|
DRAFT | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface AsyncContext
Class representing the execution context for an asynchronous operation that was started on a ServletRequest.
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.
Field Summary | |
---|---|
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_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) |
Method Summary | |
---|---|
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. |
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) . |
boolean |
hasOriginalRequestAndResponse()
Checks if this AsyncContext was initialized with the original request and response objects by calling ServletRequest#startAsync() , or if it was initialized
with wrapped request and/or response objects using
ServletRequest#startAsync(ServletRequest, ServletResponse) . |
void |
start(java.lang.Runnable run)
Causes the container to dispatch a thread to run the specified Runnable in the ServletContext that initialized this AsyncContext. |
Field Detail |
---|
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_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)
Method Detail |
---|
ServletRequest getRequest()
ServletRequest#startAsync()
or
ServletRequest#startAsync(ServletRequest, ServletResponse)
.
ServletResponse getResponse()
ServletRequest#startAsync()
or
ServletRequest#startAsync(ServletRequest, ServletResponse)
.
boolean hasOriginalRequestAndResponse()
ServletRequest#startAsync()
, or if it was initialized
with wrapped request and/or response objects using
ServletRequest#startAsync(ServletRequest, ServletResponse)
.
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()
, and false if it was initialized
with wrapped request and/or response objects using
ServletRequest#startAsync(ServletRequest, ServletResponse)
.void dispatch()
If the asynchronous cycle was started with
ServletRequest#startAsync(ServletRequest, ServletResponse)
then the dispatch is to the URI of the request passed to startAsync.
If the asynchronous cycle was started with
ServletRequest#startAsync()
, then 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
// FORWARD dispatch to /url/B
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
// FORWARD dispatch to /url/B
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.
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.
IllegalStateException
- if complete()
has already
been 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.
See dispatch()
for additional details.
path
- the path of the dispatch target, scoped to the
ServletContext from which this AsyncContext was initialized
IllegalStateException
- if complete()
has already
been 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.
See dispatch()
for additional details.
context
- the ServletContext of the dispatch targetpath
- the path of the dispatch target, scoped to the given
ServletContext
IllegalStateException
- if complete()
has already
been calledServletRequest#getDispatcherType
void complete()
Any listeners of type AsyncListener
that were added to the
request that was used to initialize this AsyncContext will have their
AsyncListener#onComplete(AsyncEvent)
method invoked.
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)
ServletContext
that initialized this AsyncContext.
run
- the asynchronous handler
|
DRAFT | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.