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 > SOAP over JMS 1.0 support
Date Thu, 10 Sep 2009 06:49:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="http://cwiki.apache.org/confluence/display/CXF20DOC/SOAP+over+JMS+1.0+support">SOAP
over JMS 1.0 support</a></h2>
    <h4>Page  <b>added</b> by             <a href="http://cwiki.apache.org/confluence/display/~njiang">willem
jiang</a>
    </h4>
         <br/>
    <div class="notificationGreySide">
         <p>SOAP over JMS offers an alternative messaging mechanism to SOAP over HTTP.
SOAP over JMS offers more reliable and scalable messaging support than SOAP over HTTP. </p>

<p><a href="http://www.w3.org/TR/soapjms/" rel="nofollow">SOAP over JMS specification</a>
is aimed at a set of standards for the transport of SOAP messages over JMS. The main purpose
is to ensure interoperability between the implementations of different Web services vendors.
CXF supports SOAP over JMS specification, and is compliant with the specification.</p>

<h2><a name="SOAPoverJMS1.0support-What%27snewcomparetotheoldCXFJMSTransport"></a>What's
new compare to the old CXF JMS Transport</h2>

<p>SOAP over JMS transport supports the most <a href="http://cwiki.apache.org/CXF20DOC/jms-transport.html"
rel="nofollow">configuration of JMS Transport</a> and does some extension to support
the SOAP over JMS specification. Such as jms:address, SOAP over JMS Transport uses <a href="http://www.ietf.org/id/draft-merrick-jms-uri-06.txt"
rel="nofollow">JMS URI</a> to describe the JMS address information and use new WSDL
extension for the configuration of JMS. </p>

<h2><a name="SOAPoverJMS1.0support-SOAPoverJMSNamespace"></a>SOAP over JMS
Namespace</h2>

<h3><a name="SOAPoverJMS1.0support-WSDLNamespace"></a>WSDL Namespace</h3>
<p>The WSDL extensions for defining a JMS endpoint are using this namespace <a href="http://www.w3.org/2008/07/soap/bindings/JMS/"
rel="nofollow">http://www.w3.org/2008/07/soap/bindings/JMS/</a>. In order to use
this JMS WSDL extensions you will need to add the namespace definition shown below to the
definitions element of your contract.</p>

<h3><a name="SOAPoverJMS1.0support-JMSExtensionNamespace"></a>JMS Extension
Namespace</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
xmlns:soapjms=<span class="code-quote">"http:<span class="code-comment">//www.w3.org/2008/07/soap/bindings/JMS/"</span></span>
</pre>
</div></div>

<h2><a name="SOAPoverJMS1.0support-JMSURI"></a>JMS URI</h2>

<p>JMS endpoints need to know the address information about how to establish a connection
to the proper destination. SOAP over JMS implements the <a href="http://www.ietf.org/id/draft-merrick-jms-uri-06.txt"
rel="nofollow">URI Scheme for Java Message Service 1.0</a>. </p>

<p>This URI scheme starts with "jms:jndi:" plus a JNDI name for a Destination. Since
interaction with some resources may require JNDI contextual information or JMS header fields
and properties to be specified as well, the "jndi" variant of the "jms" URI scheme includes
support for supplying this additional JNDI information as query parameters.</p>

<p>CXF supports three variants, "<b>jndi</b>", "<b>queue</b>",
and "<b>topic</b>".<br/>
For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
jms:jndi:SomeJndiNameForDestination?jndiInitialContextFactory=com.example.jndi.JndiFactory&amp;priority=3
jms:queue:ExampleQueueName?timeToLive=1000
</pre>
</div></div>

<p>Properties are as follows:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Property</th>
<th class='confluenceTh'>DefaultVaule</th>
<th class='confluenceTh'>Description</th>
</tr>
<tr>
<td class='confluenceTd'>deliveryMode</td>
<td class='confluenceTd'> PERSISTENT </td>
<td class='confluenceTd'> NON_PERSISTENT  messages will only be kept in memory <br/>
PERSISTENT  messages will be persisted to disk </td>
</tr>
<tr>
<td class='confluenceTd'>jndiConnectionFactoryName</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the JNDI name bound to the JMS connection factory
to use when connecting to the JMS destination.</td>
</tr>
<tr>
<td class='confluenceTd'>jndiInitialContextFactory</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the fully qualified Java class name of the "InitialContextFactory"
implementation class to use.</td>
</tr>
<tr>
<td class='confluenceTd'>jndiURL</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the JNDI provider URL</td>
</tr>
<tr>
<td class='confluenceTd'>replyToName</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Specifies the JNDI name bound to the JMS destinations where
replies are sent. </td>
</tr>
<tr>
<td class='confluenceTd'>priority</td>
<td class='confluenceTd'> 4 </td>
<td class='confluenceTd'>Priority for the messages. See your JMS provider doc for details</td>
</tr>
<tr>
<td class='confluenceTd'>timeToLive</td>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'>After this time the message will be discarded by the jms provider</td>
</tr>
<tr>
<td class='confluenceTd'>Additional JNDI Parameters</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Additional parameters for a JNDI provider.  A custom parameter
name must start with the prefix "jndi-".</td>
</tr>
</tbody></table>

<p>For more details about what information to use in these attributes, please check
out the <a href="http://www.ietf.org/id/draft-merrick-jms-uri-06.txt" rel="nofollow">JMS
URI specification</a>.</p>

<h2><a name="SOAPoverJMS1.0support-WSDLExtension"></a>WSDL Extension</h2>

<p>Various JMS properties may be set in three places in the WSDL — the binding, the
service, and the port. Values specified at the service will propagate to all ports. Values
specified at the binding will propagate to all ports using that binding. <br/>
For example, the <b>jndiInitialContextFactory</b> may be indicated for a service,
and it is then implied for all of the contained port elements.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Field</th>
<th class='confluenceTh'>DefaultVaule</th>
<th class='confluenceTh'>Description</th>
</tr>
<tr>
<td class='confluenceTd'>deliveryMode</td>
<td class='confluenceTd'> PERSISTENT </td>
<td class='confluenceTd'>NON_PERSISTENT  messages will only be kept in memory <br/>
PERSISTENT  messages will be persisted to disk </td>
</tr>
<tr>
<td class='confluenceTd'>jndiConnectionFactoryName</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the JNDI name bound to the JMS connection factory
to use when connecting to the JMS destination.</td>
</tr>
<tr>
<td class='confluenceTd'>jndiInitialContextFactory</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the fully qualified Java class name of the "InitialContextFactory"
implementation class to use.</td>
</tr>
<tr>
<td class='confluenceTd'>jndiURL</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the JNDI provider URL</td>
</tr>
<tr>
<td class='confluenceTd'>replyToName</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Specifies the JNDI name bound to the JMS destinations where
replies are sent. </td>
</tr>
<tr>
<td class='confluenceTd'>priority</td>
<td class='confluenceTd'> 4 </td>
<td class='confluenceTd'>Priority for the messages. See your JMS provider doc for details</td>
</tr>
<tr>
<td class='confluenceTd'>timeToLive</td>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'>After this time the message will be discarded by the jms provider</td>
</tr>
<tr>
<td class='confluenceTd'>jndiContextParameter</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Additional parameters for a JNDI provider.</td>
</tr>
</tbody></table>

<p>An example is as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;wsdl11:binding name=<span class="code-quote">"exampleBinding"</span>&gt;</span>
  <span class="code-tag">&lt;soapjms:jndiContextParameter name=<span class="code-quote">"name"</span>
value=<span class="code-quote">"value"</span> /&gt;</span>
<span class="code-tag">&lt;soapjms:jndiConnectionFactoryName&gt;</span>ConnectionFactory
<span class="code-tag">&lt;/soapjms:jndiConnectionFactoryName&gt;</span>
<span class="code-tag">&lt;soapjms:jndiInitialContextFactory&gt;</span>
org.apache.activemq.jndi.ActiveMQInitialContextFactory
<span class="code-tag">&lt;/soapjms:jndiInitialContextFactory&gt;</span>
<span class="code-tag">&lt;soapjms:jndiURL&gt;</span>tcp://localhost:61616
<span class="code-tag">&lt;/soapjms:jndiURL&gt;</span>
<span class="code-tag">&lt;soapjms:deliveryMode&gt;</span>PERSISTENT<span
class="code-tag">&lt;/soapjms:deliveryMode&gt;</span>
<span class="code-tag">&lt;soapjms:priority&gt;</span>5<span class="code-tag">&lt;/soapjms:priority&gt;</span>
  <span class="code-tag">&lt;soapjms:timeToLive&gt;</span>200<span
class="code-tag">&lt;/soapjms:timeToLive&gt;</span>
<span class="code-tag">&lt;/wsdl11:binding&gt;</span>

<span class="code-tag">&lt;wsdl11:service name=<span class="code-quote">"exampleService"</span>&gt;</span>
  <span class="code-tag">&lt;soapjms:jndiInitialContextFactory&gt;</span>
    com.example.jndi.InitialContextFactory
  <span class="code-tag">&lt;/soapjms:jndiInitialContextFactory&gt;</span>
  <span class="code-tag">&lt;soapjms:timeTolive&gt;</span>100<span
class="code-tag">&lt;/soapjms:timeToLive&gt;</span>
  ...
  <span class="code-tag">&lt;wsdl11:port name=<span class="code-quote">"quickPort"</span>
binding=<span class="code-quote">"tns:exampleBinding"</span>&gt;</span>
    ...
    <span class="code-tag">&lt;soapjms:timeToLive&gt;</span>10<span
class="code-tag">&lt;/soapjms:timeToLive&gt;</span>
  <span class="code-tag">&lt;/wsdl11:port&gt;</span>
  <span class="code-tag">&lt;wsdl11:port name=<span class="code-quote">"slowPort"</span>
binding=<span class="code-quote">"tns:exampleBinding"</span>&gt;</span>
    ...
  <span class="code-tag">&lt;/wsdl11:port&gt;</span>
<span class="code-tag">&lt;/wsdl11:service&gt;</span>
</pre>
</div></div>

<p>If a property is specified at multiple levels, the most specific setting takes precedence
(port first, then service, then binding). In the above example, notice the timeToLive property
— for the quickPort port, the value will be 10 (specified at the port level). For the slowPort
port, the value will be 100 (specified at the service level). The setting in the binding is,
in this example, always overridden.</p>

<h2><a name="SOAPoverJMS1.0support-WSDLUsage"></a>WSDL Usage</h2>
<p>The example is as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;wsdl:definitions name=<span class="code-quote">"JMSGreeterService"</span>
	<span class="code-tag">&lt;wsdl:binding name=<span class="code-quote">"JMSGreeterPortBinding"</span>
type=<span class="code-quote">"tns:JMSGreeterPortType"</span>&gt;</span>
		&lt;soap:binding style=<span class="code-quote">"document"</span>
			transport=<span class="code-quote">"http://www.w3.org/2008/07/soap/bindings/JMS/"</span>
/&gt;
		&lt;soapjms:jndiContextParameter name=<span class="code-quote">"name"</span>
			value=<span class="code-quote">"value"</span> /&gt;
		<span class="code-tag">&lt;soapjms:jndiConnectionFactoryName&gt;</span>ConnectionFactory
		<span class="code-tag">&lt;/soapjms:jndiConnectionFactoryName&gt;</span>
		<span class="code-tag">&lt;soapjms:jndiInitialContextFactory&gt;</span>
			org.apache.activemq.jndi.ActiveMQInitialContextFactory
		<span class="code-tag">&lt;/soapjms:jndiInitialContextFactory&gt;</span>
		<span class="code-tag">&lt;soapjms:jndiURL&gt;</span>tcp://localhost:61616
		<span class="code-tag">&lt;/soapjms:jndiURL&gt;</span>
		<span class="code-tag">&lt;soapjms:deliveryMode&gt;</span>PERSISTENT<span
class="code-tag">&lt;/soapjms:deliveryMode&gt;</span>
		<span class="code-tag">&lt;soapjms:priority&gt;</span>5<span class="code-tag">&lt;/soapjms:priority&gt;</span>
		<span class="code-tag">&lt;soapjms:timeToLive&gt;</span>1000<span
class="code-tag">&lt;/soapjms:timeToLive&gt;</span>
		<span class="code-tag">&lt;wsdl:operation name=<span class="code-quote">"greetMe"</span>&gt;</span>
			<span class="code-tag">&lt;soap:operation soapAction=<span class="code-quote">"test"</span>
style=<span class="code-quote">"document"</span> /&gt;</span>
			<span class="code-tag">&lt;wsdl:input name=<span class="code-quote">"greetMeRequest"</span>&gt;</span>
				<span class="code-tag">&lt;soap:body use=<span class="code-quote">"literal"</span>
/&gt;</span>
			<span class="code-tag">&lt;/wsdl:input&gt;</span>
			<span class="code-tag">&lt;wsdl:output name=<span class="code-quote">"greetMeResponse"</span>&gt;</span>
				<span class="code-tag">&lt;soap:body use=<span class="code-quote">"literal"</span>
/&gt;</span>
			<span class="code-tag">&lt;/wsdl:output&gt;</span>
		<span class="code-tag">&lt;/wsdl:operation&gt;</span>
	<span class="code-tag">&lt;/wsdl:binding&gt;</span>
	<span class="code-tag">&lt;wsdl:service name=<span class="code-quote">"JMSGreeterService"</span>&gt;</span>
		<span class="code-tag">&lt;wsdl:port binding=<span class="code-quote">"tns:JMSGreeterPortBinding"</span>
name=<span class="code-quote">"GreeterPort"</span>&gt;</span>
			<span class="code-tag">&lt;soap:address		location=<span class="code-quote">"jms:jndi:dynamicQueues/test.cxf.jmstransport.queue"</span>
/&gt;</span>
		<span class="code-tag">&lt;/wsdl:port&gt;</span>
	<span class="code-tag">&lt;/wsdl:service&gt;</span>
<span class="code-tag">&lt;/wsdl:definitions&gt;</span>
</pre>
</div></div>

<ul>
	<li>The transport URI in &lt;soap:binding&gt;. It is <a href="http://www.w3.org/2008/07/soap/bindings/JMS/"
rel="nofollow">http://www.w3.org/2008/07/soap/bindings/JMS/</a>.</li>
	<li>The jms: URI in the &lt;soap:address&gt;</li>
	<li>The extension properties in the &lt;soap:binding&gt;</li>
</ul>


<h2><a name="SOAPoverJMS1.0support-PublishinganservicewiththeJAVAAPI"></a>Publishing
an service with the JAVA API</h2>
<p>Some user who doesn't want to get touch with any WSDL stuff could also publish the
endpoint with CXF SOAP over JMS. First you could write as follows.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
        <span class="code-comment">// You just need to set the address with JMS URI
</span>        <span class="code-object">String</span> address = <span
class="code-quote">"jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3"</span>
            + <span class="code-quote">"?jndiInitialContextFactory"</span>
            + <span class="code-quote">"=org.apache.activemq.jndi.ActiveMQInitialContextFactory"</span>
            + <span class="code-quote">"&amp;jndiConnectionFactoryName=ConnectionFactory&amp;jndiURL=tcp:<span
class="code-comment">//localhost:61500"</span>;
</span>        Hello implementor = <span class="code-keyword">new</span>
HelloImpl();
        JaxWsServerFactoryBean svrFactory = <span class="code-keyword">new</span>
JaxWsServerFactoryBean();
        svrFactory.setServiceClass(Hello.class);
        svrFactory.setAddress(address);
        <span class="code-comment">// And specify the transport ID with SOAP over JMS
specification
</span>        svrFactory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID);
        svrFactory.setServiceBean(implementor);
        svrFactory.create();
</pre>
</div></div>

<h2><a name="SOAPoverJMS1.0support-ConsumetheservicewiththeAPI"></a>Consume
the service with the API</h2>

<p>The code how to consumer the service with the SOAP over JMS transport is as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
      <span class="code-keyword">public</span> void invoke() <span class="code-keyword">throws</span>
Exception {
        <span class="code-comment">// You just need to set the address with JMS URI
</span>        <span class="code-object">String</span> address = <span
class="code-quote">"jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3"</span>
            + <span class="code-quote">"?jndiInitialContextFactory"</span>
            + <span class="code-quote">"=org.apache.activemq.jndi.ActiveMQInitialContextFactory"</span>
            + <span class="code-quote">"&amp;jndiConnectionFactoryName=ConnectionFactory&amp;jndiURL=tcp:<span
class="code-comment">//localhost:61500"</span>;
</span>        JaxWsProxyFactoryBean factory = <span class="code-keyword">new</span>
JaxWsProxyFactoryBean();
        <span class="code-comment">// And specify the transport ID with SOAP over JMS
specification
</span>        factory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID);
        factory.setServiceClass(Hello.class);
        factory.setAddress(address);
        Hello client = (Hello)factory.create();
        <span class="code-object">String</span> reply = client.sayHi(<span
class="code-quote">" HI"</span>);
        <span class="code-object">System</span>.out.println(reply);
    }
</pre>
</div></div>

<h2><a name="SOAPoverJMS1.0support-TheDifferencebetweentheSOAPoverJMSandtheCXFoldJMStransportimplementation"></a>The
Difference between the SOAP over JMS and the CXF old JMS transport implementation</h2>
<p>There are some differences between the SOAP over JMS and the CXF old JMS transport
implementation.</p>
<ol>
	<li>The JMS Messages sent by SOAP over JMS transport implementation are in accord with
the SOAP over JMS specification. Then CXF can interoperate with other SOAP over JMS implementation.</li>
	<li>You can use new method for configuration about SOAP over JMS, and it is accord
with the SOAP over JMS specification.</li>
	<li>SOAP over JMS provides more sophisticated error-handling for the message of SOAP/JMS.</li>
</ol>






    </div>
    <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>
       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/SOAP+over+JMS+1.0+support">View
Online</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/SOAP+over+JMS+1.0+support?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
           </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message