camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > SOAP
Date Fri, 21 Sep 2012 14:39:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CAMEL&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/CAMEL/SOAP">SOAP</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~davsclaus">Claus
Ibsen</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" >{info} <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{tip:title=Namespace
prefix mapping} <br>See [JAXB] for details how you can control namespace prefix mappings
when marshalling using [SOAP] data format. <br>{tip} <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. ElementNameStrategy <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="SOAP-SOAPDataFormat"></a>SOAP DataFormat</h2>
<p><b>Available as of Camel 2.3</b></p>

<p>SOAP is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data
Format</a> which uses JAXB2 and JAX-WS annotations to marshal and unmarshal SOAP payloads.
It provides the basic features of Apache CXF without need for the CXF Stack.</p>

<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><b>Supported
SOAP versions</b><br />SOAP 1.1 is supported by default. SOAP 1.2 is supported
from Camel 2.11 onwards.</td></tr></table></div>

<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><b>Namespace prefix mapping</b><br
/>See <a href="/confluence/display/CAMEL/JAXB" title="JAXB">JAXB</a> for details
how you can control namespace prefix mappings when marshalling using <a href="/confluence/display/CAMEL/SOAP"
title="SOAP">SOAP</a> data format.</td></tr></table></div>

<h3><a name="SOAP-ElementNameStrategy"></a>ElementNameStrategy</h3>

<p>An element name strategy is used for two purposes. The first is to find a xml element
name for a given object and soap action when marshaling the object into a SOAP message. The
second is to find an Exception class for a given soap fault name.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Strategy </th>
<th class='confluenceTh'> Usage </th>
</tr>
<tr>
<td class='confluenceTd'> QNameStrategy </td>
<td class='confluenceTd'> Uses a fixed qName that is configured on instantiation. Exception
lookup is not supported </td>
</tr>
<tr>
<td class='confluenceTd'> TypeNameStrategy </td>
<td class='confluenceTd'> Uses the name and namespace from the @XMLType annotation of
the given type. If no namespace is set then package-info is used. Exception lookup is not
supported </td>
</tr>
<tr>
<td class='confluenceTd'> ServiceInterfaceStrategy </td>
<td class='confluenceTd'> Uses information from a webservice interface to determine
the type name and to find the exception class for a SOAP fault</td>
</tr>
</tbody></table>
</div>


<p>If you have generated the web service stub code with cxf-codegen or a similar tool
then you probably will want to use the ServiceInterfaceStrategy. In the case you have no annotated
service interface you should use QNameStrategy or TypeNameStrategy.</p>

<h3><a name="SOAP-UsingtheJavaDSL"></a>Using the Java DSL</h3>

<p>The following example uses a named DataFormat of <em>soap</em> which
is configured with the package com.example.customerservice to initialize the <a href="http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBContext.html"
class="external-link" rel="nofollow">JAXBContext</a>. The second parameter is the
ElementNameStrategy. The route is able to marshal normal objects as well as exceptions.  (Note
the below just sends a SOAP Envelope to a queue. A web service provider would actually need
to be listening to the queue for a SOAP call to actually occur, in which case it would be
a one way SOAP request. If you need request reply then you should look at the next example.)</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
SoapJaxbDataFormat soap = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span
class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span>
ServiceInterfaceStrategy(CustomerService.class));
from(<span class="code-quote">"direct:start"</span>)
  .marshal(soap)
  .to(<span class="code-quote">"jms:myQueue"</span>);
</pre>
</div></div>

<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><b>See also</b><br
/>As the SOAP dataformat inherits from the <a href="/confluence/display/CAMEL/JAXB"
title="JAXB">JAXB</a> dataformat most settings apply here as well</td></tr></table></div>

<h4><a name="SOAP-UsingSOAP1.2"></a>Using SOAP 1.2</h4>
<p><b>Available as of Camel 2.11</b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
SoapJaxbDataFormat soap = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span
class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span>
ServiceInterfaceStrategy(CustomerService.class));
soap.setVersion(<span class="code-quote">"1.2"</span>);
from(<span class="code-quote">"direct:start"</span>)
  .marshal(soap)
  .to(<span class="code-quote">"jms:myQueue"</span>);
</pre>
</div></div>

<p>When using XML DSL there is a version attribute you can set on the &lt;soap&gt;
element.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
    <span class="code-tag"><span class="code-comment">&lt;!-- Defining a ServiceInterfaceStrategy
for retrieving the element name when marshalling --&gt;</span></span>
    <span class="code-tag">&lt;bean id=<span class="code-quote">"myNameStrategy"</span>
class=<span class="code-quote">"org.apache.camel.dataformat.soap.name.ServiceInterfaceStrategy"</span>&gt;</span>
    	<span class="code-tag">&lt;constructor-arg value=<span class="code-quote">"com.example.customerservice.CustomerService"</span>/&gt;</span>
	<span class="code-tag">&lt;constructor-arg value=<span class="code-quote">"true"</span>/&gt;</span>
    <span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>

<p>And in the Camel route</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;route&gt;</span>
  <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
  <span class="code-tag">&lt;marshal&gt;</span>
    <span class="code-tag">&lt;soap contentPath=<span class="code-quote">"com.example.customerservice"</span>
version=<span class="code-quote">"1.2"</span> elementNameStrategyRef=<span
class="code-quote">"myNameStrategy"</span>/&gt;</span>
  <span class="code-tag">&lt;/marshal&gt;</span>
  <span class="code-tag">&lt;to uri=<span class="code-quote">"jms:myQueue"</span>/&gt;</span>
<span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>


<h3><a name="SOAP-MultipartMessages"></a>Multi-part Messages</h3>
<p><b>Available as of Camel 2.8.1</b> </p>

<p>Multi-part SOAP messages are supported by the ServiceInterfaceStrategy. The ServiceInterfaceStrategy
must be initialized with a service interface definition that is annotated in accordance with
JAX-WS 2.2 and meets the requirements of the Document Bare style. The target method must meet
the following criteria, as per the JAX-WS specification:  1) it must have at most one <tt>in</tt>
or <tt>in/out</tt> non-header parameter, 2) if it has a return type other than
<tt>void</tt> it must have no <tt>in/out</tt> or <tt>out</tt>
non-header parameters, 3) if it it has a return type of <tt>void</tt> it must
have at most one <tt>in/out</tt> or <tt>out</tt> non-header parameter.</p>

<p>The ServiceInterfaceStrategy should be initialized with a boolean parameter that
indicates whether the mapping strategy applies to the request parameters or response parameters.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ServiceInterfaceStrategy strat =  <span class="code-keyword">new</span> ServiceInterfaceStrategy(com.example.customerservice.multipart.MultiPartCustomerService.class,
<span class="code-keyword">true</span>);
SoapJaxbDataFormat soapDataFormat = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span
class="code-quote">"com.example.customerservice.multipart"</span>, strat);
</pre>
</div></div>

<h4><a name="SOAP-MultipartRequest"></a>Multi-part Request</h4>

<p>The payload parameters for a multi-part request are initiazlied using a <tt>BeanInvocation</tt>
object that reflects the signature of the target operation. The camel-soap DataFormat maps
the content in the <tt>BeanInvocation</tt> to fields in the SOAP header and body
in accordance with the JAX-WS mapping when the <tt>marshal()</tt> processor is
invoked. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
BeanInvocation beanInvocation = <span class="code-keyword">new</span> BeanInvocation();

<span class="code-comment">// Identify the target method
</span>beanInvocation.setMethod(MultiPartCustomerService.class.getMethod(<span class="code-quote">"getCustomersByName"</span>,

    GetCustomersByName.class, com.example.customerservice.multipart.Product.class));

<span class="code-comment">// Populate the method arguments
</span>GetCustomersByName getCustomersByName = <span class="code-keyword">new</span>
GetCustomersByName();
getCustomersByName.setName(<span class="code-quote">"Dr. Multipart"</span>);
                
Product product = <span class="code-keyword">new</span> Product();
product.setName(<span class="code-quote">"Multiuse Product"</span>);
product.setDescription(<span class="code-quote">"Useful <span class="code-keyword">for</span>
lots of things."</span>);
                
<span class="code-object">Object</span>[] args = <span class="code-keyword">new</span>
<span class="code-object">Object</span>[] {getCustomersByName, product};

<span class="code-comment">// Add the arguments to the bean invocation
</span>beanInvocation.setArgs(args);

<span class="code-comment">// Set the bean invocation object as the message body
</span>exchange.getIn().setBody(beanInvocation); 
</pre>
</div></div>

<h4><a name="SOAP-MultipartResponse"></a>Multi-part Response</h4>

<p>A multi-part soap response may include an element in the soap body and will have
one or more elements in the soap header.  The camel-soap DataFormat will unmarshall the element
in the soap body (if it exists) and place it onto the body of the out message in the exchange.
 Header elements will <b>not</b> be marshaled into their JAXB mapped object types.
 Instead, these elements are placed into the camel out message header <tt>org.apache.camel.dataformat.soap.UNMARSHALLED_HEADER_LIST</tt>.
The elements will appear either as element instance values, or as JAXBElement values, depending
upon the setting for the <tt>ignoreJAXBElement</tt> property. This property is
inherited from camel-jaxb.</p>

<p>You can also have the camel-soap DataFormate ignore header content all-together by
setting the <tt>ignoreUnmarshalledHeaders</tt> value to <tt>true</tt>.
</p>

<h4><a name="SOAP-HolderObjectmapping"></a>Holder Object mapping</h4>

<p>JAX-WS specifies the use of a type-parameterized <tt>javax.xml.ws.Holder</tt>
object for <tt>In/Out</tt> and <tt>Out</tt> parameters.  A <tt>Holder</tt>
object may be used when building the <tt>BeanInvocation</tt>, or you may use an
instance of the parameterized-type directly.  The camel-soap DataFormat marshals Holder values
in accordance with the JAXB mapping for the class of the <tt>Holder</tt>'s value.
 No mapping is provided for <tt>Holder</tt> objects in an unmarshalled response.</p>

<h3><a name="SOAP-Examples"></a>Examples</h3>

<h4><a name="SOAP-Webserviceclient"></a>Webservice client</h4>

<p>The following route supports marshalling the request and unmarshalling a response
or fault. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> WS_URI = <span class="code-quote">"cxf:<span
class="code-comment">//http://myserver/customerservice?serviceClass=com.example.customerservice&amp;dataFormat=MESSAGE"</span>;
</span>SoapJaxbDataFormat soapDF = <span class="code-keyword">new</span>
SoapJaxbDataFormat(<span class="code-quote">"com.example.customerservice"</span>,
<span class="code-keyword">new</span> ServiceInterfaceStrategy(CustomerService.class));
from(<span class="code-quote">"direct:customerServiceClient"</span>)
  .onException(Exception.class)
    .handled(<span class="code-keyword">true</span>)
    .unmarshal(soapDF)
  .end()
  .marshal(soapDF)
  .to(WS_URI)
  .unmarshal(soapDF);
</pre>
</div></div>

<p>The below snippet creates a proxy for the service interface and makes a SOAP call
to the above route. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.camel.Endpoint;
<span class="code-keyword">import</span> org.apache.camel.component.bean.ProxyHelper;
...

Endpoint startEndpoint = context.getEndpoint(<span class="code-quote">"direct:customerServiceClient"</span>);
<span class="code-object">ClassLoader</span> classLoader = <span class="code-object">Thread</span>.currentThread().getContextClassLoader();
<span class="code-comment">// CustomerService below is the service endpoint <span
class="code-keyword">interface</span>, *not* the javax.xml.ws.Service subclass
</span>CustomerService proxy = ProxyHelper.createProxy(startEndpoint, classLoader, CustomerService.class);
GetCustomersByNameResponse response = proxy.getCustomersByName(<span class="code-keyword">new</span>
GetCustomersByName());
</pre>
</div></div>

<h4><a name="SOAP-WebserviceServer"></a>Webservice Server</h4>

<p>Using the following route sets up a webservice server that listens on jms queue customerServiceQueue
and processes requests using the class CustomerServiceImpl. The customerServiceImpl of course
should implement the interface CustomerService. Instead of directly instantiating the server
class it could be defined in a spring context as a regular bean.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
SoapJaxbDataFormat soapDF = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span
class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span>
ServiceInterfaceStrategy(CustomerService.class));
CustomerService serverBean = <span class="code-keyword">new</span> CustomerServiceImpl();
from(<span class="code-quote">"jms:<span class="code-comment">//queue:customerServiceQueue"</span>)
</span>  .onException(Exception.class)
    .handled(<span class="code-keyword">true</span>)
    .marshal(soapDF)
  .end()
  .unmarshal(soapDF)
  .bean(serverBean)
  .marshal(soapDF);
</pre>
</div></div>

<h3><a name="SOAP-Dependencies"></a>Dependencies</h3>

<p>To use the SOAP dataformat in your camel routes you need to add the following dependency
to your pom.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.apache.camel<span
class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>camel-soap<span class="code-tag">&lt;/artifactId&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>2.3.0<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</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/CAMEL/SOAP">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=14811197&revisedVersion=23&originalVersion=22">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/SOAP?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message