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
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 }
|
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 * {@code static} 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
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 {@code this}
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 }
|