cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Daniel Kulp (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache CXF Documentation > SOAP over JMS 1.0 support
Date Thu, 22 Aug 2013 17:23:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/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/SOAP+over+JMS+1.0+support">SOAP
over JMS 1.0 support</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~dkulp">Daniel
Kulp</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" >h3. JMS Extension Namespace <br>{code}
<br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">xmlns:soapjms=&quot;http://www.w3.org/2008/07/soap/bindings/JMS/&quot;</span>
<span class="diff-added-words"style="background-color: #dfd;">xmlns:soapjms=&quot;http://www.w3.org/2010/soapjms/&quot;</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>The <a href="/confluence/display/CXF20DOC/JMS+Transport" title="JMS Transport">JMS
Transport</a> offers an alternative messaging mechanism to SOAP over HTTP. SOAP over
JMS offers more reliable and scalable messaging support than SOAP over HTTP.  The <a href="http://www.w3.org/TR/soapjms/"
class="external-link" rel="nofollow">SOAP over JMS specification</a> is aimed at
a set of standards for the transport of SOAP messages over JMS. Its main purpose is to ensure
interoperability between the implementations of different Web services vendors. CXF supports
and is compliant with this specification.</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 use a special namespace.  In order
to use the 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="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
xmlns:soapjms="http://www.w3.org/2010/soapjms/"
</pre>
</div></div>

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

<p>JMS endpoints need to know the address information for establishing connections to
the proper destination. SOAP over JMS implements the <a href="http://tools.ietf.org/id/draft-merrick-jms-uri-06.txt"
class="external-link" 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="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
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>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Property</th>
<th class='confluenceTh'>DefaultValue</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 kept only in memory <br/>
PERSISTENT messages will be saved 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 documentation
for details</td>
</tr>
<tr>
<td class='confluenceTd'>timeToLive</td>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'>Time (in ms) after which 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>
</div>


<p>For more details about these attributes, please check out the <a href="http://tools.ietf.org/id/draft-merrick-jms-uri-06.txt"
class="external-link" 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, if the <b>jndiInitialContextFactory</b> is indicated for a service,
it will be used for all of the port elements it contains.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Field</th>
<th class='confluenceTh'>DefaultValue</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 saved 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'>Time (in ms) after which 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>
</div>


<p>Here is an example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;wsdl11:binding name="exampleBinding"&gt;
  &lt;soapjms:jndiContextParameter name="name" value="value" /&gt;
  &lt;soapjms:jndiConnectionFactoryName&gt;ConnectionFactory
  &lt;/soapjms:jndiConnectionFactoryName&gt;
  &lt;soapjms:jndiInitialContextFactory&gt;
    org.apache.activemq.jndi.ActiveMQInitialContextFactory
  &lt;/soapjms:jndiInitialContextFactory&gt;
  &lt;soapjms:jndiURL&gt;tcp://localhost:61616
  &lt;/soapjms:jndiURL&gt;
  &lt;soapjms:deliveryMode&gt;PERSISTENT&lt;/soapjms:deliveryMode&gt;
  &lt;soapjms:priority&gt;5&lt;/soapjms:priority&gt;
  &lt;soapjms:timeToLive&gt;200&lt;/soapjms:timeToLive&gt;
&lt;/wsdl11:binding&gt;

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

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

<h2><a name="SOAPoverJMS1.0support-WSDLUsage"></a>WSDL Usage</h2>
<p>For this example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;wsdl:definitions name="JMSGreeterService"
	&lt;wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType"&gt;
		&lt;soap:binding style="document"
			transport="http://www.w3.org/2010/soapjms/" /&gt;
		&lt;soapjms:jndiContextParameter name="name"
			value="value" /&gt;
		&lt;soapjms:jndiConnectionFactoryName&gt;ConnectionFactory
		&lt;/soapjms:jndiConnectionFactoryName&gt;
		&lt;soapjms:jndiInitialContextFactory&gt;
			org.apache.activemq.jndi.ActiveMQInitialContextFactory
		&lt;/soapjms:jndiInitialContextFactory&gt;
		&lt;soapjms:jndiURL&gt;tcp://localhost:61616
		&lt;/soapjms:jndiURL&gt;
		&lt;soapjms:deliveryMode&gt;PERSISTENT&lt;/soapjms:deliveryMode&gt;
		&lt;soapjms:priority&gt;5&lt;/soapjms:priority&gt;
		&lt;soapjms:timeToLive&gt;1000&lt;/soapjms:timeToLive&gt;
		&lt;wsdl:operation name="greetMe"&gt;
			&lt;soap:operation soapAction="test" style="document" /&gt;
			&lt;wsdl:input name="greetMeRequest"&gt;
				&lt;soap:body use="literal" /&gt;
			&lt;/wsdl:input&gt;
			&lt;wsdl:output name="greetMeResponse"&gt;
				&lt;soap:body use="literal" /&gt;
			&lt;/wsdl:output&gt;
		&lt;/wsdl:operation&gt;
	&lt;/wsdl:binding&gt;
        &lt;wsdl:service name="JMSGreeterService"&gt;
		&lt;soapjms:jndiConnectionFactoryName&gt;ConnectionFactory
		&lt;/soapjms:jndiConnectionFactoryName&gt;
		&lt;soapjms:jndiInitialContextFactory&gt;
			org.apache.activemq.jndi.ActiveMQInitialContextFactory
		&lt;/soapjms:jndiInitialContextFactory&gt;
		&lt;wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort"&gt;
			&lt;soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" /&gt;
		&lt;/wsdl:port&gt;
	&lt;/wsdl:service&gt;
&lt;/wsdl:definitions&gt;
</pre>
</div></div>

<ul>
	<li>The transport URI (<a href="http://www.w3.org/2010/soapjms/" class="external-link"
rel="nofollow">http://www.w3.org/2010/soapjms/</a>) is defined in the &lt;soap:binding&gt;.</li>
	<li>The jms: URI is defined in the &lt;soap:address&gt;</li>
	<li>The extension properties are in the &lt;soap:binding&gt;</li>
</ul>


<h2><a name="SOAPoverJMS1.0support-PublishinganservicewiththeJAVAAPI"></a>Publishing
an service with the JAVA API</h2>
<p>Developers who don't wish to modify the WSDL file can also publish the endpoint information
using Java code.  For CXF's SOAP over JMS implementation you can write the following:</p>

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

<p>NOTE: Before you start the server, you need to make sure the JMS broker is stared,
 you can find some useful code of starting the JMS broker here.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="theme: Default; brush: java; gutter: false"><![CDATA[
public final void run() {
    try {             
        broker = new BrokerService();
        broker.setPersistenceAdapter(new MemoryPersistenceAdapter());
        broker.setTmpDataDirectory(new File("./target"));
        broker.setUseJmx(false);
        if (brokerName != null) {
            broker.setBrokerName(brokerName);
        }
        broker.addConnector(brokerUrl1 + "?daemon=true");
        broker.start();  
    } catch (Exception e) {
        e.printStackTrace();
    }
}
]]></script>
</div></div>

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

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

<p>Even if you want to use the 'queue' or 'topic' variants and avoid dealing with JNDI
directly, you still have to specify the two factory parameters in the address:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
svrFactory.setAddress("jms:queue:test.cxf.jmstransport.queue?timeToLive=1000"
                              + "&amp;jndiConnectionFactoryName=ConnectionFactory"
                              + "&amp;jndiInitialContextFactory"
                              + "=org.apache.activemq.jndi.ActiveMQInitialContextFactory");
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=CXF20DOC">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/SOAP+over+JMS+1.0+support">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2853910&revisedVersion=13&originalVersion=12">View
Changes</a>
                |
        <a href="https://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