cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r832374 - in /websites/production/cxf/content: cache/docs.pageCache docs/custom-transport.html
Date Tue, 18 Sep 2012 16:47:28 GMT
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&#8217;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 &#8220;<a shape="rect"
class="external-link" href="http://apache.org/transports/PROTOCOL_PREFIX">http://apache.org/transports/PROTOCOL_PREFIX</a>&#8221;).</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>&gt;
 		<span class="code-tag">&lt;property name=<span class="code-quote">"transportIds"</span>&gt;</span>
 			<span class="code-tag">&lt;list&gt;</span>
-			<span class="code-tag">&lt;value&gt;</span>http http://cxf.apache.org/transports/TRANSPORT_PREFIX<span
class="code-tag">&lt;/value&gt;</span>
-                	<span class="code-tag">&lt;value&gt;</span>http://cxf.apache.org/transports/TRANSPORT_PREFIX/configuration<span
class="code-tag">&lt;/value&gt;</span>
+			  <span class="code-tag">&lt;value&gt;</span>TRANSPORT_IDENTIFIER<span
class="code-tag">&lt;/value&gt;</span>
 			<span class="code-tag">&lt;/list&gt;</span>
 		<span class="code-tag">&lt;/property&gt;</span>
 	<span class="code-tag">&lt;/bean&gt;</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">
-&lt;wsdl:definitions 
-    <span class="code-keyword">xmlns:transport</span>=<span class="code-quote">"http://cxf.apache.org/transports/TRANSPORT_PREFIX"</span>
&#8230;&gt; &#8230;
-&#8230;
-<span class="code-tag">&lt;wsdl:binding name=<span class="code-quote">"GreeterPortBinding"</span>
type=<span class="code-quote">"tns: GreeterPortType"</span>&gt;</span>
-        <span class="code-tag">&lt;soap:binding style=<span class="code-quote">"document"</span>
transport=<span class="code-quote">"http://cxf.apache.org/transports/TRANSPORT_PREFIX"</span>/&gt;</span>
+<pre class="code-java">
+&lt;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>&gt;
+	address=<span class="code-quote">"http:<span class="code-comment">//localhost:8040/services/FlightReservationService"</span>&gt;
+</span>&lt;/jaxws:client&gt;
 &#8230;
-<span class="code-tag">&lt;wsdl:service name=<span class="code-quote">"GreeterService"</span>&gt;</span>
-       <span class="code-tag">&lt;wsdl:port binding=<span class="code-quote">"tns:GreeterPortBinding"</span>
name=<span class="code-quote">"GreeterPort"</span>&gt;</span>
-           <span class="code-tag">&lt;transport:address location=<span class="code-quote">"LOCATION_URL"</span>&gt;</span>
+</pre>
+</div></div>
+
+<p>TransportFactory class:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
 &#8230;
+    <span class="code-keyword">private</span> <span class="code-keyword">static</span>
<span class="code-keyword">final</span> Set&lt;<span class="code-object">String</span>&gt;
URI_PREFIXES = <span class="code-keyword">new</span> HashSet&lt;<span class="code-object">String</span>&gt;();
+    <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&lt;<span class="code-object">String</span>&gt;
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&#8217;t break streaming in Conduit and Destination
implementations, if physical protocol supports it. CXF is completely streaming oriented &#8211;
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 -->



Mime
View raw message