|
1 /* |
|
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. |
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 * |
|
5 * This code is free software; you can redistribute it and/or modify it |
|
6 * under the terms of the GNU General Public License version 2 only, as |
|
7 * published by the Free Software Foundation. Oracle designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Oracle in the LICENSE file that accompanied this code. |
|
10 * |
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
|
15 * accompanied this code). |
|
16 * |
|
17 * You should have received a copy of the GNU General Public License version |
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 * |
|
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
22 * or visit www.oracle.com if you need additional information or have any |
|
23 * questions. |
|
24 */ |
|
25 |
|
26 package com.sun.xml.internal.ws.api.pipe; |
|
27 |
|
28 import com.sun.istack.internal.NotNull; |
|
29 import com.sun.xml.internal.ws.api.message.Message; |
|
30 import com.sun.xml.internal.ws.api.message.Packet; |
|
31 import com.sun.xml.internal.ws.api.pipe.helper.AbstractFilterTubeImpl; |
|
32 import com.sun.xml.internal.ws.api.pipe.helper.AbstractTubeImpl; |
|
33 import com.sun.xml.internal.ws.api.server.Adapter; |
|
34 |
|
35 import javax.annotation.PreDestroy; |
|
36 import javax.xml.ws.Dispatch; |
|
37 import javax.xml.ws.Provider; |
|
38 import javax.xml.ws.WebServiceException; |
|
39 import javax.xml.ws.handler.LogicalHandler; |
|
40 import javax.xml.ws.handler.soap.SOAPHandler; |
|
41 import java.text.SimpleDateFormat; |
|
42 |
|
43 /** |
|
44 * Abstraction of the intermediate layers in the processing chain |
|
45 * and transport. |
|
46 * |
|
47 * <h2>What is a {@link Tube}?</h2> |
|
48 * <p> |
|
49 * {@link Tube} is a basic processing unit that represents SOAP-level |
|
50 * protocol handling code. Mutliple tubes are often put together in |
|
51 * a line (it needs not one dimensional — more later), and act on |
|
52 * {@link Packet}s in a sequential fashion. |
|
53 * |
|
54 * <p> |
|
55 * {@link Tube}s run asynchronously. That is, there is no guarantee that |
|
56 * {@link #processRequest(Packet)} and {@link #processResponse(Packet)} runs |
|
57 * in the same thread, nor is there any guarantee that this tube and next |
|
58 * tube runs in the same thread. Furthermore, one thread may be used to |
|
59 * run multiple pipeline in turn (just like a real CPU runs multiple |
|
60 * threads in turn.) |
|
61 * |
|
62 * |
|
63 * <h2>Tube examples</h2> |
|
64 * <p> |
|
65 * Transport is a kind of tube. It sends the {@link Packet} |
|
66 * through, say, HTTP connection, and receives the data back into another {@link Packet}. |
|
67 * |
|
68 * <p> |
|
69 * More often, a tube works like a filter. It acts on a packet, |
|
70 * and then it tells the JAX-WS that the packet should be passed into another |
|
71 * tube. It can do the same on the way back. |
|
72 * |
|
73 * <p> |
|
74 * For example, XWSS will be a {@link Tube}. It will act on a request |
|
75 * {@link Packet}, then perhaps wrap it into |
|
76 * another {@link Packet} to encrypt the body and add a header, then |
|
77 * the processing will go on to the next tube. |
|
78 * |
|
79 * <p> |
|
80 * Yet another kind of filter tube is those that wraps {@link LogicalHandler} |
|
81 * and {@link SOAPHandler}. These tubes are heavy-weight; they often consume |
|
82 * a message in a packet and create a new one, and then pass it to the next tube. |
|
83 * |
|
84 * <p> |
|
85 * There would be a {@link Tube} implementation that invokes {@link Provider}. |
|
86 * There would be a {@link Tube} implementation that invokes a service method |
|
87 * on the user's code. |
|
88 * There would be a {@link Dispatch} implementation that invokes a {@link Tube}. |
|
89 * |
|
90 * <p> |
|
91 * WS-MEX can be implemented as a {@link Tube} that looks for |
|
92 * {@link Message#getPayloadNamespaceURI()} and serves the request. |
|
93 * |
|
94 * |
|
95 * |
|
96 * |
|
97 * <h2>Tube Lifecycle</h2> |
|
98 * Pipeline is expensive to set up, so once it's created it will be reused. |
|
99 * A pipeline is not reentrant; one pipeline is used to process one request/response |
|
100 * at at time. The same pipeline instance may serve multiple request/response, |
|
101 * if one comes after another and they don't overlap. |
|
102 * <p> |
|
103 * Where a need arises to process multiple requests concurrently, a pipeline |
|
104 * gets cloned through {@link TubeCloner}. Note that this need may happen on |
|
105 * both server (because it quite often serves multiple requests concurrently) |
|
106 * and client (because it needs to support asynchronous method invocations.) |
|
107 * <p> |
|
108 * Created pipelines (including cloned ones and the original) may be discarded and GC-ed |
|
109 * at any time at the discretion of whoever owns pipelines. Tubes can, however, expect |
|
110 * at least one copy (or original) of pipeline to live at any given time while a pipeline |
|
111 * owner is interested in the given pipeline configuration (in more concerete terms, |
|
112 * for example, as long as a dispatch object lives, it's going to keep at least one |
|
113 * copy of a pipeline alive.) |
|
114 * <p> |
|
115 * Before a pipeline owner dies, it may invoke {@link #preDestroy()} on the last |
|
116 * remaining pipeline. It is "may" for pipeline owners that live in the client-side |
|
117 * of JAX-WS (such as dispatches and proxies), but it is a "must" for pipeline owners |
|
118 * that live in the server-side of JAX-WS. |
|
119 * <p> |
|
120 * This last invocation gives a chance for some pipes to clean up any state/resource |
|
121 * acquired (such as WS-RM's sequence, WS-Trust's SecurityToken), although as stated above, |
|
122 * this is not required for clients. |
|
123 * |
|
124 * |
|
125 * |
|
126 * <h2>Tube and state</h2> |
|
127 * <p> |
|
128 * The lifecycle of pipelines is designed to allow a {@link Tube} to store various |
|
129 * state in easily accessible fashion. |
|
130 * |
|
131 * |
|
132 * <h3>Per-packet state</h3> |
|
133 * <p> |
|
134 * Any information that changes from a packet to packet should be |
|
135 * stored in {@link Packet} (if such informaton is specific to your problem domain, |
|
136 * then most likely {@link Packet#invocationProperties}.) |
|
137 * This includes information like transport-specific headers. |
|
138 * |
|
139 * <h3>Per-thread state</h3> |
|
140 * <p> |
|
141 * Any expensive-to-create objects that are non-reentrant can be stored |
|
142 * either in instance variables of a {@link Tube}, or a static {@link ThreadLocal}. |
|
143 * |
|
144 * <p> |
|
145 * The first approach works, because {@link Tube} is |
|
146 * non reentrant. When a tube is copied, new instances should be allocated |
|
147 * so that two {@link Tube} instances don't share thread-unsafe resources. |
|
148 * |
|
149 * Similarly the second approach works, since {@link ThreadLocal} guarantees |
|
150 * that each thread gets its own private copy. |
|
151 * |
|
152 * <p> |
|
153 * The former is faster to access, and you need not worry about clean up. |
|
154 * On the other hand, because there can be many more concurrent requests |
|
155 * than # of threads, you may end up holding onto more resources than necessary. |
|
156 * |
|
157 * <p> |
|
158 * This includes state like canonicalizers, JAXB unmarshallers, |
|
159 * {@link SimpleDateFormat}, etc. |
|
160 * |
|
161 * |
|
162 * <h3>Per-proxy/per-endpoint state</h3> |
|
163 * <p> |
|
164 * Information that is tied to a particular proxy/dispatch can be stored |
|
165 * in a separate object that is referenced from a tube. When |
|
166 * a new tube is copied, you can simply hand out a reference to the newly |
|
167 * created one, so that all copied tubes refer to the same instance. |
|
168 * See the following code as an example: |
|
169 * |
|
170 * <pre> |
|
171 * class TubeImpl { |
|
172 * // this object stores per-proxy state |
|
173 * class DataStore { |
|
174 * int counter; |
|
175 * } |
|
176 * |
|
177 * private DataStore ds; |
|
178 * |
|
179 * // create a fresh new pipe |
|
180 * public TubeImpl(...) { |
|
181 * .... |
|
182 * ds = new DataStore(); |
|
183 * } |
|
184 * |
|
185 * // copy constructor |
|
186 * private TubeImpl(TubeImpl that, PipeCloner cloner) { |
|
187 * cloner.add(that,this); |
|
188 * ... |
|
189 * this.ds = that.ds; |
|
190 * } |
|
191 * |
|
192 * public TubeImpl copy(PipeCloner pc) { |
|
193 * return new TubeImpl(this,pc); |
|
194 * } |
|
195 * } |
|
196 * </pre> |
|
197 * |
|
198 * <p> |
|
199 * Note that access to such resource may need to be synchronized, |
|
200 * since multiple copies of pipelines may execute concurrently. |
|
201 * |
|
202 * |
|
203 * |
|
204 * <h3>VM-wide state</h3> |
|
205 * <p> |
|
206 * <tt>static</tt> is always there for you to use. |
|
207 * |
|
208 * |
|
209 * |
|
210 * @see AbstractTubeImpl |
|
211 * @see AbstractFilterTubeImpl |
|
212 * |
|
213 * @author Kohsuke Kawaguchi |
|
214 * @author Jitendra Kotamraju |
|
215 */ |
|
216 public interface Tube { |
|
217 /** |
|
218 * Acts on a request and perform some protocol specific operation. |
|
219 * |
|
220 * TODO: exception handling semantics need more discussion |
|
221 * |
|
222 * @throws WebServiceException |
|
223 * On the server side, this signals an error condition where |
|
224 * a fault reply is in order (or the exception gets eaten by |
|
225 * the top-most transport {@link Adapter} if it's one-way.) |
|
226 * This frees each {@link Tube} from try/catching a |
|
227 * {@link WebServiceException} in every layer. |
|
228 * |
|
229 * Note that this method is also allowed to return |
|
230 * {@link NextAction#returnWith(Packet)} with |
|
231 * a {@link Packet} that has a fault as the payload. |
|
232 * |
|
233 * <p> |
|
234 * On the client side, the {@link WebServiceException} thrown |
|
235 * will be propagated all the way back to the calling client |
|
236 * applications. (The consequence of that is that if you are |
|
237 * a filtering {@link Tube}, you must not eat the exception |
|
238 * that was given to {@link #processException(Throwable)} . |
|
239 * |
|
240 * @throws RuntimeException |
|
241 * Other runtime exception thrown by this method must |
|
242 * be treated as a bug in the tube implementation, |
|
243 * and therefore should not be converted into a fault. |
|
244 * (Otherwise it becomes very difficult to debug implementation |
|
245 * problems.) |
|
246 * |
|
247 * <p> |
|
248 * On the server side, this exception should be most likely |
|
249 * just logged. On the client-side it gets propagated to the |
|
250 * client application. |
|
251 * |
|
252 * <p> |
|
253 * The consequence of this is that if a pipe calls |
|
254 * into an user application (such as {@link SOAPHandler} |
|
255 * or {@link LogicalHandler}), where a {@link RuntimeException} |
|
256 * is *not* a bug in the JAX-WS implementation, it must be catched |
|
257 * and wrapped into a {@link WebServiceException}. |
|
258 * |
|
259 * @param request |
|
260 * The packet that represents a request message. |
|
261 * If the packet has a non-null message, it must be a valid |
|
262 * unconsumed {@link Message}. This message represents the |
|
263 * SOAP message to be sent as a request. |
|
264 * <p> |
|
265 * The packet is also allowed to carry no message, which indicates |
|
266 * that this is an output-only request. |
|
267 * (that's called "solicit", right? - KK) |
|
268 * |
|
269 * @return |
|
270 * A {@link NextAction} object that represents the next action |
|
271 * to be taken by the JAX-WS runtime. |
|
272 */ |
|
273 @NotNull NextAction processRequest(@NotNull Packet request); |
|
274 |
|
275 /** |
|
276 * Acts on a response and performs some protocol specific operation. |
|
277 * |
|
278 * <p> |
|
279 * Once a {@link #processRequest(Packet)} is invoked, this method |
|
280 * will be always invoked with the response, before this {@link Tube} |
|
281 * processes another request. |
|
282 * |
|
283 * @param response |
|
284 * If the packet has a non-null message, it must be |
|
285 * a valid unconsumed {@link Message}. This message represents |
|
286 * a response to the request message passed to |
|
287 * {@link #processRequest(Packet)} earlier. |
|
288 * <p> |
|
289 * The packet is also allowed to carry no message, which indicates |
|
290 * that there was no response. This is used for things like |
|
291 * one-way message and/or one-way transports. |
|
292 * |
|
293 * TODO: exception handling semantics need more discussion |
|
294 * |
|
295 * @return |
|
296 * A {@link NextAction} object that represents the next action |
|
297 * to be taken by the JAX-WS runtime. |
|
298 */ |
|
299 @NotNull NextAction processResponse(@NotNull Packet response); |
|
300 |
|
301 |
|
302 /** |
|
303 * Acts on a exception and performs some clean up operations. |
|
304 * |
|
305 * <p> |
|
306 * If a {@link #processRequest(Packet)}, {@link #processResponse(Packet)}, |
|
307 * {@link #processException(Throwable)} throws an exception, this method |
|
308 * will be always invoked on all the {@link Tube}s in the remaining |
|
309 * {@link NextAction}s. |
|
310 * |
|
311 * <p> |
|
312 * On the server side, the {@link Throwable} thrown will be propagated to the |
|
313 * top-most transport. The transport converts the exception to fault reply or |
|
314 * simply logs in case of one-way MEP. If you are a filtering {@link Tube} like |
|
315 * {@link AbstractTubeImpl}, you don't have to override the implementation). On |
|
316 * the other hand, any intermediate {@link Tube} may want to convert the exception |
|
317 * to a fault message. |
|
318 * |
|
319 * <p> |
|
320 * On the client side, the {@link Throwable} thrown |
|
321 * will be propagated all the way back to the calling client |
|
322 * applications. (The consequence of that is that if you are |
|
323 * a filtering {@link Tube} like {@link AbstractTubeImpl}, you don't have to |
|
324 * override the implementation) |
|
325 * |
|
326 * @param t |
|
327 * |
|
328 * @return |
|
329 * A {@link NextAction} object that represents the next action |
|
330 * to be taken by the JAX-WS runtime. |
|
331 */ |
|
332 @NotNull NextAction processException(@NotNull Throwable t); |
|
333 |
|
334 /** |
|
335 * Invoked before the last copy of the pipeline is about to be discarded, |
|
336 * to give {@link Tube}s a chance to clean up any resources. |
|
337 * |
|
338 * <p> |
|
339 * This can be used to invoke {@link PreDestroy} lifecycle methods |
|
340 * on user handler. The invocation of it is optional on the client side, |
|
341 * but mandatory on the server side. |
|
342 * |
|
343 * <p> |
|
344 * When multiple copies of pipelines are created, this method is called |
|
345 * only on one of them. |
|
346 * |
|
347 * @throws WebServiceException |
|
348 * If the clean up fails, {@link WebServiceException} can be thrown. |
|
349 * This exception will be propagated to users (if this is client), |
|
350 * or recorded (if this is server.) |
|
351 */ |
|
352 void preDestroy(); |
|
353 |
|
354 /** |
|
355 * Creates an identical clone of this {@link Tube}. |
|
356 * |
|
357 * <p> |
|
358 * This method creates an identical pipeline that can be used |
|
359 * concurrently with this pipeline. When the caller of a pipeline |
|
360 * is multi-threaded and need concurrent use of the same pipeline, |
|
361 * it can do so by creating copies through this method. |
|
362 * |
|
363 * <h3>Implementation Note</h3> |
|
364 * <p> |
|
365 * It is the implementation's responsibility to call |
|
366 * {@link TubeCloner#add(Tube,Tube)} to register the copied pipe |
|
367 * with the original. This is required before you start copying |
|
368 * the other {@link Tube} references you have, or else there's a |
|
369 * risk of infinite recursion. |
|
370 * <p> |
|
371 * For most {@link Tube} implementations that delegate to another |
|
372 * {@link Tube}, this method requires that you also copy the {@link Tube} |
|
373 * that you delegate to. |
|
374 * <p> |
|
375 * For limited number of {@link Tube}s that do not maintain any |
|
376 * thread unsafe resource, it is allowed to simply return <tt>this</tt> |
|
377 * from this method (notice that even if you are stateless, if you |
|
378 * got a delegating {@link Tube} and that one isn't stateless, you |
|
379 * still have to copy yourself.) |
|
380 * |
|
381 * <p> |
|
382 * Note that this method might be invoked by one thread while another |
|
383 * thread is executing the other process method. See |
|
384 * the {@link Codec#copy()} for more discussion about this. |
|
385 * |
|
386 * @param cloner |
|
387 * Use this object (in particular its {@link TubeCloner#copy(Tube)} method |
|
388 * to clone other pipe references you have |
|
389 * in your pipe. See {@link TubeCloner} for more discussion |
|
390 * about why. |
|
391 * |
|
392 * @return |
|
393 * always non-null {@link Tube}. |
|
394 */ |
|
395 Tube copy(TubeCloner cloner); |
|
396 } |