-
- All Known Implementing Classes:
AbstractFilterPipeImpl
,AbstractFilterTubeImpl
,AbstractPipeImpl
,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 Pipe
Deprecated.UseTube
.Abstraction of the intermediate layers in the processing chain and transport.What is a
Pipe
?Transport is a kind of pipe. It sends the
Packet
through, say, HTTP connection, and receives the data back into anotherPacket
.More often, a pipe is a filter. It acts on a packet, and then it passes the packet into another pipe. It can do the same on the way back.
For example, XWSS will be a
Pipe
that delegates to anotherPipe
, and it can wrap aPacket
into anotherPacket
to encrypt the body and add a header, for example.Yet another kind of filter pipe is those that wraps
LogicalHandler
andSOAPHandler
. These pipes are heavy-weight; they often consume a message in a packet and create a new one, and then pass it to the next pipe. For performance reason it probably makes sense to have onePipe
instance that invokes a series ofLogicalHandler
s, another one forSOAPHandler
.There would be a
Pipe
implementation that invokesProvider
. There would be aPipe
implementation that invokes a service method on the user's code. There would be aDispatch
implementation that invokes aPipe
.WS-MEX can be implemented as a
Pipe
that looks forMessage.getPayloadNamespaceURI()
and serves the request.Pipe Lifecycle
Pipe
line is expensive to set up, so once it's created it will be reused. APipe
line is not reentrant; one pipeline is used to process one request/response at at time. The same pipeline instance may serve request/response for different threads, if one comes after another and they don't overlap.Where a need arises to process multiple requests concurrently, a pipeline gets cloned through
PipeCloner
. 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 GCed at any time at the discretion of whoever owns pipelines. Pipes 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.
Pipe and State
The lifecycle of pipelines is designed to allow a
Pipe
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
. This includes information like transport-specific headers.Per-thread state
Any expensive objects that are non-reentrant can be stored in instance variables of a
Pipe
, sinceprocess(Packet)
is non reentrant. When a pipe is copied, new instances should be allocated so that twoPipe
instances don't share thread-unsafe resources. This includes things like canonicalizers, JAXB unmarshallers, buffers, and so on.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 pipe. When a new pipe is copied, you can simply hand out a reference to the newly created one, so that all copied pipes refer to the same instance. See the following code as an example:
class PipeImpl { // this object stores per-proxy state class DataStore { int counter; } private DataStore ds; // create a fresh new pipe public PipeImpl(...) { .... ds = new DataStore(); } // copy constructor private PipeImpl(PipeImpl that, PipeCloner cloner) { cloner.add(that,this); ... this.ds = that.ds; } public PipeImpl copy(PipeCloner pc) { return new PipeImpl(this,pc); } }
Note that access to such resource often needs to be synchronized, since multiple copies of pipelines may execute concurrently.
If such information is read-only, it can be stored as instance variables of a pipe, and its reference copied as pipes get copied. (The only difference between this and per-thread state is that you just won't allocate new things when pipes get copied here.)
VM-wide state
static
is always there for you to use.Pipes and Handlers
JAX-WS has a notion of
LogicalHandler
andSOAPHandler
, and we intend to have onePipe
implementation that invokes all theLogicalHandler
s and anotherPipe
implementation that invokes all theSOAPHandler
s. Those implementations need to convert aMessage
into an appropriate format, but grouping all the handlers together eliminates the intermediateMessage
instanciation between such handlers.This grouping also allows such implementations to follow the event notifications to handlers (i.e.
Handler.close(MessageContext)
method.TODO: Possible types of pipe: creator: create message from wire to SAAJ SOAP message to cached representation directly to JAXB beans transformer: transform message from one representation to another JAXB beans to encoded SOAP message StAX writing + JAXB bean to encoded SOAP message modifier: modify message add SOAP header blocks security processing header block processor: process certain SOAP header blocks outbound initiator: input from the client Manage input e.g. JAXB beans and associated with parts of the SOAP message inbound invoker: invoke the service Inkoke SEI, e.g. EJB or SEI in servlet.
- See Also:
AbstractPipeImpl
,AbstractFilterPipeImpl
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description Pipe
copy(PipeCloner cloner)
Deprecated.Creates an identical clone of thisPipe
.void
preDestroy()
Deprecated.Invoked before the last copy of the pipeline is about to be discarded, to givePipe
s a chance to clean up any resources.Packet
process(Packet request)
Deprecated.
-
-
-
Method Detail
-
process
Packet process(Packet request)
Deprecated.- Parameters:
request
- The packet that represents a request message. Must not be null. If the packet has a non-null message, it must be a valid unconsumedMessage
. 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:
- The packet that represents a response message. Must not be null.
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 as a parameter.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.
- Throws:
javax.xml.ws.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 transportPipe
if it's one-way.) This frees eachPipe
from try/catching aWebServiceException
in every layer. Note that this method is also allowed to return aPacket
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 filteringPipe
, you must not catch the exception that your nextPipe
threw.RuntimeException
- Other runtime exception thrown by this method must be treated as a bug in the pipe 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
orLogicalHandler
), where aRuntimeException
is *not* a bug in the JAX-WS implementation, it must be catched and wrapped into aWebServiceException
.
-
preDestroy
void preDestroy()
Deprecated.Invoked before the last copy of the pipeline is about to be discarded, to givePipe
s 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:
javax.xml.ws.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
Pipe copy(PipeCloner cloner)
Deprecated.Creates an identical clone of thisPipe
.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
PipeCloner.add(Pipe,Pipe)
to register the copied pipe with the original. This is required before you start copying the otherPipe
references you have, or else there's a risk of infinite recursion.For most
Pipe
implementations that delegate to anotherPipe
, this method requires that you also copy thePipe
that you delegate to.For limited number of
Pipe
s that do not maintain any thread unsafe resource, it is allowed to simply returnthis
from this method (notice that even if you are stateless, if you got a delegatingPipe
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
process(Packet)
method. See theCodec.copy()
for more discussion about this.- Parameters:
cloner
- Use this object (in particular itsPipeCloner.copy(Pipe)
method to clone other pipe references you have in your pipe. SeePipeCloner
for more discussion about why.- Returns:
- always non-null
Pipe
.
-
-