org.springframework.web.context.request.async

Class WebAsyncManager

java.lang.Object

org.springframework.web.context.request.async.WebAsyncManager

public final class WebAsyncManager
extends java.lang.Object

The central class for managing asynchronous request processing, mainly intended as an SPI and not typically used directly by application classes.

An async scenario starts with request processing as usual in a thread (T1). Concurrent request handling can be innitiated by calling startCallableProcessing or startDeferredResultProcessing both of which produce a result in a separate thread (T2). The result is saved and the request dispatched to the container, to resume processing with the saved result in a third thread (T3). Within the dispatched thread (T3), the saved result can be accessed via getConcurrentResult() or its presence detected via hasConcurrentResult().

TODO .. Servlet 3 config

Since:

3.2

Author:

Rossen Stoyanchev

See Also:

AsyncWebRequestInterceptor, AsyncHandlerInterceptor, OncePerRequestFilter.shouldFilterAsyncDispatches(), OncePerRequestFilter.isAsyncDispatch(javax.servlet.http.HttpServletRequest), OncePerRequestFilter.isLastRequestThread(javax.servlet.http.HttpServletRequest)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	WebAsyncManager.WebAsyncThreadInitializer Initialize and reset thread-bound variables.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearConcurrentResult() Clear concurrentResult and concurrentResultContext.
java.lang.Object	getConcurrentResult() Provides access to the result from concurrent handling.
java.lang.Object[]	getConcurrentResultContext() Provides access to additional processing context saved at the start of concurrent handling.
boolean	hasConcurrentResult() Whether the request has been dispatched to process the result of concurrent handling.
boolean	initializeAsyncThread(java.lang.Object key) Invoke the initialize() method of the named WebAsyncManager.WebAsyncThreadInitializer.
boolean	isConcurrentHandlingStarted() Whether the selected handler for the current request chose to handle the request asynchronously.
void	registerAsyncThreadInitializer(java.lang.Object key, WebAsyncManager.WebAsyncThreadInitializer initializer) Register an WebAsyncManager.WebAsyncThreadInitializer for the current request.
void	setAsyncWebRequest(AsyncWebRequest asyncWebRequest) Configure the AsyncWebRequest to use.
void	setTaskExecutor(AsyncTaskExecutor taskExecutor) Configure an AsyncTaskExecutor for use with concurrent processing via startCallableProcessing(Callable, Object...).
void	startCallableProcessing(AsyncTask asyncTask, java.lang.Object... processingContext) Use the given AsyncTask to configure the task executor as well as the timeout value of the AsyncWebRequest before delegating to startCallableProcessing(Callable, Object...).
void	startCallableProcessing(java.util.concurrent.Callable<?> callable, java.lang.Object... processingContext) Start concurrent request processing and execute the given task with an AsyncTaskExecutor.
void	startDeferredResultProcessing(DeferredResult<?> deferredResult, java.lang.Object... processingContext) Start concurrent request processing and initialize the given DeferredResult with a DeferredResult.DeferredResultHandler that saves the result and dispatches the request to resume processing of that result.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setAsyncWebRequest

public void setAsyncWebRequest(AsyncWebRequest asyncWebRequest)

Configure the AsyncWebRequest to use. This property may be set more than once during a single request to accurately reflect the current state of the request (e.g. following a forward, request/response wrapping, etc). However, it should not be set while concurrent handling is in progress, i.e. while isConcurrentHandlingStarted() is true.

Parameters:

asyncWebRequest - the web request to use

setTaskExecutor

public void setTaskExecutor(AsyncTaskExecutor taskExecutor)

Configure an AsyncTaskExecutor for use with concurrent processing via startCallableProcessing(Callable, Object...).

By default a SimpleAsyncTaskExecutor instance is used.

isConcurrentHandlingStarted

public boolean isConcurrentHandlingStarted()

Whether the selected handler for the current request chose to handle the request asynchronously. A return value of "true" indicates concurrent handling is under way and the response will remain open. A return value of "false" means concurrent handling was either not started or possibly that it has completed and the request was dispatched for further processing of the concurrent result.

hasConcurrentResult

public boolean hasConcurrentResult()

Whether the request has been dispatched to process the result of concurrent handling.

getConcurrentResult

public java.lang.Object getConcurrentResult()

Provides access to the result from concurrent handling.

Returns:

an Object, possibly an Exception or Throwable if concurrent handling raised one.

getConcurrentResultContext

public java.lang.Object[] getConcurrentResultContext()

Provides access to additional processing context saved at the start of concurrent handling.

clearConcurrentResult

public void clearConcurrentResult()

Clear concurrentResult and concurrentResultContext.

startCallableProcessing

public void startCallableProcessing(java.util.concurrent.Callable<?> callable,
                           java.lang.Object... processingContext)

Start concurrent request processing and execute the given task with an AsyncTaskExecutor. The result from the task execution is saved and the request dispatched in order to resume processing of that result. If the task raises an Exception then the saved result will be the raised Exception.

Parameters:

callable - a unit of work to be executed asynchronously

processingContext - additional context to save that can be accessed via getConcurrentResultContext()

See Also:

getConcurrentResult(), getConcurrentResultContext()

startCallableProcessing

public void startCallableProcessing(AsyncTask asyncTask,
                           java.lang.Object... processingContext)

Use the given AsyncTask to configure the task executor as well as the timeout value of the AsyncWebRequest before delegating to startCallableProcessing(Callable, Object...).

Parameters:

asyncTask - an asyncTask containing the target Callable

processingContext - additional context to save that can be accessed via getConcurrentResultContext()

startDeferredResultProcessing

public void startDeferredResultProcessing(DeferredResult<?> deferredResult,
                                 java.lang.Object... processingContext)

Start concurrent request processing and initialize the given DeferredResult with a DeferredResult.DeferredResultHandler that saves the result and dispatches the request to resume processing of that result. The AsyncWebRequest is also updated with a completion handler that expires the DeferredResult and a timeout handler assuming the DeferredResult has a default timeout result.

Parameters:

deferredResult - the DeferredResult instance to initialize

processingContext - additional context to save that can be accessed via getConcurrentResultContext()

See Also:

getConcurrentResult(), getConcurrentResultContext()

registerAsyncThreadInitializer

public void registerAsyncThreadInitializer(java.lang.Object key,
                                  WebAsyncManager.WebAsyncThreadInitializer initializer)

Register an WebAsyncManager.WebAsyncThreadInitializer for the current request. It may later be accessed and applied via #initializeAsyncThread(String) and will also be used to initialize and reset threads for concurrent handler execution.

Parameters:

key - a unique the key under which to keep the initializer

initializer - the initializer instance

initializeAsyncThread

public boolean initializeAsyncThread(java.lang.Object key)

Invoke the initialize() method of the named WebAsyncManager.WebAsyncThreadInitializer.

Parameters:

key - the key under which the initializer was registered

Returns:

whether an initializer was found and applied