com.sun.xml.ws.api.pipe
Interface Tube

All Known Subinterfaces:

EndpointAwareTube

All Known Implementing Classes:

AbstractFilterTubeImpl, AbstractSchemaValidationTube, AbstractTubeImpl, AsyncProviderInvokerTube, ClientLogicalHandlerTube, ClientMessageHandlerTube, ClientMUTube, ClientSchemaValidationTube, ClientSOAPHandlerTube, DeferredTransportPipe, DumpTube, HandlerTube, HttpTransportPipe, InvokerTube, InvokerTube, LoggingDumpTube, MemberSubmissionWsaClientTube, MemberSubmissionWsaServerTube, PipeAdapter, ProviderInvokerTube, SEIInvokerTube, ServerLogicalHandlerTube, ServerMessageHandlerTube, ServerMUTube, ServerSchemaValidationTube, ServerSOAPHandlerTube, SyncProviderInvokerTube, W3CWsaClientTube, W3CWsaServerTube, WsaClientTube, WsaServerTube

public interface Tube

Abstraction of the intermediate layers in the processing chain and transport.

What is a Tube?

Tube is a basic processing unit that represents SOAP-level protocol handling code. Mutliple tubes are often put together in a line (it needs not one dimensional — more later), and act on Packets in a sequential fashion.

Tubes run asynchronously. That is, there is no guarantee that processRequest(Packet) and processResponse(Packet) runs in the same thread, nor is there any guarantee that this tube and next tube runs in the same thread. Furthermore, one thread may be used to run multiple pipeline in turn (just like a real CPU runs multiple threads in turn.)

Tube examples

Transport is a kind of tube. It sends the Packet through, say, HTTP connection, and receives the data back into another Packet.

More often, a tube works like a filter. It acts on a packet, and then it tells the JAX-WS that the packet should be passed into another tube. It can do the same on the way back.

For example, XWSS will be a Tube. It will act on a request Packet, then perhaps wrap it into another Packet to encrypt the body and add a header, then the processing will go on to the next tube.

Yet another kind of filter tube is those that wraps LogicalHandler and SOAPHandler. These tubes are heavy-weight; they often consume a message in a packet and create a new one, and then pass it to the next tube.

There would be a Tube implementation that invokes Provider. There would be a Tube implementation that invokes a service method on the user's code. There would be a Dispatch implementation that invokes a Tube.

WS-MEX can be implemented as a Tube that looks for Message.getPayloadNamespaceURI() and serves the request.

Tube Lifecycle

Pipeline is expensive to set up, so once it's created it will be reused. A pipeline is not reentrant; one pipeline is used to process one request/response at at time. The same pipeline instance may serve multiple request/response, if one comes after another and they don't overlap.

Where a need arises to process multiple requests concurrently, a pipeline gets cloned through TubeCloner. Note that this need may happen on both server (because it quite often serves multiple requests concurrently) and client (because it needs to support asynchronous method invocations.)

Created pipelines (including cloned ones and the original) may be discarded and GC-ed at any time at the discretion of whoever owns pipelines. Tubes can, however, expect at least one copy (or original) of pipeline to live at any given time while a pipeline owner is interested in the given pipeline configuration (in more concerete terms, for example, as long as a dispatch object lives, it's going to keep at least one copy of a pipeline alive.)

Before a pipeline owner dies, it may invoke preDestroy() on the last remaining pipeline. It is "may" for pipeline owners that live in the client-side of JAX-WS (such as dispatches and proxies), but it is a "must" for pipeline owners that live in the server-side of JAX-WS.

This last invocation gives a chance for some pipes to clean up any state/resource acquired (such as WS-RM's sequence, WS-Trust's SecurityToken), although as stated above, this is not required for clients.

Tube and state

The lifecycle of pipelines is designed to allow a Tube to store various state in easily accessible fashion.

Per-packet state

Any information that changes from a packet to packet should be stored in Packet (if such informaton is specific to your problem domain, then most likely Packet.invocationProperties.) This includes information like transport-specific headers.

Per-thread state

Any expensive-to-create objects that are non-reentrant can be stored either in instance variables of a Tube, or a static ThreadLocal.

The first approach works, because Tube is non reentrant. When a tube is copied, new instances should be allocated so that two Tube instances don't share thread-unsafe resources. Similarly the second approach works, since ThreadLocal guarantees that each thread gets its own private copy.

The former is faster to access, and you need not worry about clean up. On the other hand, because there can be many more concurrent requests than # of threads, you may end up holding onto more resources than necessary.

This includes state like canonicalizers, JAXB unmarshallers, SimpleDateFormat, etc.

Per-proxy/per-endpoint state

Information that is tied to a particular proxy/dispatch can be stored in a separate object that is referenced from a tube. When a new tube is copied, you can simply hand out a reference to the newly created one, so that all copied tubes refer to the same instance. See the following code as an example:

 class TubeImpl {
   // this object stores per-proxy state
   class DataStore {
     int counter;
   }

   private DataStore ds;

   // create a fresh new pipe
   public TubeImpl(...) {
     ....
     ds = new DataStore();
   }

   // copy constructor
   private TubeImpl(TubeImpl that, PipeCloner cloner) {
     cloner.add(that,this);
     ...
     this.ds = that.ds;
   }

   public TubeImpl copy(PipeCloner pc) {
     return new TubeImpl(this,pc);
   }
 }
 

Note that access to such resource may need to be synchronized, since multiple copies of pipelines may execute concurrently.

VM-wide state

static is always there for you to use.

See Also:

AbstractTubeImpl, AbstractFilterTubeImpl

Method Summary

Tube	copy(TubeCloner cloner) Creates an identical clone of this Tube.
void	preDestroy() Invoked before the last copy of the pipeline is about to be discarded, to give Tubes a chance to clean up any resources.
NextAction	processException(java.lang.Throwable t) Acts on a exception and performs some clean up operations.
NextAction	processRequest(Packet request) Acts on a request and perform some protocol specific operation.
NextAction	processResponse(Packet response) Acts on a response and performs some protocol specific operation.

Method Detail

processRequest

@NotNull
NextAction processRequest(@NotNull
                                  Packet request)

Acts on a request and perform some protocol specific operation. TODO: exception handling semantics need more discussion

Parameters:

request - The packet that represents a request message. If the packet has a non-null message, it must be a valid unconsumed Message. This message represents the SOAP message to be sent as a request.

The packet is also allowed to carry no message, which indicates that this is an output-only request. (that's called "solicit", right? - KK)

Returns:

A NextAction object that represents the next action to be taken by the JAX-WS runtime.

Throws:

WebServiceException - On the server side, this signals an error condition where a fault reply is in order (or the exception gets eaten by the top-most transport Adapter if it's one-way.) This frees each Tube from try/catching a WebServiceException in every layer. Note that this method is also allowed to return NextAction.returnWith(Packet) with a Packet that has a fault as the payload.

On the client side, the WebServiceException thrown will be propagated all the way back to the calling client applications. (The consequence of that is that if you are a filtering Tube, you must not eat the exception that was given to processException(Throwable) .

java.lang.RuntimeException - Other runtime exception thrown by this method must be treated as a bug in the tube implementation, and therefore should not be converted into a fault. (Otherwise it becomes very difficult to debug implementation problems.)

On the server side, this exception should be most likely just logged. On the client-side it gets propagated to the client application.

The consequence of this is that if a pipe calls into an user application (such as SOAPHandler or LogicalHandler), where a RuntimeException is *not* a bug in the JAX-WS implementation, it must be catched and wrapped into a WebServiceException.

processResponse

@NotNull
NextAction processResponse(@NotNull
                                   Packet response)

Acts on a response and performs some protocol specific operation.

Once a processRequest(Packet) is invoked, this method will be always invoked with the response, before this Tube processes another request.

Parameters:

response - If the packet has a non-null message, it must be a valid unconsumed Message. This message represents a response to the request message passed to processRequest(Packet) earlier.

The packet is also allowed to carry no message, which indicates that there was no response. This is used for things like one-way message and/or one-way transports. TODO: exception handling semantics need more discussion

Returns:

A NextAction object that represents the next action to be taken by the JAX-WS runtime.

processException

@NotNull
NextAction processException(@NotNull
                                    java.lang.Throwable t)

Acts on a exception and performs some clean up operations.

If a processRequest(Packet), processResponse(Packet), processException(Throwable) throws an exception, this method will be always invoked on all the Tubes in the remaining NextActions.

On the server side, the Throwable thrown will be propagated to the top-most transport. The transport converts the exception to fault reply or simply logs in case of one-way MEP. If you are a filtering Tube like AbstractTubeImpl, you don't have to override the implementation). On the other hand, any intermediate Tube may want to convert the exception to a fault message.

On the client side, the Throwable thrown will be propagated all the way back to the calling client applications. (The consequence of that is that if you are a filtering Tube like AbstractTubeImpl, you don't have to override the implementation)

Parameters:

t -

Returns:

A NextAction object that represents the next action to be taken by the JAX-WS runtime.

preDestroy

void preDestroy()

Invoked before the last copy of the pipeline is about to be discarded, to give Tubes a chance to clean up any resources.

This can be used to invoke PreDestroy lifecycle methods on user handler. The invocation of it is optional on the client side, but mandatory on the server side.

When multiple copies of pipelines are created, this method is called only on one of them.

Throws:

WebServiceException - If the clean up fails, WebServiceException can be thrown. This exception will be propagated to users (if this is client), or recorded (if this is server.)

copy

Tube copy(TubeCloner cloner)

Creates an identical clone of this Tube.

This method creates an identical pipeline that can be used concurrently with this pipeline. When the caller of a pipeline is multi-threaded and need concurrent use of the same pipeline, it can do so by creating copies through this method.

Implementation Note

It is the implementation's responsibility to call TubeCloner.add(Tube,Tube) to register the copied pipe with the original. This is required before you start copying the other Tube references you have, or else there's a risk of infinite recursion.

For most Tube implementations that delegate to another Tube, this method requires that you also copy the Tube that you delegate to.

For limited number of Tubes that do not maintain any thread unsafe resource, it is allowed to simply return this from this method (notice that even if you are stateless, if you got a delegating Tube and that one isn't stateless, you still have to copy yourself.)

Note that this method might be invoked by one thread while another thread is executing the other process method. See the Codec.copy() for more discussion about this.

Parameters:

cloner - Use this object (in particular its TubeCloner.copy(Tube) method to clone other pipe references you have in your pipe. See TubeCloner for more discussion about why.

Returns:

always non-null Tube.