src/java/org/eclipse/jetty/continuation/Continuation.java - platform/external/jetty - Git at Google

 //
 //  ========================================================================
 //  Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
 //  ------------------------------------------------------------------------
 //  All rights reserved. This program and the accompanying materials
 //  are made available under the terms of the Eclipse Public License v1.0
 //  and Apache License v2.0 which accompanies this distribution.
 //
 //      The Eclipse Public License is available at
 //      http://www.eclipse.org/legal/epl-v10.html
 //
 //      The Apache License v2.0 is available at
 //      http://www.opensource.org/licenses/apache2.0.php
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
 //

 package org.eclipse.jetty.continuation;

 import javax.servlet.Filter;
 import javax.servlet.FilterChain;
 import javax.servlet.Servlet;
 import javax.servlet.ServletRequest;
 import javax.servlet.ServletResponse;
 import javax.servlet.ServletResponseWrapper;

 /* ------------------------------------------------------------ */
 /**
  * Continuation.
  *
  * A continuation is a mechanism by which a HTTP Request can be suspended and
  * restarted after a timeout or an asynchronous event has occurred.
  * <p>
  * 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 {@link ContinuationFilter}, the mechanism will also work
  * asynchronously on jetty-6 and non-asynchronously on any
  * servlet 2.5 container.
  * <p>
  * 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.
  * </p>
  * <h1>Continuation Usage</h1>
  * <p>
  * A continuation object is obtained for a request by calling the
  * factory method {@link ContinuationSupport#getContinuation(ServletRequest)}.
  * The continuation type returned will depend on the servlet container
  * being used.
  * </p>
  * <p>
  * There are two distinct style of operation of the continuation API.
  * </p>
  * <h3>Suspend/Resume Usage</h3>
  * <p>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.
  * </p>
  * <pre>
  * <b>Filter/Servlet:</b>
  *   // 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 ...
  *
  * <b>Async Handler:</b>
  *   // when the waited for event happens
  *   continuation.setAttribute("results",event);
  *   continuation.resume();
  *
  * <b>Filter/Servlet:</b>
  *   // when the request is redispatched
  *   if (results==null)
  *   {
  *     ... // see above
  *   }
  *   else
  *   {
  *     response.getOutputStream().write(process(results));
  *   }
  * </pre>
  * <h3>Suspend/Complete Usage</h3>
  * <p>
  * The suspend/complete style is used when an asynchronous handler is used to
  * generate the response:
  * </p>
  * <pre>
  * <b>Filter/Servlet:</b>
  *   // 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();
  *
  * <b>Wrapping Filter:</b>
  *   // 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 ...
  *
  * <b>Async Handler:</b>
  *   // when the async event happens
  *   continuation.getServletResponse().getOutputStream().write(process(event));
  *   continuation.complete()
  * </pre>
  *
  * <h1>Continuation Timeout</h1>
  * <p>
  * If a continuation is suspended, but neither {@link #complete()} or {@link #resume()} is
  * called during the period set by {@link #setTimeout(long)}, then the continuation will
  * expire and {@link #isExpired()} will return true.
  * </p>
  * <p>
  * When a continuation expires, the {@link ContinuationListener#onTimeout(Continuation)}
  * method is called on any {@link ContinuationListener} that has been registered via the
  * {@link #addContinuationListener(ContinuationListener)} method. The onTimeout handlers
  * may write a response and call {@link #complete()}. If {@link #complete()} is not called,
  * then the container will redispatch the request as if {@link #resume()} had been called,
  * except that {@link #isExpired()} will be true and {@link #isResumed()} will be false.
  * </p>
  *
  * @see ContinuationSupport
  * @see ContinuationListener
  *
  */
 public interface Continuation
 {
     public final static String ATTRIBUTE = "org.eclipse.jetty.continuation";

     /* ------------------------------------------------------------ */
     /**
      * Set the continuation timeout.
      *
      * @param timeoutMs
      *            The time in milliseconds to wait before expiring this
      *            continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
      *            A timeout of <=0 means the continuation will never expire.
      */
     void setTimeout(long timeoutMs);

     /* ------------------------------------------------------------ */
     /**
      * Suspend the processing of the request and associated
      * {@link ServletResponse}.
      *
      * <p>
      * After this method has been called, the lifecycle of the request will be
      * extended beyond the return to the container from the
      * {@link Servlet#service(ServletRequest, ServletResponse)} method and
      * {@link 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 {@link ContinuationThrowable} is thrown).
      * </p>
      *
      * <p>
      * 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:
      * <ul>
      * <li>a call to {@link #resume()}.</li>
      * <li>a call to {@link #complete()}.</li>
      * <li>the timeout expires.</li>
      * </ul>
      * <p>
      * Typically suspend with no arguments is uses when a call to {@link #resume()}
      * is expected. If a call to {@link #complete()} is expected, then the
      * {@link #suspend(ServletResponse)} method should be used instead of this method.
      * </p>
      *
      * @exception IllegalStateException
      *                If the request cannot be suspended
      */
     void suspend();


     /* ------------------------------------------------------------ */
     /**
      * Suspend the processing of the request and associated
      * {@link ServletResponse}.
      *
      * <p>
      * After this method has been called, the lifecycle of the request will be
      * extended beyond the return to the container from the
      * {@link Servlet#service(ServletRequest, ServletResponse)} method and
      * {@link 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 {@link ContinuationThrowable} is thrown).
      * </p>
      * <p>
      * 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:
      * <ul>
      * <li>a call to {@link #resume()}.</li>
      * <li>a call to {@link #complete()}.</li>
      * <li>the timeout expires.</li>
      * </ul>
      * <p>
      * Typically suspend with a response argument is uses when a call to {@link #complete()}
      * is expected. If a call to {@link #resume()} is expected, then the
      * {@link #suspend()} method should be used instead of this method.
      * </p>
      * <p>
      * Filters that may wrap the response object should check {@link #isResponseWrapped()}
      * to decide if they should destroy/finish the wrapper. If {@link #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
      * {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)}
      * listener).
      *
      * @param response The response to return via a call to {@link #getServletResponse()}
      * @exception IllegalStateException
      *                If the request cannot be suspended
      */
     void suspend(ServletResponse response);

     /* ------------------------------------------------------------ */
     /**
      * Resume a suspended request.
      *
      * <p>
      * 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 {@link #isInitial()} false.
      * </p>
      * <p>
      * If resume is called before a suspended request is returned to the
      * container (ie the thread that called {@link #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 {@link #isSuspended()} and
      * {@link #isResumed()} return true. Multiple calls to resume are ignored.
      * </p>
      * <p>
      * Typically resume() is used after a call to {@link #suspend()} with
      * no arguments. The dispatch after a resume call will use the original
      * request and response objects, even if {@link #suspend(ServletResponse)}
      * had been passed a wrapped response.
      * </p>
      *
      * @see #suspend()
      * @exception IllegalStateException if the request is not suspended.
      *
      */
     void resume();

     /* ------------------------------------------------------------ */
     /**
      * Complete a suspended request.
      *
      * <p>
      * 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.
      * </p>
      *
      * <p>
      * If complete is called before a suspended request is returned to the
      * container (ie the thread that called {@link #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 {@link #isSuspended()} and
      * {@link #isResumed()} return true.
      * </p>
      *
      * <p>
      * Typically resume() is used after a call to {@link #suspend(ServletResponse)} with
      * a possibly wrapped response. The async handler should use the response
      * provided by {@link #getServletResponse()} to write the response before
      * calling {@link #complete()}. If the request was suspended with a
      * call to {@link #suspend()} then no response object will be available via
      * {@link #getServletResponse()}.
      * </p>
      *
      * <p>
      * 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.
      *
      * @see #suspend()
      * @exception IllegalStateException
      *                if the request is not suspended.
      *
      */
     void complete();

     /* ------------------------------------------------------------ */
     /**
      * @return true after {@link #suspend()} has been called and before the
      *         request has been redispatched due to being resumed, completed or
      *         timed out.
      */
     boolean isSuspended();

     /* ------------------------------------------------------------ */
     /**
      * @return true if the request has been redispatched by a call to
      *         {@link #resume()}. Returns false after any subsequent call to
      *         suspend
      */
     boolean isResumed();

     /* ------------------------------------------------------------ */
     /**
      * @return true after a request has been redispatched as the result of a
      *         timeout. Returns false after any subsequent call to suspend.
      */
     boolean isExpired();

     /* ------------------------------------------------------------ */
     /**
      * @return 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.
      */
     boolean isInitial();

     /* ------------------------------------------------------------ */
     /**
      * Is the suspended response wrapped.
      * <p>
      * 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 {@link #suspend(ServletResponse)}
      * that passed the wrapped response, then the filter should register
      * a {@link ContinuationListener} to destroy/finish the wrapped response
      * during a call to {@link ContinuationListener#onComplete(Continuation)}.
      * @return True if {@link #suspend(ServletResponse)} has been passed a
      * {@link ServletResponseWrapper} instance.
      */
     boolean isResponseWrapped();


     /* ------------------------------------------------------------ */
     /**
      * Get the suspended response.
      * @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}.
      */
     ServletResponse getServletResponse();

     /* ------------------------------------------------------------ */
     /**
      * Add a ContinuationListener.
      *
      * @param listener
      */
     void addContinuationListener(ContinuationListener listener);

     /* ------------------------------------------------------------ */
     /** Set a request attribute.
      * This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)}
      * method on the associated request object.
      * This is a thread safe call and may be called by any thread.
      * @param name the attribute name
      * @param attribute the attribute value
      */
     public void setAttribute(String name, Object attribute);

     /* ------------------------------------------------------------ */
     /** Get a request attribute.
      * This method is a convenience method to call the {@link ServletRequest#getAttribute(String)}
      * method on the associated request object.
      * This is a thread safe call and may be called by any thread.
      * @param name the attribute name
      * @return the attribute value
      */
     public Object getAttribute(String name);

     /* ------------------------------------------------------------ */
     /** Remove a request attribute.
      * This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)}
      * method on the associated request object.
      * This is a thread safe call and may be called by any thread.
      * @param name the attribute name
      */
     public void removeAttribute(String name);

     /* ------------------------------------------------------------ */
     /**
      * Undispatch the request.
      * <p>
      * This method can be called on a suspended continuation in order
      * to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable}
      * which is caught either by the container or the {@link 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.
      * </p>
      * 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.
      */
     public void undispatch() throws ContinuationThrowable;
 }
	//
	// ========================================================================
	// Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
	// ------------------------------------------------------------------------
	// All rights reserved. This program and the accompanying materials
	// are made available under the terms of the Eclipse Public License v1.0
	// and Apache License v2.0 which accompanies this distribution.
	//
	// The Eclipse Public License is available at
	// http://www.eclipse.org/legal/epl-v10.html
	//
	// The Apache License v2.0 is available at
	// http://www.opensource.org/licenses/apache2.0.php
	//
	// You may elect to redistribute this code under either of these licenses.
	// ========================================================================
	//

	package org.eclipse.jetty.continuation;

	import javax.servlet.Filter;
	import javax.servlet.FilterChain;
	import javax.servlet.Servlet;
	import javax.servlet.ServletRequest;
	import javax.servlet.ServletResponse;
	import javax.servlet.ServletResponseWrapper;

	/* ------------------------------------------------------------ */
	/**
	* Continuation.
	*
	* A continuation is a mechanism by which a HTTP Request can be suspended and
	* restarted after a timeout or an asynchronous event has occurred.
	* <p>
	* 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 {@link ContinuationFilter}, the mechanism will also work
	* asynchronously on jetty-6 and non-asynchronously on any
	* servlet 2.5 container.
	* <p>
	* 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.
	* </p>
	* <h1>Continuation Usage</h1>
	* <p>
	* A continuation object is obtained for a request by calling the
	* factory method {@link ContinuationSupport#getContinuation(ServletRequest)}.
	* The continuation type returned will depend on the servlet container
	* being used.
	* </p>
	* <p>
	* There are two distinct style of operation of the continuation API.
	* </p>
	* <h3>Suspend/Resume Usage</h3>
	* <p>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.
	* </p>
	* <pre>
	* <b>Filter/Servlet:</b>
	* // 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 ...
	*
	* <b>Async Handler:</b>
	* // when the waited for event happens
	* continuation.setAttribute("results",event);
	* continuation.resume();
	*
	* <b>Filter/Servlet:</b>
	* // when the request is redispatched
	* if (results==null)
	* {
	* ... // see above
	* }
	* else
	* {
	* response.getOutputStream().write(process(results));
	* }
	* </pre>
	* <h3>Suspend/Complete Usage</h3>
	* <p>
	* The suspend/complete style is used when an asynchronous handler is used to
	* generate the response:
	* </p>
	* <pre>
	* <b>Filter/Servlet:</b>
	* // 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();
	*
	* <b>Wrapping Filter:</b>
	* // 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 ...
	*
	* <b>Async Handler:</b>
	* // when the async event happens
	* continuation.getServletResponse().getOutputStream().write(process(event));
	* continuation.complete()
	* </pre>
	*
	* <h1>Continuation Timeout</h1>
	* <p>
	* If a continuation is suspended, but neither {@link #complete()} or {@link #resume()} is
	* called during the period set by {@link #setTimeout(long)}, then the continuation will
	* expire and {@link #isExpired()} will return true.
	* </p>
	* <p>
	* When a continuation expires, the {@link ContinuationListener#onTimeout(Continuation)}
	* method is called on any {@link ContinuationListener} that has been registered via the
	* {@link #addContinuationListener(ContinuationListener)} method. The onTimeout handlers
	* may write a response and call {@link #complete()}. If {@link #complete()} is not called,
	* then the container will redispatch the request as if {@link #resume()} had been called,
	* except that {@link #isExpired()} will be true and {@link #isResumed()} will be false.
	* </p>
	*
	* @see ContinuationSupport
	* @see ContinuationListener
	*
	*/
	public interface Continuation
	{
	public final static String ATTRIBUTE = "org.eclipse.jetty.continuation";

	/* ------------------------------------------------------------ */
	/**
	* Set the continuation timeout.
	*
	* @param timeoutMs
	* The time in milliseconds to wait before expiring this
	* continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
	* A timeout of <=0 means the continuation will never expire.
	*/
	void setTimeout(long timeoutMs);

	/* ------------------------------------------------------------ */
	/**
	* Suspend the processing of the request and associated
	* {@link ServletResponse}.
	*
	* <p>
	* After this method has been called, the lifecycle of the request will be
	* extended beyond the return to the container from the
	* {@link Servlet#service(ServletRequest, ServletResponse)} method and
	* {@link 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 {@link ContinuationThrowable} is thrown).
	* </p>
	*
	* <p>
	* 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:
	* <ul>
	* <li>a call to {@link #resume()}.</li>
	* <li>a call to {@link #complete()}.</li>
	* <li>the timeout expires.</li>
	* </ul>
	* <p>
	* Typically suspend with no arguments is uses when a call to {@link #resume()}
	* is expected. If a call to {@link #complete()} is expected, then the
	* {@link #suspend(ServletResponse)} method should be used instead of this method.
	* </p>
	*
	* @exception IllegalStateException
	* If the request cannot be suspended
	*/
	void suspend();


	/* ------------------------------------------------------------ */
	/**
	* Suspend the processing of the request and associated
	* {@link ServletResponse}.
	*
	* <p>
	* After this method has been called, the lifecycle of the request will be
	* extended beyond the return to the container from the
	* {@link Servlet#service(ServletRequest, ServletResponse)} method and
	* {@link 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 {@link ContinuationThrowable} is thrown).
	* </p>
	* <p>
	* 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:
	* <ul>
	* <li>a call to {@link #resume()}.</li>
	* <li>a call to {@link #complete()}.</li>
	* <li>the timeout expires.</li>
	* </ul>
	* <p>
	* Typically suspend with a response argument is uses when a call to {@link #complete()}
	* is expected. If a call to {@link #resume()} is expected, then the
	* {@link #suspend()} method should be used instead of this method.
	* </p>
	* <p>
	* Filters that may wrap the response object should check {@link #isResponseWrapped()}
	* to decide if they should destroy/finish the wrapper. If {@link #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
	* {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)}
	* listener).
	*
	* @param response The response to return via a call to {@link #getServletResponse()}
	* @exception IllegalStateException
	* If the request cannot be suspended
	*/
	void suspend(ServletResponse response);

	/* ------------------------------------------------------------ */
	/**
	* Resume a suspended request.
	*
	* <p>
	* 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 {@link #isInitial()} false.
	* </p>
	* <p>
	* If resume is called before a suspended request is returned to the
	* container (ie the thread that called {@link #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 {@link #isSuspended()} and
	* {@link #isResumed()} return true. Multiple calls to resume are ignored.
	* </p>
	* <p>
	* Typically resume() is used after a call to {@link #suspend()} with
	* no arguments. The dispatch after a resume call will use the original
	* request and response objects, even if {@link #suspend(ServletResponse)}
	* had been passed a wrapped response.
	* </p>
	*
	* @see #suspend()
	* @exception IllegalStateException if the request is not suspended.
	*
	*/
	void resume();

	/* ------------------------------------------------------------ */
	/**
	* Complete a suspended request.
	*
	* <p>
	* 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.
	* </p>
	*
	* <p>
	* If complete is called before a suspended request is returned to the
	* container (ie the thread that called {@link #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 {@link #isSuspended()} and
	* {@link #isResumed()} return true.
	* </p>
	*
	* <p>
	* Typically resume() is used after a call to {@link #suspend(ServletResponse)} with
	* a possibly wrapped response. The async handler should use the response
	* provided by {@link #getServletResponse()} to write the response before
	* calling {@link #complete()}. If the request was suspended with a
	* call to {@link #suspend()} then no response object will be available via
	* {@link #getServletResponse()}.
	* </p>
	*
	* <p>
	* 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.
	*
	* @see #suspend()
	* @exception IllegalStateException
	* if the request is not suspended.
	*
	*/
	void complete();

	/* ------------------------------------------------------------ */
	/**
	* @return true after {@link #suspend()} has been called and before the
	* request has been redispatched due to being resumed, completed or
	* timed out.
	*/
	boolean isSuspended();

	/* ------------------------------------------------------------ */
	/**
	* @return true if the request has been redispatched by a call to
	* {@link #resume()}. Returns false after any subsequent call to
	* suspend
	*/
	boolean isResumed();

	/* ------------------------------------------------------------ */
	/**
	* @return true after a request has been redispatched as the result of a
	* timeout. Returns false after any subsequent call to suspend.
	*/
	boolean isExpired();

	/* ------------------------------------------------------------ */
	/**
	* @return 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.
	*/
	boolean isInitial();

	/* ------------------------------------------------------------ */
	/**
	* Is the suspended response wrapped.
	* <p>
	* 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 {@link #suspend(ServletResponse)}
	* that passed the wrapped response, then the filter should register
	* a {@link ContinuationListener} to destroy/finish the wrapped response
	* during a call to {@link ContinuationListener#onComplete(Continuation)}.
	* @return True if {@link #suspend(ServletResponse)} has been passed a
	* {@link ServletResponseWrapper} instance.
	*/
	boolean isResponseWrapped();


	/* ------------------------------------------------------------ */
	/**
	* Get the suspended response.
	* @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}.
	*/
	ServletResponse getServletResponse();

	/* ------------------------------------------------------------ */
	/**
	* Add a ContinuationListener.
	*
	* @param listener
	*/
	void addContinuationListener(ContinuationListener listener);

	/* ------------------------------------------------------------ */
	/** Set a request attribute.
	* This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)}
	* method on the associated request object.
	* This is a thread safe call and may be called by any thread.
	* @param name the attribute name
	* @param attribute the attribute value
	*/
	public void setAttribute(String name, Object attribute);

	/* ------------------------------------------------------------ */
	/** Get a request attribute.
	* This method is a convenience method to call the {@link ServletRequest#getAttribute(String)}
	* method on the associated request object.
	* This is a thread safe call and may be called by any thread.
	* @param name the attribute name
	* @return the attribute value
	*/
	public Object getAttribute(String name);

	/* ------------------------------------------------------------ */
	/** Remove a request attribute.
	* This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)}
	* method on the associated request object.
	* This is a thread safe call and may be called by any thread.
	* @param name the attribute name
	*/
	public void removeAttribute(String name);

	/* ------------------------------------------------------------ */
	/**
	* Undispatch the request.
	* <p>
	* This method can be called on a suspended continuation in order
	* to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable}
	* which is caught either by the container or the {@link 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.
	* </p>
	* 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.
	*/
	public void undispatch() throws ContinuationThrowable;
	}