Chapter 13. Using SOAP Over JMS

Abstract

Apache CXF implements the W3C standard SOAP/JMS transport. This standard is intended to provide a more robust alternative to SOAP/HTTP services. Apache CXF applications using this transport should be able to interoperate with applications that also implement the SOAP/JMS standard. The transport is configured directly in an endpoint's WSDL.
NOTE: Support for the JMS 1.0.2 APIs has been removed in CXF 3.0. If you are using Red Hat JBoss Fuse 6.2 or higher (includes CXF 3.0), your JMS provider must support the JMS 1.1 APIs.

13.1. Basic configuration

Overview

The SOAP over JMS protocol is defined by the World Wide Web Consortium(W3C) as a way of providing a more reliable transport layer to the customary SOAP/HTTP protocol used by most services. The Apache CXF implementation is fully compliant with the specification and should be compatible with any framework that is also compliant.
This transport uses JNDI to find the JMS destinations. When an operation is invoked, the request is packaged as a SOAP message and sent in the body of a JMS message to the specified destination.
To use the SOAP/JMS transport:
  1. Specify that the transport type is SOAP/JMS.
  2. Specify the target destination using a JMS URI.
  3. Optionally, configure the JNDI connection.
  4. Optionally, add additional JMS configuration.

Specifying the JMS transport type

You configure a SOAP binding to use the JMS transport when specifying the WSDL binding. You set the soap:binding element's transport attribute to http://www.w3.org/2010/soapjms/. Example 13.1, “SOAP over JMS binding specification” shows a WSDL binding that uses SOAP/JMS.

Example 13.1. SOAP over JMS binding specification

<wsdl:binding ... >
  <soap:binding style="document"
                transport="http://www.w3.org/2010/soapjms/" />
  ...
</wsdl:binding>

Specifying the target destination

You specify the address of the JMS target destination when specifying the WSDL port for the endpoint. The address specification for a SOAP/JMS endpoint uses the same soap:address element and attribute as a SOAP/HTTP endpoint. The difference is the address specification. JMS endpoints use a JMS URI as defined in the URI Scheme for JMS 1.0. Example 13.2, “JMS URI syntax” shows the syntax for a JMS URI.

Example 13.2. JMS URI syntax

jms:variant:destination?options
Table 13.1, “JMS URI variants” describes the available variants for the JMS URI.

Table 13.1. JMS URI variants

VariantDescription
jndiSpecifies that the destination name is a JNDI queue name. When using this variant, you must provide the configuration for accessing the JNDI provider.
jndi-topicSpecifies that the destination name is a JNDI topic name. When using this variant, you must provide the configuration for accessing the JNDI provider.
queueSpecifies that the destination is a queue name resolved using JMS. The string provided is passed into Session.createQueue() to create a representation of the destination.
topicSpecifies that the destination is a topic name resolved using JMS. The string provided is passed into Session.createTopic() to create a representation of the destination.
The options portion of a JMS URI are used to configure the transport and are discussed in Section 13.2, “JMS URIs”.
Example 13.3, “SOAP/JMS endpoint address” shows the WSDL port entry for a SOAP/JMS endpoint whose target destination is looked up using JNDI.

Example 13.3. SOAP/JMS endpoint address

<wsdl:port ... >
  ...
  <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
</wsdl:port>

Configuring JNDI and the JMS transport

The SOAP/JMS provides several ways to configure the JNDI connection and the JMS transport: