Page edited by Daniel Kulp

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.

SOAP over JMS specification 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 and is compliant with this specification.

"New Feature!"

The SOAP over JMS specification feature described here is a new feature under development for CXF 2.3. It is not available in a release yet. Help testing this with the 2.3-SNAPSHOTS would be greatly appreciated.

What's new compared to the old CXF JMS Transport

SOAP over JMS transport supports most configurations of JMS Transport and provides some extensions to support the SOAP over JMS specification. SOAP over JMS Transport uses the JMS URI (jms:address, for example) to describe JMS addressing information and provides new WSDL extensions for JMS configuration.

SOAP over JMS Namespace

WSDL Namespace

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.

JMS Extension Namespace

xmlns:soapjms="http://www.w3.org/2008/07/soap/bindings/JMS/"


JMS URI

JMS endpoints need to know the address information for establishing connections to the proper destination. SOAP over JMS implements the URI Scheme for Java Message Service 1.0. 

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.

CXF supports three variants, "jndi", "queue", and "topic".

For example:

jms:jndi:SomeJndiNameForDestination?jndiInitialContextFactory=com.example.jndi.JndiFactory&priority=3
jms:queue:ExampleQueueName?timeToLive=1000



Properties are as follows:


Property
DefaultValue
Description


deliveryMode
 PERSISTENT 
 NON_PERSISTENT  messages will kept only in memory 

PERSISTENT messages will be saved to disk 


jndiConnectionFactoryName
 
Specifies the JNDI name bound to the JMS connection factory to use when connecting to the JMS destination.


jndiInitialContextFactory
 
Specifies the fully qualified Java class name of the "InitialContextFactory" implementation class to use.


jndiURL
 
Specifies the JNDI provider URL


replyToName
 
 Specifies the JNDI name bound to the JMS destinations where replies are sent. 


priority
 4 
Priority for the messages. See your JMS provider documentation for details


timeToLive
 0 
Time (in ms) after which the message will be discarded by the jms provider


Additional JNDI Parameters
 
Additional parameters for a JNDI provider.  A custom parameter name must start with the prefix "jndi-".



For more details about these attributes, please check out the JMS URI specification.

WSDL Extension

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. 

For example, if the jndiInitialContextFactory is indicated for a service, it will be used for all of the port elements it contains.


Field
DefaultValue
Description


deliveryMode
 PERSISTENT 
NON_PERSISTENT messages will only be kept in memory 

PERSISTENT messages will be saved to disk 


jndiConnectionFactoryName
 
Specifies the JNDI name bound to the JMS connection factory to use when connecting to the JMS destination.


jndiInitialContextFactory
 
Specifies the fully qualified Java class name of the "InitialContextFactory" implementation class to use.


jndiURL
 
Specifies the JNDI provider URL


replyToName
 
Specifies the JNDI name bound to the JMS destinations where replies are sent. 


priority
 4 
Priority for the messages. See your JMS provider doc for details


timeToLive
 0 
Time (in ms) after which the message will be discarded by the jms provider


jndiContextParameter
 
 Additional parameters for a JNDI provider.



Here is an example:

<wsdl11:binding name="exampleBinding">
  <soapjms:jndiContextParameter name="name" value="value" />
<soapjms:jndiConnectionFactoryName>ConnectionFactory
</soapjms:jndiConnectionFactoryName>
<soapjms:jndiInitialContextFactory>
org.apache.activemq.jndi.ActiveMQInitialContextFactory
</soapjms:jndiInitialContextFactory>
<soapjms:jndiURL>tcp://localhost:61616
</soapjms:jndiURL>
<soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>
<soapjms:priority>5</soapjms:priority>
  <soapjms:timeToLive>200</soapjms:timeToLive>
</wsdl11:binding>

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



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.

WSDL Usage
For this example:

<wsdl:definitions name="JMSGreeterService"
	<wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType">
		<soap:binding style="document"
			transport="http://www.w3.org/2008/07/soap/bindings/JMS/" />
		<soapjms:jndiContextParameter name="name"
			value="value" />
		<soapjms:jndiConnectionFactoryName>ConnectionFactory
		</soapjms:jndiConnectionFactoryName>
		<soapjms:jndiInitialContextFactory>
			org.apache.activemq.jndi.ActiveMQInitialContextFactory
		</soapjms:jndiInitialContextFactory>
		<soapjms:jndiURL>tcp://localhost:61616
		</soapjms:jndiURL>
		<soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>
		<soapjms:priority>5</soapjms:priority>
		<soapjms:timeToLive>1000</soapjms:timeToLive>
		<wsdl:operation name="greetMe">
			<soap:operation soapAction="test" style="document" />
			<wsdl:input name="greetMeRequest">
				<soap:body use="literal" />
			</wsdl:input>
			<wsdl:output name="greetMeResponse">
				<soap:body use="literal" />
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>
	<wsdl:service name="JMSGreeterService">
		<wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort">
			<soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>




	The transport URI (http://www.w3.org/2008/07/soap/bindings/JMS/) is defined in the <soap:binding>.
	The jms: URI is defined in the <soap:address>
	The extension properties are in the <soap:binding>



Publishing an service with the JAVA API
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:


        // 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"
            + "&jndiConnectionFactoryName=ConnectionFactory&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_SPECIFICIATION_TRANSPORTID);
        svrFactory.setServiceBean(implementor);
        svrFactory.create();



Consume the service with the API

Sample code to consume a SOAP-over-JMS service is as follows:

      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"
            + "&jndiConnectionFactoryName=ConnectionFactory&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);
    }



Differences between the SOAP over JMS and the CXF old JMS transport implementation
There are some differences between the SOAP over JMS and the previous CXF over JMS transport implementation.

	The JMS Messages sent by SOAP over JMS transport implementation are in accordance with the SOAP over JMS specification, allowing CXF to interoperate with other SOAP over JMS implementations.
	Additional techniques are provided for configuring SOAP over JMS.
	The new implementation provides more sophisticated error handling for the SOAP over JMS messages.

Change Notification Preferences

View Online | View Change | Add Comment

[CONF] Apache CXF Documentation > SOAP over JMS 1.0 support

SOAP over JMS 1.0 support

Page edited by Daniel Kulp

What's new compared to the old CXF JMS Transport

SOAP over JMS Namespace

WSDL Namespace

JMS Extension Namespace

JMS URI

WSDL Extension

WSDL Usage

Publishing an service with the JAVA API

Consume the service with the API

Differences between the SOAP over JMS and the CXF old JMS transport implementation

Reply via email to