cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > JAX-WS Dispatch API
Date Fri, 02 Dec 2011 14:25:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-WS+Dispatch+API">JAX-WS
Dispatch API</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~coheigea@apache.org">Colm
O hEigeartaigh</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>    QName portName = new
QName(&quot;http://org.apache.cxf&quot;, &quot;stockQuoteReporterPort&quot;);
<br></td></tr>
            <tr><td class="diff-changed-lines" >Dispatch&lt;DOMSource&gt;
dispatch = <span class="diff-changed-words"><span class="diff-added-chars"style="background-color:
#dfd;">s.</span>createDispatch(portName,</span> <br></td></tr>
            <tr><td class="diff-unchanged" >                                 
                DOMSource.class, <br>                                              
   Service.Mode.PAYLOAD); <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="JAX-WSDispatchAPI-UsageModes"></a>Usage Modes</h2>


<h3><a name="JAX-WSDispatchAPI-Overview"></a>Overview</h3>

<p><tt>Dispatch</tt> objects have two <em>usage modes</em>:</p>
<ul>
	<li>Message mode</li>
	<li>Message Payload mode (Payload mode)</li>
</ul>


<p>The usage mode you specify for a <tt>Dispatch</tt> object determines
the amount of detail is passed to the user level code.</p>

<h3><a name="JAX-WSDispatchAPI-Messagemode"></a>Message mode</h3>

<p>In <em>message mode</em>, a <tt>Dispatch</tt> object works
with complete messages. A complete message includes any binding specific headers and wrappers.
For example, a consumer interacting with a service that requires SOAP messages would need
to provide the <tt>Dispatch</tt> object's <tt>invoke()</tt> method
a fully specified SOAP message. The <tt>invoke()</tt> method will also return
a fully specified SOAP message. The consumer code is responsible for completing and reading
the SOAP message's headers and the SOAP message's envelope information.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>Message mode is not ideal when
you wish to work with JAXB objects.</td></tr></table></div>
<p>You specify that a <tt>Dispatch</tt> object uses message mode by providing
the value <tt>java.xml.ws.Service.Mode.MESSAGE</tt> when creating the Dispatch
object.</p>

<h3><a name="JAX-WSDispatchAPI-Payloadmode"></a>Payload mode</h3>

<p>In <em>payload mode</em>, also called message payload mode, a <tt>Dispatch</tt>
object works with only the payload of a message. For example, a <tt>Dispatch</tt>
object working in payload mode works only with the body of a SOAP message. The binding layer
processes any binding level wrappers and headers. When a result is returned from <tt>invoke()</tt>
the binding level wrappers and headers are already striped away and only the body of the message
is left.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>When working with a binding that
does not use special wrappers, such as the Artix ESB XML binding, payload mode and message
mode provide the same results.</td></tr></table></div>
<p>You specify that a <tt>Dispatch</tt> object uses payload mode by providing
the value <tt>java.xml.ws.Service.Mode.PAYLOAD</tt> when creating the <tt>Dispatch</tt>
object.</p>

<h2><a name="JAX-WSDispatchAPI-DataTypes"></a>Data Types</h2>


<h3><a name="JAX-WSDispatchAPI-Overview"></a>Overview</h3>

<p><tt>Dispatch</tt> objects, because they are low-level objects, are not
optimized for using the same JAXB generated types as the higher level consumer APIs. <tt>Dispatch</tt>
objects work with the following types of objects:</p>
<ul>
	<li><tt>javax.xml.transform.Source</tt></li>
	<li><tt>javax.xml.soap.SOAPMessage</tt></li>
	<li><tt>javax.activation.DataSource</tt></li>
	<li>JAXB</li>
</ul>


<h3><a name="JAX-WSDispatchAPI-Using%7B%7BSource%7D%7Dobjects"></a>Using
<tt>Source</tt> objects</h3>

<p>A <tt>Dispatch</tt> object can accept and return objects that are derived
from the <tt>javax.xml.transform.Source</tt> interface. Source objects are low
level objects that hold XML documents. Each <tt>Source</tt> implementation provides
methods that access the stored XML documents and manipulate its contents. The following objects
implement the <tt>Source</tt> interface:</p>
<ul>
	<li><tt>DOMSource</tt></li>
	<li><tt>SAXSource</tt></li>
	<li><tt>StreamSource</tt>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>When using <tt>Source</tt>
objects the developer is responsible for ensuring that all required binding specific wrappers
are added to the message. For example, when interacting with a service expecting SOAP messages,
the developer must ensure that the required SOAP envelope is added to the outgoing request
and that the SOAP envelope's contents are correct.</td></tr></table></div></li>
</ul>


<h3><a name="JAX-WSDispatchAPI-Using%7B%7BSOAPMessage%7D%7Dobjects"></a>Using
<tt>SOAPMessage</tt> objects</h3>

<p><tt>Dispatch</tt> objects can use <tt>javax.xml.soap.SOAPMessage</tt>
objects when the following conditions are true:</p>
<ul>
	<li>the <tt>Dispatch</tt> object is using the SOAP binding.</li>
	<li>the <tt>Dispatch</tt> object is using message mode.</li>
</ul>


<h3><a name="JAX-WSDispatchAPI-Using%7B%7BDataSource%7D%7Dobjects"></a>Using
<tt>DataSource</tt> objects</h3>

<p><tt>Dispatch</tt> objects can use objects that implement the <tt>javax.activation.DataSource</tt>
interface when the following conditions are true:</p>
<ul>
	<li>the <tt>Dispatch</tt> object is using the HTTP binding.</li>
	<li>the <tt>Dispatch</tt> object is using message mode.</li>
</ul>


<p><tt>DataSource</tt> objects provide a mechanism for working with MIME
typed data from a variety of sources including URLs, files, and byte arrays.</p>

<h3><a name="JAX-WSDispatchAPI-UsingJAXBobjects"></a>Using JAXB objects</h3>

<p>While <tt>Dispatch</tt> objects are intended to be low level API that
allows you to work with raw messages, they also allow you to work with JAXB objects. To work
with JAXB objects a <tt>Dispatch</tt> object must be passed a <tt>JAXBContext</tt>
that knows how to marshal and unmarshal the JAXB objects in use. The <tt>JAXBContext</tt>
is passed when the <tt>Dispatch</tt> object is created.</p>

<p>You can pass any JAXB object understood by the <tt>JAXBContext</tt> object
as the parameter to the <tt>invoke()</tt> method. You can also cast the returned
message into any JAXB object understood by the <tt>JAXBContext</tt> object.</p>

<h2><a name="JAX-WSDispatchAPI-Workingwith%7B%7BDispatch%7D%7DObjects"></a>Working
with <tt>Dispatch</tt> Objects</h2>


<h3><a name="JAX-WSDispatchAPI-Procedure"></a>Procedure</h3>

<p>To use a Dispatch object to invoke a remote service you do the following:</p>
<ol>
	<li>Create a <tt>Dispatch</tt> object.</li>
	<li>Construct a request message.</li>
	<li>Call the proper <tt>invoke()</tt> method.</li>
	<li>Parse the response message.</li>
</ol>


<h3><a name="JAX-WSDispatchAPI-Creatinga%7B%7BDispatch%7D%7Dobject"></a>Creating
a <tt>Dispatch</tt> object</h3>

<p>To create a <tt>Dispatch</tt> object do the following:</p>
<ol>
	<li>Create a <tt>Service</tt> object to represent the <tt>wsdl:service</tt>
element defining the service on which the <tt>Dispatch</tt> object will make invocations.</li>
	<li>Create the <tt>Dispatch</tt> object using the <tt>Service</tt>
object's <tt>createDispatch()</tt> method.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> Dispatch&lt;T&gt; createDispatch(QName
portName, java.lang.<span class="code-object">Class</span>&lt;T&gt; type,
Service.Mode mode)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>If you are using JAXB objects
the method signature for <tt>createDispatch()</tt> is:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> Dispatch&lt;T&gt; createDispatch(QName
portName, javax.xml.bind.JAXBContext context, Service.Mode mode)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div></td></tr></table></div></li>
</ol>


<p>The following table describes the parameters for <tt>createDispatch()</tt>.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> portName </td>
<td class='confluenceTd'> Specifies the QName of the <tt>wsdl:port</tt>
element that represent the service provider on which the <tt>Dispatch</tt> object
will make invocations. </td>
</tr>
<tr>
<td class='confluenceTd'> type </td>
<td class='confluenceTd'> Specifies the data type of the objects used by the <tt>Dispatch</tt>
object. </td>
</tr>
<tr>
<td class='confluenceTd'> mode </td>
<td class='confluenceTd'> Specifies the usage mode for the <tt>Dispatch</tt>
object. </td>
</tr>
</tbody></table>
</div>


<p>The code below creates a <tt>Dispatch</tt> object that works with <tt>DOMSource</tt>
objects in payload mode.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> com.mycompany.demo;

<span class="code-keyword">import</span> javax.xml.namespace.QName;
<span class="code-keyword">import</span> javax.xml.ws.Service;

<span class="code-keyword">public</span> class Client
{
<span class="code-keyword">public</span> <span class="code-keyword">static</span>
void main(<span class="code-object">String</span> args[])
  {
    QName serviceName = <span class="code-keyword">new</span> QName(<span class="code-quote">"http:<span
class="code-comment">//org.apache.cxf"</span>, <span class="code-quote">"stockQuoteReporter"</span>);
</span>    Service s = Service.create(serviceName);

    QName portName = <span class="code-keyword">new</span> QName(<span class="code-quote">"http:<span
class="code-comment">//org.apache.cxf"</span>, <span class="code-quote">"stockQuoteReporterPort"</span>);
</span>    Dispatch&lt;DOMSource&gt; dispatch = s.createDispatch(portName,
                                                  DOMSource.class,
                                                  Service.Mode.PAYLOAD);
    ...
</pre>
</div></div>

<h3><a name="JAX-WSDispatchAPI-Constructingrequestmessages"></a>Constructing
request messages</h3>

<p>When working with <tt>Dispatch</tt> objects requests must be built from
scratch. The developer is responsible for ensuring that the messages passed to a <tt>Dispatch</tt>
object match a request that the targeted service provider can process. This requires precise
knowledge about the messages used by the service provider and what, if any, header information
it requires.</p>

<p>This information can be provided by a WSDL document or an XMLSchema document that
defines the messages. While service providers vary greatly there are a few guidelines that
can be followed:</p>
<ul>
	<li>The root element of the request is based in the value of the name attribute of
the <tt>wsdl:operation</tt> element that corresponds to the operation being invoked.
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>If the service being
invoked uses doc/literal bare messages, the root element of the request will be based on the
value of name attribute of the <tt>wsdl:part</tt> element refered to by the <tt>wsdl:operation</tt>
element.</td></tr></table></div></li>
	<li>The root element of the request will be namespace qualified.</li>
	<li>If the service being invoked uses rpc/literal messages, the top-level elements
in the request will not be namespace qualified.
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>The children of top-level
elements may be namespace qualified. To be certain you will need to check their schema definitions.</td></tr></table></div></li>
	<li>If the service being invoked uses rpc/literal messages, none of the top-level elements
can be null.</li>
	<li>If the service being invoked uses doc/literal messages, the schema definition of
the message determines if any of the elements are namespace qualified.</li>
</ul>


<p>For more information about how services use XML messages see the WS-I Basic Profile.</p>

<h3><a name="JAX-WSDispatchAPI-Synchronousinvocation"></a>Synchronous invocation</h3>

<p>For consumers that make synchronous invocations that generate a response, you use
the <tt>Dispatch</tt> object's <tt>invoke()</tt> method shown bellow.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
T invoke(T msg)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div>
<p>The type of both the response and the request passed to the <tt>invoke()</tt>
method are determined when the Dispatch object is created. For example if you created a <tt>Dispatch</tt>
object using <tt>createDispatch(portName, SOAPMessage.class, Service.Mode.MESSAGE)</tt>
the response and the request would both be <tt>SOAPMessage</tt> objects.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>When using JAXB objects, the response
and the request can be of any type the provided <tt>JAXBContext</tt> object can
marshal and unmarshal. Also, the response and the request can be different JAXB objects.</td></tr></table></div>
<p>The code bellow makes a synchronous invocation on a remote service using a <tt>DOMSource</tt>
object.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// Creating a DOMSource <span class="code-object">Object</span>
<span class="code-keyword">for</span> the request
</span>DocumentBuilder db = DocumentBuilderFactory.newDocumentBuilder();
Document requestDoc = db.newDocument();
Element root = requestDoc.createElementNS(<span class="code-quote">"http:<span class="code-comment">//org.apache.cxf/stockExample"</span>,

</span>   <span class="code-quote">"getStockPrice"</span>);
root.setNodeValue(<span class="code-quote">"DOW"</span>);
DOMSource request = <span class="code-keyword">new</span> DOMSource(requestDoc);

<span class="code-comment">// Dispatch disp created previously
</span>DOMSource response = disp.invoke(request);
</pre>
</div></div>

<h4><a name="JAX-WSDispatchAPI-Asynchronousinvocation"></a>Asynchronous
invocation</h4>

<p><tt>Dispatch</tt> objects also support asynchronous invocations. As with
the higher level asynchronous APIs discussed in Chapter 4, <tt>Dispatch</tt> objects
can use both the polling approach and the callback approach.</p>

<p>When using the polling approach the <tt>invokeAsync()</tt> method returns
a <tt>Response&lt;t&gt;</tt> object that can be periodically polled to
see if the response has arrived.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Response &lt;T&gt; invokeAsync(T msg)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div>

<p>When using the callback approach the <tt>invokeAsync()</tt> method takes
an <tt>AsyncHandler</tt> implementation that processes the response when it is
returned.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Future&lt;?&gt; invokeAsync(T msg, AsyncHandler&lt;T&gt; handler)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>As with the synchronous <tt>invoke()</tt>
method, the type of the response and the type of the request are determined when you create
the <tt>Dispatch</tt> object.</td></tr></table></div>

<h4><a name="JAX-WSDispatchAPI-Onewayinvocation"></a>Oneway invocation</h4>

<p>When a request does not generate a response, you make remote invocations using the
<tt>Dispatch</tt> object's <tt>invokeOneWay()</tt>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
void invokeOneWay(T msg)
<span class="code-keyword">throws</span> WebServiceException;
</pre>
</div></div>
<p>The type of object used to package the request is determined when the <tt>Dispatch</tt>
object is created. For example if the <tt>Dispatch</tt> object is created using
<tt>createDispatch(portName, DOMSource.class, Service.Mode.PAYLOAD)</tt> the request
would be packaged into a <tt>DOMSource</tt> object.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>When using JAXB objects, the response
and the request can be of any type the provided <tt>JAXBContext</tt> object can
marshal and unmarshal. Also, the response and the request can be different JAXB objects.</td></tr></table></div>
<p>The code bellow makes a one way invocation on a remote service using a JAXB object.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// Creating a JAXBContext and an Unmarshaller <span class="code-keyword">for</span>
the request
</span>JAXBContext jbc = JAXBContext.newInstance(<span class="code-quote">"com.mycompany.StockExample"</span>);
Unmarshaller u = jbc.createUnmarshaller();

<span class="code-comment">// Read the request from disk
</span>File rf = <span class="code-keyword">new</span> File(<span class="code-quote">"request.xml"</span>);
GetStockPrice request = (GetStockPrice)u.unmarshal(rf);

<span class="code-comment">// Dispatch disp created previously
</span>disp.invokeOneWay(request);
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-WS+Dispatch+API">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=59882&revisedVersion=7&originalVersion=6">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-WS+Dispatch+API?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message