public interface AsyncContext
An AsyncContext is created and initialized by a call to ServletRequest.startAsync()
or
ServletRequest.startAsync(ServletRequest, ServletResponse)
. Repeated invocations of these methods will return
the same AsyncContext instance, reinitialized as appropriate.
In the event that an asynchronous operation has timed out, the container must run through these steps:
onTimeout
method, all AsyncListener
instances registered
with the ServletRequest on which the asynchronous operation was initiated.complete()
or any of the dispatch()
methods, perform an error
dispatch with a status code equal to HttpServletResponse.SC_INTERNAL_SERVER_ERROR.complete()
or any of the
dispatch()
methods, call complete()
.Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ASYNC_CONTEXT_PATH
The name of the request attribute under which the original context path is made available to the target of a
dispatch(String) or dispatch(ServletContext,String) |
static java.lang.String |
ASYNC_MAPPING
The name of the request attribute under which the original
HttpServletMapping is made
available to the target of a dispatch(String) or dispatch(ServletContext,String) |
static java.lang.String |
ASYNC_PATH_INFO
The name of the request attribute under which the original path info is made available to the target of a
dispatch(String) or dispatch(ServletContext,String) |
static java.lang.String |
ASYNC_QUERY_STRING
The name of the request attribute under which the original query string is made available to the target of a
dispatch(String) or dispatch(ServletContext,String) |
static java.lang.String |
ASYNC_REQUEST_URI
The name of the request attribute under which the original request URI is made available to the target of a
dispatch(String) or dispatch(ServletContext,String) |
static java.lang.String |
ASYNC_SERVLET_PATH
The name of the request attribute under which the original servlet path is made available to the target of a
dispatch(String) or dispatch(ServletContext,String) |
Modifier and Type | Method and Description |
---|---|
void |
addListener(AsyncListener listener)
Registers the given
AsyncListener with the most recent asynchronous cycle that was started by a call to one
of the ServletRequest.startAsync() methods. |
void |
addListener(AsyncListener listener,
ServletRequest servletRequest,
ServletResponse servletResponse)
Registers the given
AsyncListener with the most recent asynchronous cycle that was started by a call to one
of the ServletRequest.startAsync() methods. |
void |
complete()
Completes the asynchronous operation that was started on the request that was used to initialze this AsyncContext,
closing the response that was used to initialize this AsyncContext.
|
<T extends AsyncListener> |
createListener(java.lang.Class<T> clazz)
Instantiates the given
AsyncListener class. |
void |
dispatch()
Dispatches the request and response objects of this AsyncContext to the servlet container.
|
void |
dispatch(ServletContext context,
java.lang.String path)
Dispatches the request and response objects of this AsyncContext to the given path scoped to the given
context.
|
void |
dispatch(java.lang.String path)
Dispatches the request and response objects of this AsyncContext to the given path.
|
ServletRequest |
getRequest()
Gets the request that was used to initialize this AsyncContext by calling
ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse) . |
ServletResponse |
getResponse()
Gets the response that was used to initialize this AsyncContext by calling
ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse) . |
long |
getTimeout()
Gets the timeout (in milliseconds) for this AsyncContext.
|
boolean |
hasOriginalRequestAndResponse()
Checks if this AsyncContext was initialized with the original or application-wrapped request and response objects.
|
void |
setTimeout(long timeout)
Sets the timeout (in milliseconds) for this AsyncContext.
|
void |
start(java.lang.Runnable run)
Causes the container to dispatch a thread, possibly from a managed thread pool, to run the specified
Runnable.
|
static final java.lang.String ASYNC_REQUEST_URI
dispatch(String)
or dispatch(ServletContext,String)
static final java.lang.String ASYNC_CONTEXT_PATH
dispatch(String)
or dispatch(ServletContext,String)
static final java.lang.String ASYNC_MAPPING
HttpServletMapping
is made
available to the target of a dispatch(String)
or dispatch(ServletContext,String)
static final java.lang.String ASYNC_PATH_INFO
dispatch(String)
or dispatch(ServletContext,String)
static final java.lang.String ASYNC_SERVLET_PATH
dispatch(String)
or dispatch(ServletContext,String)
static final java.lang.String ASYNC_QUERY_STRING
dispatch(String)
or dispatch(ServletContext,String)
ServletRequest getRequest()
ServletRequest.startAsync()
or
ServletRequest.startAsync(ServletRequest, ServletResponse)
.java.lang.IllegalStateException
- if complete()
or any of the dispatch()
methods has been called in the
asynchronous cycleServletResponse getResponse()
ServletRequest.startAsync()
or
ServletRequest.startAsync(ServletRequest, ServletResponse)
.java.lang.IllegalStateException
- if complete()
or any of the dispatch()
methods has been called in the
asynchronous cycleboolean hasOriginalRequestAndResponse()
This information may be used by filters invoked in the outbound direction, after a request was put into asynchronous mode, to determine whether any request and/or response wrappers that they added during their inbound invocation need to be preserved for the duration of the asynchronous operation, or may be released.
ServletRequest.startAsync()
, or if it was initialized by calling
ServletRequest.startAsync(ServletRequest, ServletResponse)
, and neither the ServletRequest nor
ServletResponse arguments carried any application-provided wrappers; false otherwisevoid dispatch()
If the asynchronous cycle was started with ServletRequest.startAsync(ServletRequest, ServletResponse)
, and
the request passed is an instance of HttpServletRequest, then the dispatch is to the URI returned by
HttpServletRequest.getRequestURI()
. Otherwise, the dispatch is to the URI of the request
when it was last dispatched by the container.
The following sequence illustrates how this will work:
// REQUEST dispatch to /url/A
AsyncContext ac = request.startAsync();
...
ac.dispatch(); // ASYNC dispatch to /url/A
// REQUEST to /url/A
// FORWARD dispatch to /url/B
request.getRequestDispatcher("/url/B").forward(request,response);
// Start async operation from within the target of the FORWARD
// dispatch
ac = request.startAsync();
...
ac.dispatch(); // ASYNC dispatch to /url/A
// REQUEST to /url/A
// FORWARD dispatch to /url/B
request.getRequestDispatcher("/url/B").forward(request,response);
// Start async operation from within the target of the FORWARD
// dispatch
ac = request.startAsync(request,response);
...
ac.dispatch(); // ASYNC dispatch to /url/B
This method returns immediately after passing the request and response objects to a container managed thread, on which the dispatch operation will be performed. If this method is called before the container-initiated dispatch that called startAsync has returned to the container, the dispatch operation will be delayed until after the container-initiated dispatch has returned to the container.
The dispatcher type of the request is set to DispatcherType.ASYNC. Unlike
forward dispatches
, the response buffer and
headers will not be reset, and it is legal to dispatch even if the response has already been committed.
Control over the request and response is delegated to the dispatch target, and the response will be closed when the
dispatch target has completed execution, unless ServletRequest.startAsync()
or
ServletRequest.startAsync(ServletRequest, ServletResponse)
are called.
Any errors or exceptions that may occur during the execution of this method must be caught and handled by the container, as follows:
onError
method, all AsyncListener
instances registered
with the ServletRequest for which this AsyncContext was created, and make the caught Throwable available via
AsyncEvent.getThrowable()
.complete()
or any of the dispatch()
methods, perform an error
dispatch with a status code equal to HttpServletResponse.SC_INTERNAL_SERVER_ERROR, and make the above
Throwable available as the value of the RequestDispatcher.ERROR_EXCEPTION request attribute.complete()
or any of the
dispatch()
methods, call complete()
.
There can be at most one asynchronous dispatch operation per asynchronous cycle, which is started by a call to one of
the ServletRequest.startAsync()
methods. Any attempt to perform an additional asynchronous dispatch operation
within the same asynchronous cycle will result in an IllegalStateException. If startAsync is subsequently called on
the dispatched request, then any of the dispatch or complete()
methods may be called.
java.lang.IllegalStateException
- if one of the dispatch methods has been called and the startAsync method has not been
called during the resulting dispatch, or if complete()
was calledServletRequest.getDispatcherType()
void dispatch(java.lang.String path)
The path parameter is interpreted in the same way as in ServletRequest.getRequestDispatcher(String)
,
within the scope of the ServletContext
from which this AsyncContext was initialized.
All path related query methods of the request must reflect the dispatch target, while the original request URI,
context path, path info, servlet path, and query string may be recovered from the ASYNC_REQUEST_URI
,
ASYNC_CONTEXT_PATH
, ASYNC_PATH_INFO
, ASYNC_SERVLET_PATH
, and ASYNC_QUERY_STRING
attributes of the request. These attributes will always reflect the original path elements, even under repeated
dispatches.
There can be at most one asynchronous dispatch operation per asynchronous cycle, which is started by a call to one of
the ServletRequest.startAsync()
methods. Any attempt to perform an additional asynchronous dispatch operation
within the same asynchronous cycle will result in an IllegalStateException. If startAsync is subsequently called on
the dispatched request, then any of the dispatch or complete()
methods may be called.
See dispatch()
for additional details, including error handling.
path
- the path of the dispatch target, scoped to the ServletContext from which this AsyncContext was
initializedjava.lang.IllegalStateException
- if one of the dispatch methods has been called and the startAsync method has not been
called during the resulting dispatch, or if complete()
was calledServletRequest.getDispatcherType()
void dispatch(ServletContext context, java.lang.String path)
The path parameter is interpreted in the same way as in ServletRequest.getRequestDispatcher(String)
,
except that it is scoped to the given context.
All path related query methods of the request must reflect the dispatch target, while the original request URI,
context path, path info, servlet path, and query string may be recovered from the ASYNC_REQUEST_URI
,
ASYNC_CONTEXT_PATH
, ASYNC_PATH_INFO
, ASYNC_SERVLET_PATH
, and ASYNC_QUERY_STRING
attributes of the request. These attributes will always reflect the original path elements, even under repeated
dispatches.
There can be at most one asynchronous dispatch operation per asynchronous cycle, which is started by a call to one of
the ServletRequest.startAsync()
methods. Any attempt to perform an additional asynchronous dispatch operation
within the same asynchronous cycle will result in an IllegalStateException. If startAsync is subsequently called on
the dispatched request, then any of the dispatch or complete()
methods may be called.
See dispatch()
for additional details, including error handling.
context
- the ServletContext of the dispatch targetpath
- the path of the dispatch target, scoped to the given ServletContextjava.lang.IllegalStateException
- if one of the dispatch methods has been called and the startAsync method has not been
called during the resulting dispatch, or if complete()
was calledServletRequest.getDispatcherType()
void complete()
Any listeners of type AsyncListener
that were registered with the ServletRequest for which this AsyncContext
was created will be invoked at their onComplete
method.
It is legal to call this method any time after a call to ServletRequest.startAsync()
or
ServletRequest.startAsync(ServletRequest, ServletResponse)
, and before a call to one of the dispatch
methods of this class. If this method is called before the container-initiated dispatch that called
startAsync has returned to the container, then the call will not take effect (and any invocations of
AsyncListener.onComplete(AsyncEvent)
will be delayed) until after the container-initiated dispatch has
returned to the container.
void start(java.lang.Runnable run)
run
- the asynchronous handlervoid addListener(AsyncListener listener)
AsyncListener
with the most recent asynchronous cycle that was started by a call to one
of the ServletRequest.startAsync()
methods.
The given AsyncListener will receive an AsyncEvent
when the asynchronous cycle completes successfully, times
out, results in an error, or a new asynchronous cycle is being initiated via one of the
ServletRequest.startAsync()
methods.
AsyncListener instances will be notified in the order in which they were added.
If ServletRequest.startAsync(ServletRequest, ServletResponse)
or ServletRequest.startAsync()
is called,
the exact same request and response objects are available from the AsyncEvent
when the AsyncListener
is notified.
listener
- the AsyncListener to be registeredjava.lang.IllegalStateException
- if this method is called after the container-initiated dispatch, during which one of
the ServletRequest.startAsync()
methods was called, has returned to the containervoid addListener(AsyncListener listener, ServletRequest servletRequest, ServletResponse servletResponse)
AsyncListener
with the most recent asynchronous cycle that was started by a call to one
of the ServletRequest.startAsync()
methods.
The given AsyncListener will receive an AsyncEvent
when the asynchronous cycle completes successfully, times
out, results in an error, or a new asynchronous cycle is being initiated via one of the
ServletRequest.startAsync()
methods.
AsyncListener instances will be notified in the order in which they were added.
The given ServletRequest and ServletResponse objects will be made available to the given AsyncListener via the
getSuppliedRequest
and getSuppliedResponse
methods, respectively, of the AsyncEvent
delivered to it. These objects should not be
read from or written to, respectively, at the time the AsyncEvent is delivered, because additional wrapping may have
occurred since the given AsyncListener was registered, but may be used in order to release any resources associated
with them.
listener
- the AsyncListener to be registeredservletRequest
- the ServletRequest that will be included in the AsyncEventservletResponse
- the ServletResponse that will be included in the AsyncEventjava.lang.IllegalStateException
- if this method is called after the container-initiated dispatch, during which one of
the ServletRequest.startAsync()
methods was called, has returned to the container<T extends AsyncListener> T createListener(java.lang.Class<T> clazz) throws ServletException
AsyncListener
class.
The returned AsyncListener instance may be further customized before it is registered with this AsyncContext via a
call to one of the addListener
methods.
The given AsyncListener class must define a zero argument constructor, which is used to instantiate it.
This method supports resource injection if the given clazz represents a Managed Bean. See the Jakarta EE platform and CDI specifications for additional details about Managed Beans and resource injection.
This method supports any annotations applicable to AsyncListener.
T
- the class of the object to instantiateclazz
- the AsyncListener class to instantiateServletException
- if the given clazz fails to be instantiatedvoid setTimeout(long timeout)
The timeout applies to this AsyncContext once the container-initiated dispatch during which one of the
ServletRequest.startAsync()
methods was called has returned to the container.
The timeout will expire if neither the complete()
method nor any of the dispatch methods are called. A timeout
value of zero or less indicates no timeout.
If setTimeout(long)
is not called, then the container's default timeout, which is available via a call to
getTimeout()
, will apply.
The default value is 30000
ms.
timeout
- the timeout in millisecondsjava.lang.IllegalStateException
- if this method is called after the container-initiated dispatch, during which one of
the ServletRequest.startAsync()
methods was called, has returned to the containerlong getTimeout()
This method returns the container's default timeout for asynchronous operations, or the timeout value passed to the
most recent invocation of setTimeout(long)
.
A timeout value of zero or less indicates no timeout.