Mercurial Hosting > luan

annotate src/org/eclipse/jetty/continuation/Continuation.java @ 867:4f5547d29192

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
minor
author Franklin Schmidt <fschmidt@gmail.com>
date Sun, 02 Oct 2016 21:06:18 -0600
parents 3428c60d7cfc
children 1fc8ee20cb18
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 }