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
`class` `AsyncContinuation.AsyncEventState`

### Field Summary

Fields
`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
`protected` `AsyncContinuation()`

### Method Summary

Methods
`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()`