All Known Subinterfaces:

ContinuationFilter.FilteredContinuation

All Known Implementing Classes:

Servlet3Continuation
```
@Deprecated
public interface Continuation
```
Deprecated.
use Servlet 3.0 AsyncContext instead
Continuation.
A continuation is a mechanism by which an HTTP Request can be suspended and restarted after a timeout or an asynchronous event has occurred.
The continuation mechanism is a portable mechanism that will work asynchronously without additional configuration of all jetty-7, jetty-8 and Servlet 3.0 containers. With the addition of the ContinuationFilter, the mechanism will also work asynchronously on jetty-6 and non-asynchronously on any servlet 2.5 container.
The Continuation API is a simplification of the richer async API provided by the servlet-3.0 and an enhancement of the continuation API that was introduced with jetty-6.

Continuation Usage

A continuation object is obtained for a request by calling the factory method ContinuationSupport.getContinuation(ServletRequest). The continuation type returned will depend on the servlet container being used.

There are two distinct style of operation of the continuation API.

Suspend/Resume Usage

The suspend/resume style is used when a servlet and/or filter is used to generate the response after a asynchronous wait that is terminated by an asynchronous handler.
```
 Filter/Servlet:
   // if we need to get asynchronous results
   Object results = request.getAttribute("results);
   if (results==null)
   {
     Continuation continuation = ContinuationSupport.getContinuation(request);
     continuation.suspend();
     myAsyncHandler.register(continuation);
     return; // or continuation.undispatch();
   }

 async wait ...

 Async Handler:
   // when the waited for event happens
   continuation.setAttribute("results",event);
   continuation.resume();

 Filter/Servlet:
   // when the request is redispatched
   if (results==null)
   {
     ... // see above
   }
   else
   {
     response.getOutputStream().write(process(results));
   }
 
```
Suspend/Complete Usage

The suspend/complete style is used when an asynchronous handler is used to generate the response:
```
 Filter/Servlet:
   // when we want to enter asynchronous mode
   Continuation continuation = ContinuationSupport.getContinuation(request);
   continuation.suspend(response); // response may be wrapped
   myAsyncHandler.register(continuation);
   return; // or continuation.undispatch();

 Wrapping Filter:
   // any filter that had wrapped the response should be implemented like:
   try
   {
     chain.doFilter(request,wrappedResponse);
   }
   finally
   {
     if (!continuation.isResponseWrapped())
       wrappedResponse.finish()
     else
       continuation.addContinuationListener(myCompleteListener)
   }

 async wait ...

 Async Handler:
   // when the async event happens
   continuation.getServletResponse().getOutputStream().write(process(event));
   continuation.complete()
 
```
Continuation Timeout

If a continuation is suspended, but neither complete() or resume() is called during the period set by setTimeout(long), then the continuation will expire and isExpired() will return true.

When a continuation expires, the ContinuationListener.onTimeout(Continuation) method is called on any ContinuationListener that has been registered via the addContinuationListener(ContinuationListener) method. The onTimeout handlers may write a response and call complete(). If complete() is not called, then the container will redispatch the request as if resume() had been called, except that isExpired() will be true and isResumed() will be false.
See Also:

ContinuationSupport, ContinuationListener

Field Summary

Fields
Modifier and Type Field Description

static java.lang.String ATTRIBUTE
Deprecated.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`addContinuationListener(ContinuationListener listener)`	Deprecated. Add a ContinuationListener.
`void`	`complete()`	Deprecated. Complete a suspended request.
`java.lang.Object`	`getAttribute(java.lang.String name)`	Deprecated. Get a request attribute.
`javax.servlet.ServletResponse`	`getServletResponse()`	Deprecated. Get the suspended response.
`boolean`	`isExpired()`	Deprecated.
`boolean`	`isInitial()`	Deprecated.
`boolean`	`isResponseWrapped()`	Deprecated. Is the suspended response wrapped.
`boolean`	`isResumed()`	Deprecated.
`boolean`	`isSuspended()`	Deprecated.
`void`	`removeAttribute(java.lang.String name)`	Deprecated. Remove a request attribute.
`void`	`resume()`	Deprecated. Resume a suspended request.
`void`	`setAttribute(java.lang.String name, java.lang.Object attribute)`	Deprecated. Set a request attribute.
`void`	`setTimeout(long timeoutMs)`	Deprecated. Set the continuation timeout.
`void`	`suspend()`	Deprecated. Suspend the processing of the request and associated `ServletResponse`.
`void`	`suspend(javax.servlet.ServletResponse response)`	Deprecated. Suspend the processing of the request and associated `ServletResponse`.
`void`	`undispatch()`	Deprecated. Undispatch the request.

- Field Detail
  - ATTRIBUTE
```
static final java.lang.String ATTRIBUTE
```
    Deprecated.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - setTimeout
```
void setTimeout(long timeoutMs)
```
    Deprecated.
    
    Set the continuation timeout.
    
    Parameters:
    
    timeoutMs - The time in milliseconds to wait before expiring this continuation after a call to suspend() or suspend(ServletResponse). A timeout of <=0 means the continuation will never expire.
  - suspend
```
void suspend()
```
    Deprecated.
    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 resume().
    
    a call to complete().
    
    the timeout expires.
    
    Typically suspend with no arguments is uses when a call to resume() is expected. If a call to complete() is expected, then the suspend(ServletResponse) method should be used instead of this method.
    Throws:
    
    java.lang.IllegalStateException - If the request cannot be suspended
  - suspend
```
void suspend(javax.servlet.ServletResponse response)
```
    Deprecated.
    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 resume().
    
    a call to complete().
    
    the timeout expires.
    
    Typically suspend with a response argument is uses when a call to complete() is expected. If a call to resume() is expected, then the suspend() method should be used instead of this method.
    
    Filters that may wrap the response object should check isResponseWrapped() to decide if they should destroy/finish the wrapper. If 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 complete() (potentially using a ContinuationListener.onComplete(Continuation) listener).
    Parameters:
    
    response - The response to return via a call to getServletResponse()
    
    Throws:
    
    java.lang.IllegalStateException - If the request cannot be suspended
  - resume
```
void resume()
```
    Deprecated.
    
    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 isInitial() false.
    
    If resume is called before a suspended request is returned to the container (ie the thread that called 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 isSuspended() and isResumed() return true. Multiple calls to resume are ignored.
    
    Typically resume() is used after a call to suspend() with no arguments. The dispatch after a resume call will use the original request and response objects, even if suspend(ServletResponse) had been passed a wrapped response.
    
    Throws:
    
    java.lang.IllegalStateException - if the request is not suspended.
    
    See Also:
    
    suspend()
  - complete
```
void complete()
```
    Deprecated.
    
    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 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 isSuspended() and isResumed() return true.
    
    Typically resume() is used after a call to suspend(ServletResponse) with a possibly wrapped response. The async handler should use the response provided by getServletResponse() to write the response before calling complete(). If the request was suspended with a call to suspend() then no response object will be available via 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.
    
    Throws:
    
    java.lang.IllegalStateException - if the request is not suspended.
    
    See Also:
    
    suspend()
  - isSuspended
```
boolean isSuspended()
```
    Deprecated.
    
    Returns:
    
    true after suspend() has been called and before the request has been redispatched due to being resumed, completed or timed out.
  - isResumed
```
boolean isResumed()
```
    Deprecated.
    
    Returns:
    
    true if the request has been redispatched by a call to resume(). Returns false after any subsequent call to suspend
  - isExpired
```
boolean isExpired()
```
    Deprecated.
    
    Returns:
    
    true after a request has been redispatched as the result of a timeout. Returns false after any subsequent call to suspend.
  - isInitial
```
boolean isInitial()
```
    Deprecated.
    
    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.
  - isResponseWrapped
```
boolean isResponseWrapped()
```
    Deprecated.
    
    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 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).
    
    Returns:
    
    True if suspend(ServletResponse) has been passed a ServletResponseWrapper instance.
  - getServletResponse
```
javax.servlet.ServletResponse getServletResponse()
```
    Deprecated.
    
    Get the suspended response.
    
    Returns:
    
    the ServletResponse passed to suspend(ServletResponse).
  - addContinuationListener
```
void addContinuationListener(ContinuationListener listener)
```
    Deprecated.
    
    Add a ContinuationListener.
    
    Parameters:
    
    listener - the listener
  - setAttribute
```
void setAttribute(java.lang.String name,
                  java.lang.Object attribute)
```
    Deprecated.
    
    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.
    
    Parameters:
    
    name - the attribute name
    
    attribute - the attribute value
  - getAttribute
```
java.lang.Object getAttribute(java.lang.String name)
```
    Deprecated.
    
    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.
    
    Parameters:
    
    name - the attribute name
    
    Returns:
    
    the attribute value
  - removeAttribute
```
void removeAttribute(java.lang.String name)
```
    Deprecated.
    
    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.
    
    Parameters:
    
    name - the attribute name
  - undispatch
```
void undispatch()
         throws ContinuationThrowable
```
    Deprecated.
    
    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.
    
    Throws:
    
    ContinuationThrowable - thrown if the request is suspended. The instance of the exception may be reused on subsequent calls, so the stack frame may not be accurate.

Interface Continuation

Continuation Usage

Suspend/Resume Usage

Suspend/Complete Usage

Continuation Timeout

Field Summary

Method Summary

Field Detail

ATTRIBUTE

Method Detail

setTimeout

suspend

suspend

resume

complete

isSuspended

isResumed

isExpired

isInitial

isResponseWrapped

getServletResponse

addContinuationListener

setAttribute

getAttribute

removeAttribute

undispatch