javax.servlet

## Interface AsyncContext

-     public interface AsyncContext

  Class representing the execution context for an asynchronous operation that was initiated 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.

  In the event that an asynchronous operation has timed out, the container must run through these steps:

  1. Invoke, at their `onTimeout` method, all `AsyncListener` instances registered with the ServletRequest on which the asynchronous operation was initiated.
  2. If none of the listeners called `complete()` or any of the `dispatch()` methods, perform an error dispatch with a status code equal to `HttpServletResponse.SC_INTERNAL_SERVER_ERROR`.
  3. If no matching error page was found, or the error page did not call `complete()` or any of the `dispatch()` methods, call `complete()`.
  Since:
    Servlet 3.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static 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 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 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 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 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

    Methods
    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> T` | `createListener(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, String path)` Dispatches the request and response objects of this AsyncContext to the given `path` scoped to the given `context`.
    `void` | `dispatch(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(Runnable run)` Causes the container to dispatch a thread, possibly from a managed thread pool, to run the specified `Runnable`.

- - ### Field Detail

    - #### ASYNC_REQUEST_URI

          static final 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 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 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 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 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
      Throws:
        `IllegalStateException` - if `complete()` or any of the `dispatch()` methods has been called in the asynchronous cycle

    - #### 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
      Throws:
        `IllegalStateException` - if `complete()` or any of the `dispatch()` methods has been called in the asynchronous cycle

    - #### hasOriginalRequestAndResponse

          boolean hasOriginalRequestAndResponse()

      Checks if this AsyncContext was initialized with the original or application-wrapped request and response objects.

      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()`, or if it was initialized by calling `ServletRequest.startAsync(ServletRequest, ServletResponse)`, and neither the ServletRequest nor ServletResponse arguments carried any application-provided wrappers; false otherwise

    - #### 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)`, 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:

      1. Invoke, at their `onError` method, all `AsyncListener` instances registered with the ServletRequest for which this AsyncContext was created, and make the caught `Throwable` available via `AsyncEvent.getThrowable()`.
      2. If none of the listeners called `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.
      3. If no matching error page was found, or the error page did not call `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.

      Throws:
        `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 called
      See Also:
        `ServletRequest.getDispatcherType()`

    - #### dispatch

          void dispatch(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.

      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.

      Parameters:
        `path` - the path of the dispatch target, scoped to the ServletContext from which this AsyncContext was initialized
      Throws:
        `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 called
      See Also:
        `ServletRequest.getDispatcherType()`

    - #### dispatch

          void dispatch(ServletContext context,
                      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.

      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.

      Parameters:
        `context` - the ServletContext of the dispatch target
        `path` - the path of the dispatch target, scoped to the given ServletContext
      Throws:
        `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 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 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.

    - #### start

          void start(Runnable run)

      Causes the container to dispatch a thread, possibly from a managed thread pool, to run the specified `Runnable`. The container may propagate appropriate contextual information to the `Runnable`.
      Parameters:
        `run` - the asynchronous handler

    - #### addListener

          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.

      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.

      Parameters:
        `listener` - the AsyncListener to be registered
      Throws:
        `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

    - #### addListener

          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.

      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.

      Parameters:
        `listener` - the AsyncListener to be registered
        `servletRequest` - the ServletRequest that will be included in the AsyncEvent
        `servletResponse` - the ServletResponse that will be included in the AsyncEvent
      Throws:
        `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

    - #### createListener

          <T extends AsyncListener> T createListener(Class<T> clazz)
                                                 throws ServletException

      Instantiates the given `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 Java EE platform and JSR 299 specifications for additional details about Managed Beans and resource injection.

      This method supports any annotations applicable to AsyncListener.

      Parameters:
        `clazz` - the AsyncListener class to instantiate
      Returns:
        the new AsyncListener instance
      Throws:
        `ServletException` - if the given `clazz` fails to be instantiated

    - #### setTimeout

          void setTimeout(long timeout)

      Sets the timeout (in milliseconds) for this AsyncContext.

      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.

      Parameters:
        `timeout` - the timeout in milliseconds
      Throws:
        `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

    - #### getTimeout

          long getTimeout()

      Gets the timeout (in milliseconds) for this AsyncContext.

      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.

      Returns:
        the timeout in milliseconds

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.