Author: buildbot
Date: Tue Sep 18 16:47:27 2012
New Revision: 832374
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/custom-transport.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/custom-transport.html
==============================================================================
--- websites/production/cxf/content/docs/custom-transport.html (original)
+++ websites/production/cxf/content/docs/custom-transport.html Tue Sep 18
16:47:27 2012
@@ -153,7 +153,7 @@ To send a message into a physical channe
HelloWorld hw = service.getHelloWorldPort();
<span class="code-object">String</span> result =
hw.sayHi(TEST_REQUEST); }}
</pre>
-</div></div></li><li>Step2: The CXF runtime selects the correct
TransportFactory based on some criteria (described below)</li><li>Step3: The
CXF runtime calls <em>TransportFactory.getConduit()</em> method to obtain the
conduit</li><li>Step4: The CXF runtime invokes <em>Conduit.prepare()</em> and
passes the outgoing message as an argument</li><li>Step5: Conduit sets own
OutputStream (normally extended CachedOutputStream) as the outgoing message
content</li><li>Step6: CXF runtime processes the outgoing message, calls the
interceptor chain and invokes Conduit.close(Message) method for the outgoing
message.</li><li>Step7: Finally, <em>OutputStream.doClose()</em> for the
outgoing message is invoked</li><li>Step8: In the <em>doClose()</em> method,
the OutputStream class has access to the marshalled outgoing message and
exchange and will send this message to the service using the corresponding
transport protocol</li><li>Step9: In case of one-way communication exchange
will be close
d. Skip to Step 14</li><li>Step10: In case of request-response communication,
the conduit will wait for the service response in a synchronous or asynchronous
manner</li><li>Step11: If a successful response is received, the conduit
creates a new message, sets its context and puts it as In-Message in the
exchange as an incoming message</li><li>Step12: If a fault is instead received,
the Conduit creates a new Message, sets its context and places it as a fault
message in exchange as in-fault message</li><li>Step13: Conduit notifies
incomingObserver (that is ClientImpl object) about the response using
<em>incomingObserver.onMessage()</em> call</li><li>Step14:
<em>Conduit.close(Message)</em> method is invoked for incoming message.
Normally the conduit implementation decreases the reference count with the
service, potentially closing the network connection if the count is
zero.</li><li>Step15: The JAX-WS client code receives the response in sync or
async style</li></ul>
+</div></div></li><li>Step2: The CXF runtime selects the correct
TransportFactory based on some criteria (described below)</li><li>Step3: The
CXF runtime calls <em>TransportFactory.getConduit()</em> method to obtain the
conduit</li><li>Step4: The CXF runtime invokes <em>Conduit.prepare()</em> and
passes the outgoing message as an argument</li><li>Step5: Conduit sets own
OutputStream (normally extended CachedOutputStream) as the outgoing message
content</li><li>Step6: CXF runtime processes outgoing message, calls the
interceptor chain and writes outgoing message to conduit’s OutputStream
stream. Messaging in CXF is stream-oriented; therefore the message normally is
proceed and sent not as one bunch, but as a stream. The last bytes of the
message can still be in processing by sender, but the first already sent to
recipient. Basically it is responsibility of Conduit how to send the message:
using streaming or collecting the whole message and send it at
once</li><li>Step7:
When CXF runtime completely proceeded outgoing message, it invokes
<em>Conduit.close(Message)</em> method. It means that the message is completely
written into <em>OutputStream</em>. Correspondingly,
<em>OutputStream.doClose()</em> method will be called</li><li>Step8: In the
<em>doClose()</em> method, Conduit sends the rest of the message (or whole
message) to recipient</li><li>Step9: In case of one-way communication exchange
will be closed. Skip to Step 14</li><li>Step10: In case of request-response
communication, the conduit will wait for the service response in a synchronous
or asynchronous manner</li><li>Step11: If a successful response is received,
the conduit creates a new message, sets its context and puts it as In-Message
in the exchange as an incoming message</li><li>Step12: If a fault is instead
received, the Conduit creates a new Message, sets its context and places it as
a fault message in exchange as in-fault message</li><li>Step13: Conduit
notifies incomingObse
rver (that is ClientImpl object) about the response using
<em>incomingObserver.onMessage()</em> call</li><li>Step14: Conduit
implementation decreases the reference count with the network connection,
potentially closing the connection if the count is zero</li><li>Step15: The
JAX-WS client code receives the response in sync or async style</li></ul>
<h3><a shape="rect"
name="CustomTransport-SimplifiedServiceWorkflow%3A"></a>Simplified Service
Workflow:</h3>
@@ -163,7 +163,7 @@ To send a message into a physical channe
HelloWorldImpl serverImpl = <span class="code-keyword">new</span>
HelloWorldImpl();
Endpoint.publish(<span class="code-quote">"udp:<span
class="code-comment">//localhost:9000/hello"</span>, serverImpl);</span>
</pre>
-</div></div></li><li>Step2: The CXF runtime selects correct TransportFactory
based on some criteria (described below)</li><li>Step3: The CXF runtime calls
<em>TransportFactory.getDestination()</em> method to obtain the
destination</li><li>Step4: As soon as the CXF runtime activates the endpoint
(adds a listener, etc) the <em>Destination.activate()</em> method will be
automatically invoked</li><li>Step5: The implementation of
<em>Destination.activate()</em> normally opens network transport connections
and listens to incoming requests</li><li>Step6: When a request comes, the
destination creates a message, sets the content and notifies message observer
(that is ChainInitializationObserver object) via
<em>incomingObserver.onMessage()</em> about request. Normally an incoming
connection is saved in a correlation map to be extracted for the appropriate
response.</li><li>Step7: The business service implementation will be called
with the request message. In case of one-way communicat
ion the exchange is now finished. In case of request-response, the business
implementation either returns a response or throws a fault
exception.</li><li>Step8: The CXF Runtime requests a back-channel conduit from
the destination via <em>Destination.getInbuiltBackChannel()</em></li><li>Step9:
The Back-channel conduit's <em>prepare()</em> method will be called with a
response message as argument</li><li>Step10: Back-channel conduit sets its own
OutputStream as a message context</li><li>Step11: CXF runtime processes the
response message, calls the interceptor chain and invokes
<em>Conduit.close(Message)</em> for the response message.</li><li>Step12.
Finally <em>OutputStream.doClose()</em> method for the response message is
invoked</li><li>Step13: In <em>doClose()</em> method the OutputStream class has
access to the marshalled response message and will send this message through
the network as a response to the client. An appropriate incoming connection
normally is extracted fro
m a correlation map.</li></ul>
+</div></div></li><li>Step2: The CXF runtime selects correct TransportFactory
based on some criteria (described below)</li><li>Step3: The CXF runtime calls
<em>TransportFactory.getDestination()</em> method to obtain the
destination</li><li>Step4: As soon as the CXF runtime activates the endpoint
(adds a listener, etc) the <em>Destination.activate()</em> method will be
automatically invoked</li><li>Step5: The implementation of
<em>Destination.activate()</em> normally opens network transport connections
and listens to incoming requests</li><li>Step6: When a request comes, the
destination creates a message, sets the content and notifies message observer
(that is <em>ChainInitializationObserver</em> object) via
<em>incomingObserver.onMessage()</em> about request. Message content is saved
as a stream; therefore runtime and business logic can start processing even not
completely received message. Normally an incoming connection is saved in a
correlation map to be extracted for the
sending of appropriate response</li><li>Step7: The business service
implementation will be called with the request message in stream form. In case
of one-way communication the exchange is now finished. In case of
request-response, the business implementation either returns a response or
throws a fault exception</li><li>Step8: The CXF Runtime requests a back-channel
conduit from the destination via
<em>Destination.getInbuiltBackChannel()</em></li><li>Step9: The Back-channel
conduit's <em>prepare()</em> method will be called with a response message as
argument</li><li>Step10: Back-channel conduit sets its own OutputStream as a
message context</li><li>Step11: CXF runtime processes the response message,
calls the interceptor chain and invokes <em>Conduit.close(Message)</em> for the
response message</li><li>Step12. Finally <em>OutputStream.doClose()</em> method
for the response message is invoked</li><li>Step13: In <em>doClose()</em>
method the <em>OutputStream</em> class has acc
ess to the marshaled response message and will send this message through the
network as a response to the client. In case of streaming, the part of the
message can be already sent to the network at this time, and Conduit just sends
the last part and closes the sending. Normally incoming connection for
specified protocol is cached and created only if necessary</li></ul>
<h2><a shape="rect"
name="CustomTransport-RegistrationofTransportFactory"></a>Registration of
Transport Factory</h2>
@@ -174,15 +174,13 @@ To register transport factory programmat
Bus bus = BusFactory.getThreadDefaultBus();
DestinationFactoryManagerImpl dfm =
bus.getExtension(DestinationFactoryManagerImpl.class);
CustomTransportFactory customTransport = <span
class="code-keyword">new</span> CustomTransportFactory();
- dfm.registerDestinationFactory(<span class="code-quote">"http:<span
class="code-comment">//cxf.apache.org/transports/TRANSPORT_PREFIX"</span>,
customTransport);
-</span> dfm.registerDestinationFactory(<span
class="code-quote">"http:<span
class="code-comment">//cxf.apache.org/transports/TRANSPORT_PREFIX/configuration"</span>,
customTransport);
-</span>
+ dfm.registerDestinationFactory(TRANSPORT_IDENTIFIER, customTransport);
+
ConduitInitiatorManager extension =
bus.getExtension(ConduitInitiatorManager.class);
- extension.registerConduitInitiator(<span class="code-quote">"http:<span
class="code-comment">//cxf.apache.org/transports/TRANSPORT_PREFIX"</span>,
customTransport);
-</span> extension.registerConduitInitiator(<span
class="code-quote">"http:<span
class="code-comment">//cxf.apache.org/transports/TRANSPORT_PREFIX/configuration"</span>,
customTransport);</span>
+ extension.registerConduitInitiator(TRANSPORT_IDENTIFIER, customTransport);
</pre>
</div></div>
-<p>Where TRANSPORT_PREFIX is the protocol of the new transport (http, https,
jms, udp).</p>
+<p>TRANSPORT_IDENTIFIER is unique transport id (normally in form “<a
shape="rect" class="external-link"
href="http://apache.org/transports/PROTOCOL_PREFIX";>http://apache.org/transports/PROTOCOL_PREFIX</a>”).</p>
<p>For Spring configuration, the following could be used instead:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
@@ -191,41 +189,57 @@ To register transport factory programmat
lazy-init=<span class="code-quote">"false"</span>>
<span class="code-tag"><property name=<span
class="code-quote">"transportIds"</span>></span>
<span class="code-tag"><list></span>
- <span class="code-tag"><value></span>http
http://cxf.apache.org/transports/TRANSPORT_PREFIX<span
class="code-tag"></value></span>
- <span
class="code-tag"><value></span>http://cxf.apache.org/transports/TRANSPORT_PREFIX/configuration<span
class="code-tag"></value></span>
+ <span
class="code-tag"><value></span>TRANSPORT_IDENTIFIER<span
class="code-tag"></value></span>
<span class="code-tag"></list></span>
<span class="code-tag"></property></span>
<span class="code-tag"></bean></span>
</pre>
</div></div>
-<p>To define a new transport endpoint in the WSDL document follow these two
steps:<br clear="none">
-a) Set the soap:binding transport attribute to the transport URL value (<a
shape="rect"
href="http://cxf.apache.org/transports/TRANSPORT_PREFIX";>http://cxf.apache.org/transports/TRANSPORT_PREFIX</a>)<br
clear="none">
-b) The Port address element should be bound to namespace equal to the
transport URL in the WSDL XML</p>
-<p>Sample:</p>
+<h2><a shape="rect"
name="CustomTransport-TransportFactoryselection"></a>TransportFactory
selection</h2>
+<p>As far as binding TransportFactory is found, CXF looking for protocol
TransportFactory responsible for physical network communication. In this case
important is method <em>TransportFactory.getUriPrefixes()</em>. This method
returns list of protocol prefixes supported by this TransportFactory. <br
clear="none">
+When CXF client or service try to communicate using URL with specified
protocol prefix (<a shape="rect" class="external-link" href="http://";
rel="nofollow">http://</a>, <a shape="rect" class="external-link"
href="https://"; rel="nofollow">https://</a>, jms://, local://), CXF looks into
registered transport factories map and gets the right one for this prefix. If
no TransportFactory for this protocol is found, CXF throws corresponded
exception.</p>
+
+<p>Client configuration:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
-<pre class="code-xml">
-<wsdl:definitions
- <span class="code-keyword">xmlns:transport</span>=<span
class="code-quote">"http://cxf.apache.org/transports/TRANSPORT_PREFIX";</span>
…> …
-…
-<span class="code-tag"><wsdl:binding name=<span
class="code-quote">"GreeterPortBinding"</span> type=<span
class="code-quote">"tns: GreeterPortType"</span>></span>
- <span class="code-tag"><soap:binding style=<span
class="code-quote">"document"</span> transport=<span
class="code-quote">"http://cxf.apache.org/transports/TRANSPORT_PREFIX";</span>/></span>
+<pre class="code-java">
+<jaxws:client id=<span class="code-quote">"FlightReservationClient"</span>
+ xmlns:serviceNamespace=<span class="code-quote">"http:<span
class="code-comment">//www.apache.org/cxf/samples/FlightReservation"</span>
+</span>
+serviceClass=<span
class="code-quote">"org.apache.cxf.samples.flightreservation.FlightReservation"</span>
+ serviceName=<span
class="code-quote">"serviceNamespace:FlightReservationService"</span>
endpointName=<span
class="code-quote">"serviceNamespace:FlightReservationSOAP"</span>>
+ address=<span class="code-quote">"http:<span
class="code-comment">//localhost:8040/services/FlightReservationService"</span>>
+</span></jaxws:client>
…
-<span class="code-tag"><wsdl:service name=<span
class="code-quote">"GreeterService"</span>></span>
- <span class="code-tag"><wsdl:port binding=<span
class="code-quote">"tns:GreeterPortBinding"</span> name=<span
class="code-quote">"GreeterPort"</span>></span>
- <span class="code-tag"><transport:address location=<span
class="code-quote">"LOCATION_URL"</span>></span>
+</pre>
+</div></div>
+
+<p>TransportFactory class:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
…
+ <span class="code-keyword">private</span> <span
class="code-keyword">static</span> <span class="code-keyword">final</span>
Set<<span class="code-object">String</span>> URI_PREFIXES = <span
class="code-keyword">new</span> HashSet<<span
class="code-object">String</span>>();
+ <span class="code-keyword">static</span> {
+ URI_PREFIXES.add(<span class="code-quote">"http:<span
class="code-comment">//"</span>);
+</span> URI_PREFIXES.add(<span class="code-quote">"https:"</span>);
+ }
+ <span class="code-keyword">public</span> Set<<span
class="code-object">String</span>> getUriPrefixes() {
+ <span class="code-keyword">return</span> URI_PREFIXES;
+ }
</pre>
</div></div>
<h2><a shape="rect"
name="CustomTransport-ConduitandDestinationLifecycle"></a>Conduit and
Destination Lifecycle</h2>
-<p>The conduit and destination lifecycle can be started by the
TransportFactory during every client or service creation. The TransportFactory
can either create a conduit and destination for each request or cache them
based on service endpoint information.</p>
+<p>Destinations are normally created by service on startup and released by
shutdown. Conduits can be either recreated for each request or cached based on
endpoint information for whole client life time. Clients can make concurrent
calls to endpoints using different protocols and bound them to different
conduits.</p>
<h2><a shape="rect" name="CustomTransport-ConcurrencyAspects"></a>Concurrency
Aspects</h2>
-<p>Conduit and destination objects can by concurrently accessed by multiple
threads. Implementations should care about concurrent correlations maps and/or
synchronization primitives.</p>
+<p>Conduit and destination objects can by concurrently accessed by multiple
threads. Implementations should care about thread safety of the class.</p>
+
+<h2><a shape="rect" name="CustomTransport-Streaming"></a>Streaming</h2>
+<p>It is strongly recommended to don’t break streaming in Conduit and
Destination implementations, if physical protocol supports it. CXF is
completely streaming oriented – it causes high performance and
scalability.</p>
<h2><a shape="rect" name="CustomTransport-References"></a>References</h2>
-<p>CXF transport implementations: package
<em>org.apache.cxf.transport.*</em></p>
+<p>What is the start point to understand the CXF transport layer and implement
own transport? I would recommend to read CXF documentation <span
class="error">[CXF transports
overview#http://cxf.apache.org/docs/transports.html]</span> and analyze source
code of existing CXF transports (Local and JMS once are more straightforward).
They are located into packages: org.apache.cxf.transport.local and
org.apache.cxf.transport.jms correspondingly</p>
</div>
</div>
<!-- Content -->
