AsyncContinuation (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

org.eclipse.jetty.server

## Class AsyncContinuation

- java.lang.Object
- - org.eclipse.jetty.server.AsyncContinuation

- All Implemented Interfaces:
    Continuation, AsyncContext

      public class AsyncContinuation
      extends Object
      implements AsyncContext, Continuation

  Implementation of Continuation and AsyncContext interfaces.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `AsyncContinuation.AsyncEventState`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected AbstractHttpConnection` | `_connection`

    - ### Fields inherited from interface org.eclipse.jetty.server.AsyncContext

      `ASYNC_CONTEXT_PATH, ASYNC_PATH_INFO, ASYNC_QUERY_STRING, ASYNC_REQUEST_URI, ASYNC_SERVLET_PATH`

    - ### Fields inherited from interface org.eclipse.jetty.continuation.Continuation

      `ATTRIBUTE`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AsyncContinuation()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addContinuationListener(ContinuationListener listener)` Add a ContinuationListener.
    `void` | `cancel()`
    `protected void` | `cancelTimeout()`
    `void` | `complete()` Complete a suspended request.
    `void` | `dispatch()`
    `void` | `dispatch(javax.servlet.ServletContext context, String path)`
    `void` | `dispatch(String path)`
    `protected void` | `doComplete()`
    `protected void` | `expired()`
    `AsyncContinuation.AsyncEventState` | `getAsyncEventState()`
    `Object` | `getAttribute(String name)` Get a request attribute.
    `Request` | `getBaseRequest()`
    `ContextHandler` | `getContextHandler()`
    `javax.servlet.ServletRequest` | `getRequest()`
    `javax.servlet.ServletResponse` | `getResponse()`
    `javax.servlet.ServletResponse` | `getServletResponse()` Get the suspended response.
    `String` | `getStatusString()`
    `long` | `getTimeout()`
    `protected boolean` | `handling()`
    `boolean` | `hasOriginalRequestAndResponse()`
    `boolean` | `isAsync()`
    `boolean` | `isAsyncStarted()`
    `boolean` | `isComplete()`
    `boolean` | `isCompleting()`
    `boolean` | `isDispatchable()`
    `boolean` | `isExpired()`
    `boolean` | `isInitial()`
    `boolean` | `isResponseWrapped()` Is the suspended response wrapped.
    `boolean` | `isResumed()`
    `boolean` | `isSuspended()`
    `boolean` | `isSuspending()`
    `protected void` | `recycle()`
    `void` | `removeAttribute(String name)` Remove a request attribute.
    `void` | `resume()` Resume a suspended request.
    `protected void` | `scheduleDispatch()`
    `protected void` | `scheduleTimeout()`
    `void` | `setAttribute(String name, Object attribute)` Set a request attribute.
    `protected void` | `setConnection(AbstractHttpConnection connection)`
    `void` | `setTimeout(long ms)` Set the continuation timeout.
    `void` | `start(Runnable run)`
    `void` | `suspend()` Suspend the processing of the request and associated `ServletResponse`.
    `protected void` | `suspend(javax.servlet.ServletContext context, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)`
    `void` | `suspend(javax.servlet.ServletResponse response)` Suspend the processing of the request and associated `ServletResponse`.
    `String` | `toString()`
    `void` | `undispatch()` Undispatch the request.
    `protected boolean` | `unhandle()` Signal that the HttpConnection has finished handling the request.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### _connection

          protected AbstractHttpConnection _connection

  - ### Constructor Detail

    - #### AsyncContinuation

          protected AsyncContinuation()

  - ### Method Detail

    - #### setConnection

          protected void setConnection(AbstractHttpConnection connection)

    - #### addContinuationListener

          public void addContinuationListener(ContinuationListener listener)

      Description copied from interface: `Continuation`
      Add a ContinuationListener.
      Specified by:
        `addContinuationListener` in interface `Continuation`
      Specified by:
        `addContinuationListener` in interface `AsyncContext`

    - #### setTimeout

          public void setTimeout(long ms)

      Description copied from interface: `Continuation`
      Set the continuation timeout.
      Specified by:
        `setTimeout` in interface `Continuation`
      Specified by:
        `setTimeout` in interface `AsyncContext`
      Parameters:
        `ms` - The time in milliseconds to wait before expiring this continuation after a call to `Continuation.suspend()` or `Continuation.suspend(ServletResponse)`. A timeout of <=0 means the continuation will never expire.

    - #### getTimeout

          public long getTimeout()

    - #### getAsyncEventState

          public AsyncContinuation.AsyncEventState getAsyncEventState()

    - #### isResponseWrapped

          public boolean isResponseWrapped()

      Description copied from interface: `Continuation`
      Is the suspended response wrapped.

      Filters that wrap the response object should check this method to determine if they should destroy/finish the wrapped response. If the request was suspended with a call to `Continuation.suspend(ServletResponse)` that passed the wrapped response, then the filter should register a `ContinuationListener` to destroy/finish the wrapped response during a call to `ContinuationListener.onComplete(Continuation)`.

      Specified by:
        `isResponseWrapped` in interface `Continuation`
      Returns:
        True if `Continuation.suspend(ServletResponse)` has been passed a `ServletResponseWrapper` instance.
      See Also:
        `Continuation.isResponseWrapped()`

    - #### isInitial

          public boolean isInitial()

      Specified by:
        `isInitial` in interface `Continuation`
      Returns:
        true while the request is within the initial dispatch to the filter chain and/or servlet. Will return false once the calling thread has returned to the container after suspend has been called and during any subsequent redispatch.

    - #### isSuspended

          public boolean isSuspended()

      Specified by:
        `isSuspended` in interface `Continuation`
      Returns:
        true after `Continuation.suspend()` has been called and before the request has been redispatched due to being resumed, completed or timed out.

    - #### isSuspending

          public boolean isSuspending()

    - #### isDispatchable

          public boolean isDispatchable()

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getStatusString

          public String getStatusString()

    - #### handling

          protected boolean handling()

      Returns:
        false if the handling of the request should not proceed

    - #### unhandle

          protected boolean unhandle()

      Signal that the HttpConnection has finished handling the request. For blocking connectors, this call may block if the request has been suspended (startAsync called).
      Returns:
        true if handling is complete, false if the request should be handled again (eg because of a resume that happened before unhandle was called)

    - #### dispatch

          public void dispatch()

      Specified by:
        `dispatch` in interface `AsyncContext`

    - #### expired

          protected void expired()

    - #### complete

          public void complete()

      Description copied from interface: `Continuation`
      Complete a suspended request.

      This method can be called by any thread that has been passed a reference to a suspended request. When a request is completed, the associated response object committed and flushed. The request is not redispatched.

      If complete is called before a suspended request is returned to the container (ie the thread that called `Continuation.suspend()` is still within the filter chain and/or servlet service method), then the complete does not take effect until the call to the filter chain and/or servlet returns to the container. In this case both `Continuation.isSuspended()` and `Continuation.isResumed()` return true.

      Typically resume() is used after a call to `Continuation.suspend(ServletResponse)` with a possibly wrapped response. The async handler should use the response provided by `Continuation.getServletResponse()` to write the response before calling `Continuation.complete()`. If the request was suspended with a call to `Continuation.suspend()` then no response object will be available via `Continuation.getServletResponse()`.

      Once complete has been called and any thread calling the filter chain and/or servlet chain has returned to the container, the request lifecycle is complete. The container is able to recycle request objects, so it is not valid hold a request or continuation reference after the end of the life cycle.

      Specified by:
        `complete` in interface `Continuation`
      Specified by:
        `complete` in interface `AsyncContext`
      See Also:
        `Continuation.suspend()`

    - #### doComplete

          protected void doComplete()

    - #### recycle

          protected void recycle()

    - #### cancel

          public void cancel()

    - #### scheduleDispatch

          protected void scheduleDispatch()

    - #### scheduleTimeout

          protected void scheduleTimeout()

    - #### cancelTimeout

          protected void cancelTimeout()

    - #### isCompleting

          public boolean isCompleting()

    - #### isComplete

          public boolean isComplete()

    - #### isAsyncStarted

          public boolean isAsyncStarted()

    - #### isAsync

          public boolean isAsync()

    - #### dispatch

          public void dispatch(javax.servlet.ServletContext context,
                      String path)

      Specified by:
        `dispatch` in interface `AsyncContext`

    - #### dispatch

          public void dispatch(String path)

      Specified by:
        `dispatch` in interface `AsyncContext`

    - #### getBaseRequest

          public Request getBaseRequest()

    - #### getRequest

          public javax.servlet.ServletRequest getRequest()

      Specified by:
        `getRequest` in interface `AsyncContext`

    - #### getResponse

          public javax.servlet.ServletResponse getResponse()

      Specified by:
        `getResponse` in interface `AsyncContext`

    - #### start

          public void start(Runnable run)

      Specified by:
        `start` in interface `AsyncContext`

    - #### hasOriginalRequestAndResponse

          public boolean hasOriginalRequestAndResponse()

      Specified by:
        `hasOriginalRequestAndResponse` in interface `AsyncContext`

    - #### getContextHandler

          public ContextHandler getContextHandler()

    - #### isResumed

          public boolean isResumed()

      Specified by:
        `isResumed` in interface `Continuation`
      Returns:
        true if the request has been redispatched by a call to `Continuation.resume()`. Returns false after any subsequent call to suspend
      See Also:
        `Continuation.isResumed()`

    - #### isExpired

          public boolean isExpired()

      Specified by:
        `isExpired` in interface `Continuation`
      Returns:
        true after a request has been redispatched as the result of a timeout. Returns false after any subsequent call to suspend.
      See Also:
        `Continuation.isExpired()`

    - #### resume

          public void resume()

      Description copied from interface: `Continuation`
      Resume a suspended request.

      This method can be called by any thread that has been passed a reference to a continuation. When called the request is redispatched to the normal filter chain and servlet processing with `Continuation.isInitial()` false.

      If resume is called before a suspended request is returned to the container (ie the thread that called `Continuation.suspend()` is still within the filter chain and/or servlet service method), then the resume does not take effect until the call to the filter chain and/or servlet returns to the container. In this case both `Continuation.isSuspended()` and `Continuation.isResumed()` return true. Multiple calls to resume are ignored.

      Typically resume() is used after a call to `Continuation.suspend()` with no arguments. The dispatch after a resume call will use the original request and response objects, even if `Continuation.suspend(ServletResponse)` had been passed a wrapped response.

      Specified by:
        `resume` in interface `Continuation`
      See Also:
        `Continuation.resume()`

    - #### suspend

          protected void suspend(javax.servlet.ServletContext context,
                     javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response)

    - #### suspend

          public void suspend(javax.servlet.ServletResponse response)

      Description copied from interface: `Continuation`
      Suspend the processing of the request and associated `ServletResponse`.

      After this method has been called, the lifecycle of the request will be extended beyond the return to the container from the `Servlet.service(ServletRequest, ServletResponse)` method and `Filter.doFilter(ServletRequest, ServletResponse, FilterChain)` calls. When a suspended request is returned to the container after a dispatch, then the container will not commit the associated response (unless an exception other than `ContinuationThrowable` is thrown).

      When the thread calling the filter chain and/or servlet has returned to the container with a suspended request, the thread is freed for other tasks and the request is held until either:

      - a call to `Continuation.resume()`.
      - a call to `Continuation.complete()`.
      - the timeout expires.

      Typically suspend with a response argument is uses when a call to `Continuation.complete()` is expected. If a call to `Continuation.resume()` is expected, then the `Continuation.suspend()` method should be used instead of this method.

      Filters that may wrap the response object should check `Continuation.isResponseWrapped()` to decide if they should destroy/finish the wrapper. If `Continuation.isResponseWrapped()` returns true, then the wrapped request has been passed to the asynchronous handler and the wrapper should not be destroyed/finished until after a call to `Continuation.complete()` (potentially using a `ContinuationListener.onComplete(Continuation)` listener).

      Specified by:
        `suspend` in interface `Continuation`
      Parameters:
        `response` - The response to return via a call to `Continuation.getServletResponse()`
      See Also:
        `Continuation.suspend()`

    - #### suspend

          public void suspend()

      Description copied from interface: `Continuation`
      Suspend the processing of the request and associated `ServletResponse`.

      After this method has been called, the lifecycle of the request will be extended beyond the return to the container from the `Servlet.service(ServletRequest, ServletResponse)` method and `Filter.doFilter(ServletRequest, ServletResponse, FilterChain)` calls. When a suspended request is returned to the container after a dispatch, then the container will not commit the associated response (unless an exception other than `ContinuationThrowable` is thrown).

      When the thread calling the filter chain and/or servlet has returned to the container with a suspended request, the thread is freed for other tasks and the request is held until either:

      - a call to `Continuation.resume()`.
      - a call to `Continuation.complete()`.
      - the timeout expires.

      Typically suspend with no arguments is uses when a call to `Continuation.resume()` is expected. If a call to `Continuation.complete()` is expected, then the `Continuation.suspend(ServletResponse)` method should be used instead of this method.

      Specified by:
        `suspend` in interface `Continuation`
      See Also:
        `Continuation.suspend()`

    - #### getServletResponse

          public javax.servlet.ServletResponse getServletResponse()

      Description copied from interface: `Continuation`
      Get the suspended response.
      Specified by:
        `getServletResponse` in interface `Continuation`
      Returns:
        the `ServletResponse` passed to `Continuation.suspend(ServletResponse)`.
      See Also:
        `Continuation.getServletResponse()`

    - #### getAttribute

          public Object getAttribute(String name)

      Description copied from interface: `Continuation`
      Get a request attribute. This method is a convenience method to call the `ServletRequest.getAttribute(String)` method on the associated request object. This is a thread safe call and may be called by any thread.
      Specified by:
        `getAttribute` in interface `Continuation`
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value
      See Also:
        `Continuation.getAttribute(java.lang.String)`

    - #### removeAttribute

          public void removeAttribute(String name)

      Description copied from interface: `Continuation`
      Remove a request attribute. This method is a convenience method to call the `ServletRequest.removeAttribute(String)` method on the associated request object. This is a thread safe call and may be called by any thread.
      Specified by:
        `removeAttribute` in interface `Continuation`
      Parameters:
        `name` - the attribute name
      See Also:
        `Continuation.removeAttribute(java.lang.String)`

    - #### setAttribute

          public void setAttribute(String name,
                          Object attribute)

      Description copied from interface: `Continuation`
      Set a request attribute. This method is a convenience method to call the `ServletRequest.setAttribute(String, Object)` method on the associated request object. This is a thread safe call and may be called by any thread.
      Specified by:
        `setAttribute` in interface `Continuation`
      Parameters:
        `name` - the attribute name
        `attribute` - the attribute value
      See Also:
        `Continuation.setAttribute(java.lang.String, java.lang.Object)`

    - #### undispatch

          public void undispatch()

      Description copied from interface: `Continuation`
      Undispatch the request.

      This method can be called on a suspended continuation in order to exit the dispatch to the filter/servlet by throwing a `ContinuationThrowable` which is caught either by the container or the `ContinuationFilter`. This is an alternative to simply returning from the dispatch in the case where filters in the filter chain may not be prepared to handle a suspended request.

      This method should only be used as a last resort and a normal return is a prefereable solution if filters can be updated to handle that case.
      Specified by:
        `undispatch` in interface `Continuation`
      See Also:
        `Continuation.undispatch()`

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.