Mercurial Hosting > luan
annotate src/org/eclipse/jetty/continuation/Continuation.java @ 917:1fc8ee20cb18
remove doSuspend
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Sun, 09 Oct 2016 03:23:55 -0600 |
| parents | 3428c60d7cfc |
| children | a5af9ee7cf91 |
| 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 { |
| 917 | 147 public final static String ATTRIBUTE = "org.eclipse.jetty.continuation"; |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
148 |
| 917 | 149 /* ------------------------------------------------------------ */ |
| 150 /** | |
| 151 * Set the continuation timeout. | |
| 152 * | |
| 153 * @param timeoutMs | |
| 154 * The time in milliseconds to wait before expiring this | |
| 155 * continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}. | |
| 156 * A timeout of <=0 means the continuation will never expire. | |
| 157 */ | |
| 158 void setTimeout(long timeoutMs); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
159 |
| 917 | 160 /* ------------------------------------------------------------ */ |
| 161 /** | |
| 162 * Suspend the processing of the request and associated | |
| 163 * {@link ServletResponse}. | |
| 164 * | |
| 165 * <p> | |
| 166 * After this method has been called, the lifecycle of the request will be | |
| 167 * extended beyond the return to the container from the | |
| 168 * {@link Servlet#service(ServletRequest, ServletResponse)} method and | |
| 169 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} | |
| 170 * calls. When a suspended request is returned to the container after | |
| 171 * a dispatch, then the container will not commit the associated response | |
| 172 * (unless an exception other than {@link ContinuationThrowable} is thrown). | |
| 173 * </p> | |
| 174 * | |
| 175 * <p> | |
| 176 * When the thread calling the filter chain and/or servlet has returned to | |
| 177 * the container with a suspended request, the thread is freed for other | |
| 178 * tasks and the request is held until either: | |
| 179 * <ul> | |
| 180 * <li>a call to {@link #resume()}.</li> | |
| 181 * <li>a call to {@link #complete()}.</li> | |
| 182 * <li>the timeout expires.</li> | |
| 183 * </ul> | |
| 184 * <p> | |
| 185 * Typically suspend with no arguments is uses when a call to {@link #resume()} | |
| 186 * is expected. If a call to {@link #complete()} is expected, then the | |
| 187 * {@link #suspend(ServletResponse)} method should be used instead of this method. | |
| 188 * </p> | |
| 189 * | |
| 190 * @exception IllegalStateException | |
| 191 * If the request cannot be suspended | |
| 192 */ | |
| 193 // void suspend(); | |
| 194 | |
| 195 | |
| 196 /* ------------------------------------------------------------ */ | |
| 197 /** | |
| 198 * Suspend the processing of the request and associated | |
| 199 * {@link ServletResponse}. | |
| 200 * | |
| 201 * <p> | |
| 202 * After this method has been called, the lifecycle of the request will be | |
| 203 * extended beyond the return to the container from the | |
| 204 * {@link Servlet#service(ServletRequest, ServletResponse)} method and | |
| 205 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} | |
| 206 * calls. When a suspended request is returned to the container after | |
| 207 * a dispatch, then the container will not commit the associated response | |
| 208 * (unless an exception other than {@link ContinuationThrowable} is thrown). | |
| 209 * </p> | |
| 210 * <p> | |
| 211 * When the thread calling the filter chain and/or servlet has returned to | |
| 212 * the container with a suspended request, the thread is freed for other | |
| 213 * tasks and the request is held until either: | |
| 214 * <ul> | |
| 215 * <li>a call to {@link #resume()}.</li> | |
| 216 * <li>a call to {@link #complete()}.</li> | |
| 217 * <li>the timeout expires.</li> | |
| 218 * </ul> | |
| 219 * <p> | |
| 220 * Typically suspend with a response argument is uses when a call to {@link #complete()} | |
| 221 * is expected. If a call to {@link #resume()} is expected, then the | |
| 222 * {@link #suspend()} method should be used instead of this method. | |
| 223 * </p> | |
| 224 * <p> | |
| 225 * Filters that may wrap the response object should check {@link #isResponseWrapped()} | |
| 226 * to decide if they should destroy/finish the wrapper. If {@link #isResponseWrapped()} | |
| 227 * returns true, then the wrapped request has been passed to the asynchronous | |
| 228 * handler and the wrapper should not be destroyed/finished until after a call to | |
| 229 * {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)} | |
| 230 * listener). | |
| 231 * | |
| 232 * @param response The response to return via a call to {@link #getServletResponse()} | |
| 233 * @exception IllegalStateException | |
| 234 * If the request cannot be suspended | |
| 235 */ | |
| 236 // void suspend(ServletResponse response); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
237 |
| 917 | 238 /* ------------------------------------------------------------ */ |
| 239 /** | |
| 240 * Resume a suspended request. | |
| 241 * | |
| 242 * <p> | |
| 243 * This method can be called by any thread that has been passed a reference | |
| 244 * to a continuation. When called the request is redispatched to the | |
| 245 * normal filter chain and servlet processing with {@link #isInitial()} false. | |
| 246 * </p> | |
| 247 * <p> | |
| 248 * If resume is called before a suspended request is returned to the | |
| 249 * container (ie the thread that called {@link #suspend()} is still | |
| 250 * within the filter chain and/or servlet service method), then the resume | |
| 251 * does not take effect until the call to the filter chain and/or servlet | |
| 252 * returns to the container. In this case both {@link #isSuspended()} and | |
| 253 * {@link #isResumed()} return true. Multiple calls to resume are ignored. | |
| 254 * </p> | |
| 255 * <p> | |
| 256 * Typically resume() is used after a call to {@link #suspend()} with | |
| 257 * no arguments. The dispatch after a resume call will use the original | |
| 258 * request and response objects, even if {@link #suspend(ServletResponse)} | |
| 259 * had been passed a wrapped response. | |
| 260 * </p> | |
| 261 * | |
| 262 * @see #suspend() | |
| 263 * @exception IllegalStateException if the request is not suspended. | |
| 264 * | |
| 265 */ | |
| 266 void resume(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
267 |
| 917 | 268 /* ------------------------------------------------------------ */ |
| 269 /** | |
| 270 * Complete a suspended request. | |
| 271 * | |
| 272 * <p> | |
| 273 * This method can be called by any thread that has been passed a reference | |
| 274 * to a suspended request. When a request is completed, the associated | |
| 275 * response object committed and flushed. The request is not redispatched. | |
| 276 * </p> | |
| 277 * | |
| 278 * <p> | |
| 279 * If complete is called before a suspended request is returned to the | |
| 280 * container (ie the thread that called {@link #suspend()} is still | |
| 281 * within the filter chain and/or servlet service method), then the complete | |
| 282 * does not take effect until the call to the filter chain and/or servlet | |
| 283 * returns to the container. In this case both {@link #isSuspended()} and | |
| 284 * {@link #isResumed()} return true. | |
| 285 * </p> | |
| 286 * | |
| 287 * <p> | |
| 288 * Typically resume() is used after a call to {@link #suspend(ServletResponse)} with | |
| 289 * a possibly wrapped response. The async handler should use the response | |
| 290 * provided by {@link #getServletResponse()} to write the response before | |
| 291 * calling {@link #complete()}. If the request was suspended with a | |
| 292 * call to {@link #suspend()} then no response object will be available via | |
| 293 * {@link #getServletResponse()}. | |
| 294 * </p> | |
| 295 * | |
| 296 * <p> | |
| 297 * Once complete has been called and any thread calling the filter chain | |
| 298 * and/or servlet chain has returned to the container, the request lifecycle | |
| 299 * is complete. The container is able to recycle request objects, so it is | |
| 300 * not valid hold a request or continuation reference after the end of the | |
| 301 * life cycle. | |
| 302 * | |
| 303 * @see #suspend() | |
| 304 * @exception IllegalStateException | |
| 305 * if the request is not suspended. | |
| 306 * | |
| 307 */ | |
| 308 void complete(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
309 |
| 917 | 310 /* ------------------------------------------------------------ */ |
| 311 /** | |
| 312 * @return true after {@link #suspend()} has been called and before the | |
| 313 * request has been redispatched due to being resumed, completed or | |
| 314 * timed out. | |
| 315 */ | |
| 316 boolean isSuspended(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
317 |
| 917 | 318 /* ------------------------------------------------------------ */ |
| 319 /** | |
| 320 * @return true if the request has been redispatched by a call to | |
| 321 * {@link #resume()}. Returns false after any subsequent call to | |
| 322 * suspend | |
| 323 */ | |
| 324 boolean isResumed(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
325 |
| 917 | 326 /* ------------------------------------------------------------ */ |
| 327 /** | |
| 328 * @return true after a request has been redispatched as the result of a | |
| 329 * timeout. Returns false after any subsequent call to suspend. | |
| 330 */ | |
| 331 boolean isExpired(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
332 |
| 917 | 333 /* ------------------------------------------------------------ */ |
| 334 /** | |
| 335 * @return true while the request is within the initial dispatch to the | |
| 336 * filter chain and/or servlet. Will return false once the calling | |
| 337 * thread has returned to the container after suspend has been | |
| 338 * called and during any subsequent redispatch. | |
| 339 */ | |
| 340 boolean isInitial(); | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
341 |
| 917 | 342 /* ------------------------------------------------------------ */ |
| 343 /** | |
| 344 * Is the suspended response wrapped. | |
| 345 * <p> | |
| 346 * Filters that wrap the response object should check this method to | |
| 347 * determine if they should destroy/finish the wrapped response. If | |
| 348 * the request was suspended with a call to {@link #suspend(ServletResponse)} | |
| 349 * that passed the wrapped response, then the filter should register | |
| 350 * a {@link ContinuationListener} to destroy/finish the wrapped response | |
| 351 * during a call to {@link ContinuationListener#onComplete(Continuation)}. | |
| 352 * @return True if {@link #suspend(ServletResponse)} has been passed a | |
| 353 * {@link ServletResponseWrapper} instance. | |
| 354 */ | |
| 355 boolean isResponseWrapped(); | |
|
802
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 |
| 917 | 358 /* ------------------------------------------------------------ */ |
| 359 /** | |
| 360 * Get the suspended response. | |
| 361 * @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}. | |
| 362 */ | |
| 363 ServletResponse getServletResponse(); | |
| 364 | |
| 365 /* ------------------------------------------------------------ */ | |
| 366 /** | |
| 367 * Add a ContinuationListener. | |
| 368 * | |
| 369 * @param listener | |
| 370 */ | |
| 371 void addContinuationListener(ContinuationListener listener); | |
| 372 | |
| 373 /* ------------------------------------------------------------ */ | |
| 374 /** Set a request attribute. | |
| 375 * This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)} | |
| 376 * method on the associated request object. | |
| 377 * This is a thread safe call and may be called by any thread. | |
| 378 * @param name the attribute name | |
| 379 * @param attribute the attribute value | |
| 380 */ | |
| 381 public void setAttribute(String name, Object attribute); | |
| 382 | |
| 383 /* ------------------------------------------------------------ */ | |
| 384 /** Get a request attribute. | |
| 385 * This method is a convenience method to call the {@link ServletRequest#getAttribute(String)} | |
| 386 * method on the associated request object. | |
| 387 * This is a thread safe call and may be called by any thread. | |
| 388 * @param name the attribute name | |
| 389 * @return the attribute value | |
| 390 */ | |
| 391 public Object getAttribute(String name); | |
| 392 | |
| 393 /* ------------------------------------------------------------ */ | |
| 394 /** Remove a request attribute. | |
| 395 * This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)} | |
| 396 * method on the associated request object. | |
| 397 * This is a thread safe call and may be called by any thread. | |
| 398 * @param name the attribute name | |
| 399 */ | |
| 400 public void removeAttribute(String name); | |
| 401 | |
| 402 /* ------------------------------------------------------------ */ | |
| 403 /** | |
| 404 * Undispatch the request. | |
| 405 * <p> | |
| 406 * This method can be called on a suspended continuation in order | |
| 407 * to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable} | |
| 408 * which is caught either by the container or the {@link ContinuationFilter}. | |
| 409 * This is an alternative to simply returning from the dispatch in the case | |
| 410 * where filters in the filter chain may not be prepared to handle a suspended | |
| 411 * request. | |
| 412 * </p> | |
| 413 * This method should only be used as a last resort and a normal return is a prefereable | |
| 414 * solution if filters can be updated to handle that case. | |
| 415 * | |
| 416 * @throws ContinuationThrowable thrown if the request is suspended. The instance of the | |
| 417 * exception may be reused on subsequent calls, so the stack frame may not be accurate. | |
| 418 */ | |
| 419 public void undispatch() throws ContinuationThrowable; | |
|
802
3428c60d7cfc
replace jetty jars with source
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff
changeset
|
420 } |