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