AsyncContext (Servlet 6.1 API Documentation - Apache Tomcat 11.0.25)
Description: declaration: package: jakarta.servlet, interface: AsyncContext

# Interface AsyncContext

public interface AsyncContext
Provides the context for asynchronous request handling

Since:
  Servlet 3.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ASYNC_CONTEXT_PATH`
  The attribute name for the Context Path of the async request
  `static final String`
  `ASYNC_MAPPING`
  The attribute name for the Mapping of the async request
  `static final String`
  `ASYNC_PATH_INFO`
  The attribute name for the Path Info of the async request
  `static final String`
  `ASYNC_QUERY_STRING`
  The attribute name for the Query String of the async request
  `static final String`
  `ASYNC_REQUEST_URI`
  The attribute name for the URI of the async request
  `static final String`
  `ASYNC_SERVLET_PATH`
  The attribute name for the Servlet Path of the async request

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(AsyncListener listener)`
  Adds an event listener that will be called for different AsyncEvents fire
  `void`
  `addListener(AsyncListener listener, ServletRequest request, ServletResponse response)`
  Adds an event listener that will be called when different AsyncEvents fire
  `void`
  `complete()`
  Completes the async request processing and closes the response stream
  `<T extends AsyncListener>
  T`
  `createListener(Class<T> clazz)`
  Creates and returns an AsyncListener object
  `void`
  `dispatch()`
  Dispatches the request to the resource at the original request URI, as specified in the original request.
  `void`
  `dispatch(ServletContext context, String path)`
  Dispatches the request to the resource at the specified path relative to the given `ServletContext`.
  `void`
  `dispatch(String path)`
  Dispatches the request to the resource at the specified path relative to the `ServletContext` from which this async request was started.
  `ServletRequest`
  `getRequest()`
  Returns the `ServletRequest` associated with this asynchronous operation.
  `ServletResponse`
  `getResponse()`
  Returns the `ServletResponse` associated with this asynchronous operation.
  `long`
  `getTimeout()`
  Get the current timeout.
  `boolean`
  `hasOriginalRequestAndResponse()`
  Determines whether the request and response objects are the original ones passed to `ServletRequest.startAsync()`, or if they are new objects created by the container.
  `void`
  `setTimeout(long timeout)`
  Set the timeout.
  `void`
  `start(Runnable run)`
  Starts a new thread to process the asynchronous request

- ## Field Details

  - ### ASYNC_REQUEST_URI

    static final String ASYNC_REQUEST_URI
    The attribute name for the URI of the async request
    See Also:
      - Constant Field Values

  - ### ASYNC_CONTEXT_PATH

    static final String ASYNC_CONTEXT_PATH
    The attribute name for the Context Path of the async request
    See Also:
      - Constant Field Values

  - ### ASYNC_MAPPING

    static final String ASYNC_MAPPING
    The attribute name for the Mapping of the async request
    See Also:
      - Constant Field Values

  - ### ASYNC_PATH_INFO

    static final String ASYNC_PATH_INFO
    The attribute name for the Path Info of the async request
    See Also:
      - Constant Field Values

  - ### ASYNC_SERVLET_PATH

    static final String ASYNC_SERVLET_PATH
    The attribute name for the Servlet Path of the async request
    See Also:
      - Constant Field Values

  - ### ASYNC_QUERY_STRING

    static final String ASYNC_QUERY_STRING
    The attribute name for the Query String of the async request
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getRequest

    ServletRequest getRequest()
    Returns the `ServletRequest` associated with this asynchronous operation.
    Returns:
      the ServletRequest object

  - ### getResponse

    ServletResponse getResponse()
    Returns the `ServletResponse` associated with this asynchronous operation.
    Returns:
      the ServletResponse object

  - ### hasOriginalRequestAndResponse

    boolean hasOriginalRequestAndResponse()
    Determines whether the request and response objects are the original ones passed to `ServletRequest.startAsync()`, or if they are new objects created by the container.
    Returns:
      `true` if the request and response are the original objects, `false` otherwise

  - ### dispatch

    void dispatch()
    Dispatches the request to the resource at the original request URI, as specified in the original request. After the dispatch, the async request processing is complete and the response is committed.
    Throws:
      `IllegalStateException` - if this method is called when the request is not in asynchronous mode. The request is in asynchronous mode after `ServletRequest.startAsync()` or `ServletRequest.startAsync(ServletRequest, ServletResponse)` has been called and before `complete()` or any other dispatch() method has been called.

  - ### dispatch

    void dispatch(String path)
    Dispatches the request to the resource at the specified path relative to the `ServletContext` from which this async request was started. After the dispatch, the async request processing is complete and the response is committed.
    Parameters:
      `path` - the path to which the request/response should be dispatched relative to the `ServletContext` from which this async request was started
    Throws:
      `IllegalStateException` - if this method is called when the request is not in asynchronous mode. The request is in asynchronous mode after `ServletRequest.startAsync()` or `ServletRequest.startAsync(ServletRequest, ServletResponse)` has been called and before `complete()` or any other dispatch() method has been called.

  - ### dispatch

    void dispatch(ServletContext context, String path)
    Dispatches the request to the resource at the specified path relative to the given `ServletContext`. After the dispatch, the async request processing is complete and the response is committed.
    Parameters:
      `context` - the `ServletContext` to which the request/response should be dispatched
      `path` - the path to which the request/response should be dispatched relative to the specified `ServletContext`
    Throws:
      `IllegalStateException` - if this method is called when the request is not in asynchronous mode. The request is in asynchronous mode after `ServletRequest.startAsync()` or `ServletRequest.startAsync(ServletRequest, ServletResponse)` has been called and before `complete()` or any other dispatch() method has been called.

  - ### complete

    void complete()
    Completes the async request processing and closes the response stream

  - ### start

    void start(Runnable run)
    Starts a new thread to process the asynchronous request
    Parameters:
      `run` - a Runnable that the new thread will run

  - ### addListener

    void addListener(AsyncListener listener)
    Adds an event listener that will be called for different AsyncEvents fire
    Parameters:
      `listener` - an AsyncListener that will be called with AsyncEvent objects

  - ### addListener

    void addListener(AsyncListener listener, ServletRequest request, ServletResponse response)
    Adds an event listener that will be called when different AsyncEvents fire
    Parameters:
      `listener` - an AsyncListener that will be called with AsyncEvent objects
      `request` - the ServletRequest that will be passed with the AsyncEvent
      `response` - the ServletResponse that will be passed with the AsyncEvent

  - ### createListener

    <T extends AsyncListener> T createListener(Class<T> clazz) throws ServletException
    Creates and returns an AsyncListener object
    Type Parameters:
      `T` - The type to create that extends AsyncListener
    Parameters:
      `clazz` - The class to instantiate to create the listener
    Returns:
      the newly created AsyncListener object
    Throws:
      `ServletException` - if the listener cannot be created

  - ### setTimeout

    void setTimeout(long timeout)
    Set the timeout.
    Parameters:
      `timeout` - The timeout in milliseconds. 0 or less indicates no timeout.

  - ### getTimeout

    long getTimeout()
    Get the current timeout.
    Returns:
      The timeout in milliseconds. 0 or less indicates no timeout.