org.springframework.web.context.request.async

## Interface CallableProcessingInterceptor

- All Known Implementing Classes:
    CallableProcessingInterceptorAdapter, TimeoutCallableProcessingInterceptor

      public interface CallableProcessingInterceptor

  Intercepts concurrent request handling, where the concurrent result is obtained by executing a `Callable` on behalf of the application with an `AsyncTaskExecutor`.

  A `CallableProcessingInterceptor` is invoked before and after the invocation of the `Callable` task in the asynchronous thread, as well as on timeout/error from a container thread, or after completing for any reason including a timeout or network error.

  As a general rule exceptions raised by interceptor methods will cause async processing to resume by dispatching back to the container and using the Exception instance as the concurrent result. Such exceptions will then be processed through the `HandlerExceptionResolver` mechanism.

  The `handleTimeout` method can select a value to be used to resume processing.

  Since:
    3.2
  Author:
    Rossen Stoyanchev, Rob Winch

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Object` | `RESPONSE_HANDLED` Constant indicating that the response has been handled by this interceptor without a result and that no further interceptors are to be invoked.
    `static Object` | `RESULT_NONE` Constant indicating that no result has been determined by this interceptor, giving subsequent interceptors a chance.

  - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <T> void` | `afterCompletion(NativeWebRequest request, Callable<T> task)` Invoked from a container thread when async processing completes for any reason including timeout or network error.
    `default <T> void` | `beforeConcurrentHandling(NativeWebRequest request, Callable<T> task)` Invoked before the start of concurrent handling in the original thread in which the `Callable` is submitted for concurrent handling.
    `default <T> Object` | `handleError(NativeWebRequest request, Callable<T> task, Throwable t)` Invoked from a container thread when an error occurred while processing the async request before the `Callable` task completes.
    `default <T> Object` | `handleTimeout(NativeWebRequest request, Callable<T> task)` Invoked from a container thread when the async request times out before the `Callable` task completes.
    `default <T> void` | `postProcess(NativeWebRequest request, Callable<T> task, Object concurrentResult)` Invoked after the `Callable` has produced a result in the async thread in which the `Callable` is executed.
    `default <T> void` | `preProcess(NativeWebRequest request, Callable<T> task)` Invoked after the start of concurrent handling in the async thread in which the `Callable` is executed and before the actual invocation of the `Callable`.

- - ### Field Detail

    - #### RESULT_NONE

          static final Object RESULT_NONE

      Constant indicating that no result has been determined by this interceptor, giving subsequent interceptors a chance.
      See Also:
        `handleTimeout(org.springframework.web.context.request.NativeWebRequest, java.util.concurrent.Callable<T>)`, `handleError(org.springframework.web.context.request.NativeWebRequest, java.util.concurrent.Callable<T>, java.lang.Throwable)`

    - #### RESPONSE_HANDLED

          static final Object RESPONSE_HANDLED

      Constant indicating that the response has been handled by this interceptor without a result and that no further interceptors are to be invoked.
      See Also:
        `handleTimeout(org.springframework.web.context.request.NativeWebRequest, java.util.concurrent.Callable<T>)`, `handleError(org.springframework.web.context.request.NativeWebRequest, java.util.concurrent.Callable<T>, java.lang.Throwable)`

  - ### Method Detail

    - #### beforeConcurrentHandling

          default <T> void beforeConcurrentHandling(NativeWebRequest request,
                                                    Callable<T> task)
                                             throws Exception

      Invoked before the start of concurrent handling in the original thread in which the `Callable` is submitted for concurrent handling.

      This is useful for capturing the state of the current thread just prior to invoking the `Callable`. Once the state is captured, it can then be transferred to the new `Thread` in `preProcess(NativeWebRequest, Callable)`. Capturing the state of Spring Security's SecurityContextHolder and migrating it to the new Thread is a concrete example of where this is useful.

      The default implementation is empty.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
      Throws:
        `Exception` - in case of errors

    - #### preProcess

          default <T> void preProcess(NativeWebRequest request,
                                      Callable<T> task)
                               throws Exception

      Invoked after the start of concurrent handling in the async thread in which the `Callable` is executed and before the actual invocation of the `Callable`.

      The default implementation is empty.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
      Throws:
        `Exception` - in case of errors

    - #### postProcess

          default <T> void postProcess(NativeWebRequest request,
                                       Callable<T> task,
                                       Object concurrentResult)
                                throws Exception

      Invoked after the `Callable` has produced a result in the async thread in which the `Callable` is executed. This method may be invoked later than `afterTimeout` or `afterCompletion` depending on when the `Callable` finishes processing.

      The default implementation is empty.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
        `concurrentResult` - the result of concurrent processing, which could be a `Throwable` if the `Callable` raised an exception
      Throws:
        `Exception` - in case of errors

    - #### handleTimeout

          default <T> Object handleTimeout(NativeWebRequest request,
                                           Callable<T> task)
                                    throws Exception

      Invoked from a container thread when the async request times out before the `Callable` task completes. Implementations may return a value, including an `Exception`, to use instead of the value the `Callable` did not return in time.

      The default implementation always returns `RESULT_NONE`.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
      Returns:
        a concurrent result value; if the value is anything other than `RESULT_NONE` or `RESPONSE_HANDLED`, concurrent processing is resumed and subsequent interceptors are not invoked
      Throws:
        `Exception` - in case of errors

    - #### handleError

          default <T> Object handleError(NativeWebRequest request,
                                         Callable<T> task,
                                         Throwable t)
                                  throws Exception

      Invoked from a container thread when an error occurred while processing the async request before the `Callable` task completes. Implementations may return a value, including an `Exception`, to use instead of the value the `Callable` did not return in time.

      The default implementation always returns `RESULT_NONE`.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
        `t` - the error that occurred while request processing
      Returns:
        a concurrent result value; if the value is anything other than `RESULT_NONE` or `RESPONSE_HANDLED`, concurrent processing is resumed and subsequent interceptors are not invoked
      Throws:
        `Exception` - in case of errors
      Since:
        5.0

    - #### afterCompletion

          default <T> void afterCompletion(NativeWebRequest request,
                                           Callable<T> task)
                                    throws Exception

      Invoked from a container thread when async processing completes for any reason including timeout or network error.

      The default implementation is empty.

      Parameters:
        `request` - the current request
        `task` - the task for the current async request
      Throws:
        `Exception` - in case of errors