DRAFT

javax.servlet
Interface AsyncContext


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.

Since:
Servlet 3.0

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

ASYNC_REQUEST_URI

static final 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)

See Also:
Constant Field Values

ASYNC_CONTEXT_PATH

static final 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)

See Also:
Constant Field Values

ASYNC_PATH_INFO

static final 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)

See Also:
Constant Field Values

ASYNC_SERVLET_PATH

static final 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)

See Also:
Constant Field Values

ASYNC_QUERY_STRING

static final 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)

See Also:
Constant Field Values
Method Detail

getRequest

ServletRequest getRequest()
Gets the request that was used to initialize this AsyncContext by calling ServletRequest#startAsync() or ServletRequest#startAsync(ServletRequest, ServletResponse).

Returns:
the request that was used to initialize this AsyncContext

getResponse

ServletResponse getResponse()
Gets the response that was used to initialize this AsyncContext by calling ServletRequest#startAsync() or ServletRequest#startAsync(ServletRequest, ServletResponse).

Returns:
the response that was used to initialize this AsyncContext

hasOriginalRequestAndResponse

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).

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.

Returns:
true if this AsyncContext was initialized with the original request and response objects by calling ServletRequest#startAsync(), and false if it was initialized with wrapped request and/or response objects using ServletRequest#startAsync(ServletRequest, ServletResponse).

dispatch

void dispatch()
Dispatches the request and response objects of this AsyncContext to the servlet container.

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.

Throws:
IllegalStateException - if complete() has already been called
See Also:
ServletRequest#getDispatcherType

dispatch

void dispatch(java.lang.String path)
Dispatches the request and response objects of this AsyncContext to the given 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.

Parameters:
path - the path of the dispatch target, scoped to the ServletContext from which this AsyncContext was initialized
Throws:
IllegalStateException - if complete() has already been called
See Also:
ServletRequest#getDispatcherType

dispatch

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.

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.

Parameters:
context - the ServletContext of the dispatch target
path - the path of the dispatch target, scoped to the given ServletContext
Throws:
IllegalStateException - if complete() has already been called
See Also:
ServletRequest#getDispatcherType

complete

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.

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.


start

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.

Parameters:
run - the asynchronous handler

DRAFT

Submit a bug or feature

Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.