< prev index next >

src/java.xml.ws/share/classes/com/sun/xml/internal/ws/api/pipe/Tube.java

Print this page




 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 }
< prev index next >