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:
- Specify that the transport type is SOAP/JMS.
- Specify the target destination using a JMS URI.
- Optionally, configure the JNDI connection.
- 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.
| Variant | Description |
|---|---|
| jndi | Specifies that the destination name is a JNDI queue name. When using this variant, you must provide the configuration for accessing the JNDI provider. |
| jndi-topic | Specifies that the destination name is a JNDI topic name. When using this variant, you must provide the configuration for accessing the JNDI provider. |
| queue | Specifies 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. |
| topic | Specifies 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:
