## org.eclipse.jetty.continuation
Class Servlet3Continuation

    java.lang.Object
      org.eclipse.jetty.continuation.Servlet3Continuation

All Implemented Interfaces:
  Continuation

    public class Servlet3Continuation

extends Object
implements Continuation

This implementation of Continuation is used by `ContinuationSupport` when it detects that the application has been deployed in a non-jetty Servlet 3 server.

Field Summary

Fields inherited from interface org.eclipse.jetty.continuation.Continuation
`ATTRIBUTE`

Constructor Summary
`Servlet3Continuation(ServletRequest request)`

Method Summary
`void` `addContinuationListener(ContinuationListener listener)` Add a ContinuationListener.
`void` `complete()` Complete a suspended request.
`Object` `getAttribute(String name)` Get a request attribute.
`ServletResponse` `getServletResponse()` Get the suspended response.
`boolean` `isExpired()`
`boolean` `isInitial()`
`boolean` `isResponseWrapped()` Is the suspended response wrapped.
`boolean` `isResumed()`
`boolean` `isSuspended()`
`void` `keepWrappers()`
`void` `removeAttribute(String name)` Remove a request attribute.
`void` `resume()` Resume a suspended request.
`void` `setAttribute(String name, Object attribute)` Set a request attribute.
`void` `setTimeout(long timeoutMs)` Set the continuation timeout.
`void` `suspend()` Suspend the processing of the request and associated `ServletResponse`.
`void` `suspend(ServletResponse response)` Suspend the processing of the request and associated `ServletResponse`.
`void` `undispatch()` Undispatch the request.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Servlet3Continuation

    public Servlet3Continuation(ServletRequest request)

Method Detail

### addContinuationListener

    public void addContinuationListener(ContinuationListener listener)

  Description copied from interface: `Continuation`
  Add a ContinuationListener.

  Specified by:
    `addContinuationListener` in interface `Continuation`

### 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`
  See Also:
    `Continuation.suspend()`

### getServletResponse

    public 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)`.

### 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.

### 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.

### 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

### 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.

### keepWrappers

    public void keepWrappers()

### 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.suspend()`

### setTimeout

    public void setTimeout(long timeoutMs)

  Description copied from interface: `Continuation`
  Set the continuation timeout.

  Specified by:
    `setTimeout` in interface `Continuation`
  Parameters:
    `timeoutMs` - 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.

### suspend

    public void suspend(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()`

### 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`

### 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.

### 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-2010 Mort Bay Consulting. All Rights Reserved.