repo/luan: src/org/eclipse/jetty/continuation/Continuation.java annotate

author	Franklin Schmidt <fschmidt@gmail.com>
date	Wed, 07 Sep 2016 21:15:48 -0600
parents
children	1fc8ee20cb18

rev	line source
802 3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1 //
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2 // ========================================================================
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3 // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4 // ------------------------------------------------------------------------
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5 // All rights reserved. This program and the accompanying materials
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6 // are made available under the terms of the Eclipse Public License v1.0
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7 // and Apache License v2.0 which accompanies this distribution.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8 //
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9 // The Eclipse Public License is available at
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10 // http://www.eclipse.org/legal/epl-v10.html
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	11 //
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	12 // The Apache License v2.0 is available at
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	13 // http://www.opensource.org/licenses/apache2.0.php
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	14 //
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	15 // You may elect to redistribute this code under either of these licenses.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	16 // ========================================================================
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	17 //
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	18
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	19 package org.eclipse.jetty.continuation;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	20
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	21 import javax.servlet.Filter;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	22 import javax.servlet.FilterChain;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	23 import javax.servlet.Servlet;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	24 import javax.servlet.ServletRequest;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	25 import javax.servlet.ServletResponse;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	26 import javax.servlet.ServletResponseWrapper;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	27
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	28 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	29 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	30 * Continuation.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	31 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	32 * A continuation is a mechanism by which a HTTP Request can be suspended and
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	33 * restarted after a timeout or an asynchronous event has occurred.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	34 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	35 * The continuation mechanism is a portable mechanism that will work
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	36 * asynchronously without additional configuration of all jetty-7,
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	37 * jetty-8 and Servlet 3.0 containers. With the addition of
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	38 * the {@link ContinuationFilter}, the mechanism will also work
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	39 * asynchronously on jetty-6 and non-asynchronously on any
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	40 * servlet 2.5 container.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	41 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	42 * The Continuation API is a simplification of the richer async API
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	43 * provided by the servlet-3.0 and an enhancement of the continuation
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	44 * API that was introduced with jetty-6.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	45 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	46 * <h1>Continuation Usage</h1>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	47 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	48 * A continuation object is obtained for a request by calling the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	49 * factory method {@link ContinuationSupport#getContinuation(ServletRequest)}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	50 * The continuation type returned will depend on the servlet container
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	51 * being used.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	52 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	53 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	54 * There are two distinct style of operation of the continuation API.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	55 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	56 * <h3>Suspend/Resume Usage</h3>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	57 * <p>The suspend/resume style is used when a servlet and/or
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	58 * filter is used to generate the response after a asynchronous wait that is
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	59 * terminated by an asynchronous handler.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	60 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	61 * <pre>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	62 * <b>Filter/Servlet:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	63 * // if we need to get asynchronous results
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	64 * Object results = request.getAttribute("results);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	65 * if (results==null)
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	66 * {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	67 * Continuation continuation = ContinuationSupport.getContinuation(request);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	68 * continuation.suspend();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	69 * myAsyncHandler.register(continuation);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	70 * return; // or continuation.undispatch();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	71 * }
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	72 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	73 * async wait ...
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	74 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	75 * <b>Async Handler:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	76 * // when the waited for event happens
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	77 * continuation.setAttribute("results",event);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	78 * continuation.resume();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	79 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	80 * <b>Filter/Servlet:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	81 * // when the request is redispatched
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	82 * if (results==null)
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	83 * {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	84 * ... // see above
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	85 * }
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	86 * else
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	87 * {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	88 * response.getOutputStream().write(process(results));
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	89 * }
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	90 * </pre>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	91 * <h3>Suspend/Complete Usage</h3>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	92 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	93 * The suspend/complete style is used when an asynchronous handler is used to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	94 * generate the response:
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	95 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	96 * <pre>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	97 * <b>Filter/Servlet:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	98 * // when we want to enter asynchronous mode
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	99 * Continuation continuation = ContinuationSupport.getContinuation(request);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	100 * continuation.suspend(response); // response may be wrapped
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	101 * myAsyncHandler.register(continuation);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	102 * return; // or continuation.undispatch();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	103 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	104 * <b>Wrapping Filter:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	105 * // any filter that had wrapped the response should be implemented like:
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	106 * try
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	107 * {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	108 * chain.doFilter(request,wrappedResponse);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	109 * }
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	110 * finally
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	111 * {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	112 * if (!continuation.isResponseWrapped())
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	113 * wrappedResponse.finish()
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	114 * else
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	115 * continuation.addContinuationListener(myCompleteListener)
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	116 * }
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	117 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	118 * async wait ...
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	119 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	120 * <b>Async Handler:</b>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	121 * // when the async event happens
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	122 * continuation.getServletResponse().getOutputStream().write(process(event));
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	123 * continuation.complete()
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	124 * </pre>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	125 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	126 * <h1>Continuation Timeout</h1>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	127 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	128 * If a continuation is suspended, but neither {@link #complete()} or {@link #resume()} is
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	129 * called during the period set by {@link #setTimeout(long)}, then the continuation will
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	130 * expire and {@link #isExpired()} will return true.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	131 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	132 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	133 * When a continuation expires, the {@link ContinuationListener#onTimeout(Continuation)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	134 * method is called on any {@link ContinuationListener} that has been registered via the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	135 * {@link #addContinuationListener(ContinuationListener)} method. The onTimeout handlers
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	136 * may write a response and call {@link #complete()}. If {@link #complete()} is not called,
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	137 * then the container will redispatch the request as if {@link #resume()} had been called,
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	138 * except that {@link #isExpired()} will be true and {@link #isResumed()} will be false.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	139 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	140 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	141 * @see ContinuationSupport
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	142 * @see ContinuationListener
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	143 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	144 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	145 public interface Continuation
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	146 {
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	147 public final static String ATTRIBUTE = "org.eclipse.jetty.continuation";
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	148
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	149 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	150 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	151 * Set the continuation timeout.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	152 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	153 * @param timeoutMs
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	154 * The time in milliseconds to wait before expiring this
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	155 * continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	156 * A timeout of <=0 means the continuation will never expire.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	157 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	158 void setTimeout(long timeoutMs);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	159
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	160 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	161 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	162 * Suspend the processing of the request and associated
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	163 * {@link ServletResponse}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	164 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	165 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	166 * After this method has been called, the lifecycle of the request will be
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	167 * extended beyond the return to the container from the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	168 * {@link Servlet#service(ServletRequest, ServletResponse)} method and
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	169 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	170 * calls. When a suspended request is returned to the container after
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	171 * a dispatch, then the container will not commit the associated response
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	172 * (unless an exception other than {@link ContinuationThrowable} is thrown).
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	173 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	174 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	175 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	176 * When the thread calling the filter chain and/or servlet has returned to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	177 * the container with a suspended request, the thread is freed for other
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	178 * tasks and the request is held until either:
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	179 * <ul>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	180 * <li>a call to {@link #resume()}.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	181 * <li>a call to {@link #complete()}.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	182 * <li>the timeout expires.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	183 * </ul>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	184 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	185 * Typically suspend with no arguments is uses when a call to {@link #resume()}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	186 * is expected. If a call to {@link #complete()} is expected, then the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	187 * {@link #suspend(ServletResponse)} method should be used instead of this method.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	188 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	189 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	190 * @exception IllegalStateException
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	191 * If the request cannot be suspended
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	192 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	193 void suspend();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	194
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	195
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	196 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	197 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	198 * Suspend the processing of the request and associated
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	199 * {@link ServletResponse}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	200 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	201 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	202 * After this method has been called, the lifecycle of the request will be
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	203 * extended beyond the return to the container from the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	204 * {@link Servlet#service(ServletRequest, ServletResponse)} method and
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	205 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	206 * calls. When a suspended request is returned to the container after
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	207 * a dispatch, then the container will not commit the associated response
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	208 * (unless an exception other than {@link ContinuationThrowable} is thrown).
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	209 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	210 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	211 * When the thread calling the filter chain and/or servlet has returned to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	212 * the container with a suspended request, the thread is freed for other
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	213 * tasks and the request is held until either:
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	214 * <ul>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	215 * <li>a call to {@link #resume()}.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	216 * <li>a call to {@link #complete()}.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	217 * <li>the timeout expires.</li>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	218 * </ul>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	219 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	220 * Typically suspend with a response argument is uses when a call to {@link #complete()}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	221 * is expected. If a call to {@link #resume()} is expected, then the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	222 * {@link #suspend()} method should be used instead of this method.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	223 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	224 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	225 * Filters that may wrap the response object should check {@link #isResponseWrapped()}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	226 * to decide if they should destroy/finish the wrapper. If {@link #isResponseWrapped()}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	227 * returns true, then the wrapped request has been passed to the asynchronous
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	228 * handler and the wrapper should not be destroyed/finished until after a call to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	229 * {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	230 * listener).
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	231 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	232 * @param response The response to return via a call to {@link #getServletResponse()}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	233 * @exception IllegalStateException
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	234 * If the request cannot be suspended
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	235 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	236 void suspend(ServletResponse response);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	237
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	238 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	239 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	240 * Resume a suspended request.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	241 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	242 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	243 * This method can be called by any thread that has been passed a reference
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	244 * to a continuation. When called the request is redispatched to the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	245 * normal filter chain and servlet processing with {@link #isInitial()} false.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	246 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	247 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	248 * If resume is called before a suspended request is returned to the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	249 * container (ie the thread that called {@link #suspend()} is still
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	250 * within the filter chain and/or servlet service method), then the resume
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	251 * does not take effect until the call to the filter chain and/or servlet
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	252 * returns to the container. In this case both {@link #isSuspended()} and
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	253 * {@link #isResumed()} return true. Multiple calls to resume are ignored.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	254 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	255 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	256 * Typically resume() is used after a call to {@link #suspend()} with
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	257 * no arguments. The dispatch after a resume call will use the original
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	258 * request and response objects, even if {@link #suspend(ServletResponse)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	259 * had been passed a wrapped response.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	260 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	261 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	262 * @see #suspend()
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	263 * @exception IllegalStateException if the request is not suspended.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	264 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	265 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	266 void resume();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	267
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	268 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	269 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	270 * Complete a suspended request.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	271 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	272 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	273 * This method can be called by any thread that has been passed a reference
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	274 * to a suspended request. When a request is completed, the associated
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	275 * response object committed and flushed. The request is not redispatched.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	276 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	277 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	278 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	279 * If complete is called before a suspended request is returned to the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	280 * container (ie the thread that called {@link #suspend()} is still
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	281 * within the filter chain and/or servlet service method), then the complete
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	282 * does not take effect until the call to the filter chain and/or servlet
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	283 * returns to the container. In this case both {@link #isSuspended()} and
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	284 * {@link #isResumed()} return true.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	285 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	286 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	287 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	288 * Typically resume() is used after a call to {@link #suspend(ServletResponse)} with
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	289 * a possibly wrapped response. The async handler should use the response
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	290 * provided by {@link #getServletResponse()} to write the response before
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	291 * calling {@link #complete()}. If the request was suspended with a
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	292 * call to {@link #suspend()} then no response object will be available via
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	293 * {@link #getServletResponse()}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	294 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	295 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	296 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	297 * Once complete has been called and any thread calling the filter chain
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	298 * and/or servlet chain has returned to the container, the request lifecycle
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	299 * is complete. The container is able to recycle request objects, so it is
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	300 * not valid hold a request or continuation reference after the end of the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	301 * life cycle.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	302 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	303 * @see #suspend()
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	304 * @exception IllegalStateException
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	305 * if the request is not suspended.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	306 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	307 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	308 void complete();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	309
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	310 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	311 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	312 * @return true after {@link #suspend()} has been called and before the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	313 * request has been redispatched due to being resumed, completed or
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	314 * timed out.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	315 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	316 boolean isSuspended();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	317
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	318 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	319 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	320 * @return true if the request has been redispatched by a call to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	321 * {@link #resume()}. Returns false after any subsequent call to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	322 * suspend
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	323 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	324 boolean isResumed();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	325
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	326 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	327 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	328 * @return true after a request has been redispatched as the result of a
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	329 * timeout. Returns false after any subsequent call to suspend.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	330 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	331 boolean isExpired();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	332
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	333 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	334 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	335 * @return true while the request is within the initial dispatch to the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	336 * filter chain and/or servlet. Will return false once the calling
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	337 * thread has returned to the container after suspend has been
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	338 * called and during any subsequent redispatch.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	339 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	340 boolean isInitial();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	341
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	342 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	343 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	344 * Is the suspended response wrapped.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	345 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	346 * Filters that wrap the response object should check this method to
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	347 * determine if they should destroy/finish the wrapped response. If
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	348 * the request was suspended with a call to {@link #suspend(ServletResponse)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	349 * that passed the wrapped response, then the filter should register
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	350 * a {@link ContinuationListener} to destroy/finish the wrapped response
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	351 * during a call to {@link ContinuationListener#onComplete(Continuation)}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	352 * @return True if {@link #suspend(ServletResponse)} has been passed a
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	353 * {@link ServletResponseWrapper} instance.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	354 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	355 boolean isResponseWrapped();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	356
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	357
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	358 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	359 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	360 * Get the suspended response.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	361 * @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	362 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	363 ServletResponse getServletResponse();
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	364
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	365 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	366 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	367 * Add a ContinuationListener.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	368 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	369 * @param listener
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	370 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	371 void addContinuationListener(ContinuationListener listener);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	372
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	373 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	374 /** Set a request attribute.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	375 * This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	376 * method on the associated request object.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	377 * This is a thread safe call and may be called by any thread.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	378 * @param name the attribute name
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	379 * @param attribute the attribute value
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	380 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	381 public void setAttribute(String name, Object attribute);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	382
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	383 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	384 /** Get a request attribute.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	385 * This method is a convenience method to call the {@link ServletRequest#getAttribute(String)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	386 * method on the associated request object.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	387 * This is a thread safe call and may be called by any thread.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	388 * @param name the attribute name
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	389 * @return the attribute value
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	390 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	391 public Object getAttribute(String name);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	392
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	393 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	394 /** Remove a request attribute.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	395 * This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	396 * method on the associated request object.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	397 * This is a thread safe call and may be called by any thread.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	398 * @param name the attribute name
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	399 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	400 public void removeAttribute(String name);
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	401
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	402 /* ------------------------------------------------------------ */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	403 /**
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	404 * Undispatch the request.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	405 * <p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	406 * This method can be called on a suspended continuation in order
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	407 * to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable}
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	408 * which is caught either by the container or the {@link ContinuationFilter}.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	409 * This is an alternative to simply returning from the dispatch in the case
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	410 * where filters in the filter chain may not be prepared to handle a suspended
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	411 * request.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	412 * </p>
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	413 * This method should only be used as a last resort and a normal return is a prefereable
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	414 * solution if filters can be updated to handle that case.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	415 *
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	416 * @throws ContinuationThrowable thrown if the request is suspended. The instance of the
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	417 * exception may be reused on subsequent calls, so the stack frame may not be accurate.
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	418 */
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	419 public void undispatch() throws ContinuationThrowable;
3428c60d7cfc replace jetty jars with source Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	420 }

802

3428c60d7cfc replace jetty jars with source