Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 26. Using JMS

Abstract

HTTP is the underlying transport for the Web. It provides a standardized, robust, and flexible platform for communicating between endpoints. Because of these factors it is the assumed transport for most WS-* specifications and is integral to RESTful architectures.
Important
The Java Business Integration components of Red Hat JBoss Fuse are considered deprecated. You should consider migrating any JBI applications to OSGi.

26.1. Using SOAP/JMS
Copy link

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.

26.1.1. Basic configuration
Copy link

Overview
Copy link

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
Copy link

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 26.1, “SOAP over JMS binding specification” shows a WSDL binding that uses SOAP/JMS.

Example 26.1. SOAP over JMS binding specification

<wsdl:binding ... >
  <soap:binding style="document"
                transport="http://www.w3.org/2010/soapjms/" />
  ...
</wsdl:binding>
Copy to Clipboard Toggle word wrap

Specifying the target destination
Copy link

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 26.2, “JMS URI syntax” shows the syntax for a JMS URI.

Example 26.2. JMS URI syntax

jms:variant:destination?options
Copy to Clipboard Toggle word wrap
Table 26.1, “JMS URI variants” describes the available variants for the JMS URI.
Expand
Table 26.1. JMS URI variants
VariantDescription
jndiSpecifies that the destination is a JNDI name for the target destination. When using this variant, you must provide the configuration for accessing the JNDI provider.
topicSpecifies that the destination is the name of the topic to be used as the target destination. The string provided is passed into Session.createTopic() to create a representation of the destination.
queueSpecifies that the destination is the name of the queue to be used as the target destination. The string provided is passed into Session.createQueue() 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 26.1.2, “JMS URIs”.
Example 26.3, “SOAP/JMS endpoint address” shows the WSDL port entry for a SOAP/JMS endpoint whose target destination is looked up using JNDI.

Example 26.3. SOAP/JMS endpoint address

<wsdl:port ... >
  ...
  <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
</wsdl:port>
Copy to Clipboard Toggle word wrap
For working with SOAP/JMS services in Java see ???.

Configuring JNDI and the JMS transport
Copy link

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

26.1.2. JMS URIs
Copy link

Overview
Copy link

When using SOAP/JMS, a JMS URI is used to specify the endpoint's target destination. The JMS URI can also be used to configure JMS connection by appending one or more options to the URI. These options are detailed in the IETF standard, URI Scheme for Java Message Service 1.0. They can be used to configure the JNDI system, the reply destination, the delivery mode to use, and other JMS properties.

Syntax
Copy link

As shown in Example 26.2, “JMS URI syntax”, you can append one or more options to the end of a JMS URI by separating them from the destination's address with a question mark(?). Multiple options are separated by an ampersand(&). Example 26.4, “Syntax for JMS URI options” shows the syntax for using multiple options in a JMS URI.

Example 26.4. Syntax for JMS URI options

jmsAddress?option1=value1&option2=value2&...optionN=valueN
Copy to Clipboard Toggle word wrap

JMS properties
Copy link

Table 26.2, “JMS properties settable as URI options” shows the URI options that affect the JMS transport layer.
Expand
Table 26.2. JMS properties settable as URI options
PropertyDefaultDescription
deliveryModePERSISTENTSpecifies whether to use JMS PERSISTENT or NON_PERSISTENT message semantics. In the case of PERSISTENT delivery mode, the JMS broker stores messages in persistent storage before acknowledging them; whereas NON_PERSISTENT messages are kept in memory only.
replyToName 
Explicitly specifies the reply destination to appear in the JMSReplyTo header. Setting this property is recommended for applications that have request-reply semantics because the JMS provider will assign a temporary reply queue if one is not explicitly set.
The value of this property has an interpretation that depends on the variant specified in the JMS URI:
  • jndi variant—the JNDI name of the destination
  • queue or topic variants—the actual name of the destination
priority4Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest).
timeToLive0Time (in milliseconds) after which the message will be discarded by the JMS provider. A value of 0 represents an infinite lifetime (the default).

JNDI properties
Copy link

Table 26.3, “JNDI properties settable as URI options” shows the URI options that can be used to configure JNDI for this endpoint.
Expand
Table 26.3. JNDI properties settable as URI options
PropertyDescription
jndiConnectionFactoryNameSpecifies the JNDI name of the JMS connection factory.
jndiInitialContextFactorySpecifies the fully qualified Java class name of the JNDI provider (which must be of javax.jms.InitialContextFactory type). Equivalent to setting the java.naming.factory.initial Java system property.
jndiURLSpecifies the URL that initializes the JNDI provider. Equivalent to setting the java.naming.provider.url Java system property.

Additional JNDI properties
Copy link

The properties, java.naming.factory.initial and java.naming.provider.url, are standard properties, which are required to initialize any JNDI provider. Sometimes, however, a JNDI provider might support custom properties in addition to the standard ones. In this case, you can set an arbitrary JNDI property by setting a URI option of the form jndi-PropertyName.
For example, if you were using SUN's LDAP implementation of JNDI, you could set the JNDI property, java.naming.factory.control, in a JMS URI as shown in Example 26.5, “Setting a JNDI property in a JMS URI”.

Example 26.5. Setting a JNDI property in a JMS URI

jms:queue:FOO.BAR?jndi-java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
Copy to Clipboard Toggle word wrap

Example
Copy link

If the JMS provider is not already configured, it is possible to provide the requisite JNDI configuration details in the URI using options (see Table 26.3, “JNDI properties settable as URI options”). For example, to configure an endpoint to use the Apache ActiveMQ JMS provider and connect to the queue called test.cxf.jmstransport.queue, use the URI shown in Example 26.6, “JMS URI that configures a JNDI connection”.

Example 26.6. JMS URI that configures a JNDI connection

jms:jndi:dynamicQueues/test.cxf.jmstransport.queue
?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory
&jndiConnectionFactoryName=ConnectionFactory
&jndiURL=tcp://localhost:61616
Copy to Clipboard Toggle word wrap

26.1.3. WSDL extensions
Copy link

Overview
Copy link

You can specify the basic configuration of the JMS transport by inserting WSDL extension elements into the contract, either at binding scope, service scope, or port scope. The WSDL extensions enable you to specify the properties for bootstrapping a JNDI InitialContext, which can then be used to look up JMS destinations. You can also set some properties that affect the behavior of the JMS transport layer.

SOAP/JMS namespace
Copy link

the SOAP/JMS WSDL extensions are defined in the http://www.w3.org/2010/soapjms/ namespace. To use them in your WSDL contracts add the following setting to the wsdl:definitions element: 
<wsdl:definitions ...
    xmlns:soapjms="http://www.w3.org/2010/soapjms/"
  ... >
Copy to Clipboard Toggle word wrap

WSDL extension elements
Copy link

Table 26.4, “SOAP/JMS WSDL extension elements” shows all of the WSDL extension elements you can use to configure the JMS transport.
Expand
Table 26.4. SOAP/JMS WSDL extension elements
ElementDefaultDescription
soapjms:jndiInitialContextFactory Specifies the fully qualified Java class name of the JNDI provider. Equivalent to setting the java.naming.factory.initial Java system property.
soapjms:jndiURL Specifies the URL that initializes the JNDI provider. Equivalent to setting the java.naming.provider.url Java system property.
soapjms:jndiContextParameter Enables you to specify an additional property for creating the JNDI InitialContext. Use the name and value attributes to specify the property.
soapjms:jndiConnectionFactoryName Specifies the JNDI name of the JMS connection factory.
soapjms:deliveryModePERSISTENTSpecifies whether to use JMS PERSISTENT or NON_PERSISTENT message semantics. In the case of PERSISTENT delivery mode, the JMS broker stores messages in persistent storage before acknowledging them; whereas NON_PERSISTENT messages are kept in memory only.
soapjms:replyToName 
Explicitly specifies the reply destination to appear in the JMSReplyTo header. Setting this property is recommended for SOAP invocations that have request-reply semantics. If this property is not set the JMS provider allocates a temporary queue with an automatically generated name.
The value of this property has an interpretation that depends on the variant specified in the JMS URI, as follows:
  • jndi variant—the JNDI name of the destination.
  • queue or topic variants—the actual name of the destination.
soapjms:priority4Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest).
soapjms:timeToLive0Time, in milliseconds, after which the message will be discarded by the JMS provider. A value of 0 represents an infinite lifetime.

Configuration scopes
Copy link

The WSDL elements placement in the WSDL contract effect the scope of the configuration changes on the endpoints defined in the contract. The SOAP/JMS WSDL elements can be placed as children of either the wsdl:binding element, the wsdl:service element, or the wsdl:port element. The parent of the SOAP/JMS elements determine which of the following scopes the configuration is placed into.
Binding scope
You can configure the JMS transport at the binding scope by placing extension elements inside the wsdl:binding element. Elements in this scope define the default configuration for all endpoints that use this binding. Any settings in the binding scope can be overridden at the service scope or the port scope.
Service scope
You can configure the JMS transport at the service scope by placing extension elements inside a wsdl:service element. Elements in this scope define the default configuration for all endpoints in this service. Any settings in the service scope can be overridden at the port scope.
Port scope
You can configure the JMS transport at the port scope by placing extension elements inside a wsdl:port element. Elements in the port scope define the configuration for this port. They override any defaults defined at the service scope or at the binding scope.

Example
Copy link

Example 26.7, “WSDL contract with SOAP/JMS configuration” shows a WSDL contract for a SOAP/JMS service. It configures the JNDI layer in the binding scope, the message delivery details in the service scope, and the reply destination in the port scope.

Example 26.7. WSDL contract with SOAP/JMS configuration

<wsd;definitions ...
1    xmlns:soapjms="http://www.w3.org/2010/soapjms/"
  ... >
  ...
  <wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType">
    ...
2    <soapjms:jndiInitialContextFactory>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </soapjms:jndiInitialContextFactory>
    <soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL>
    <soapjms:jndiConnectionFactoryName>
      ConnectionFactory
    </soapjms:jndiConnectionFactoryName>
    ...
  </wsdl:binding>
  ...
  <wsdl:service name="JMSGreeterService">
    ...
3    <soapjms:deliveryMode>NON_PERSISTENT</soapjms:deliveryMode>
    <soapjms:timeToLive>60000</soapjms:timeToLive>
    ...
    <wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort">
4      <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
5      <soapjms:replyToName>
        dynamicQueues/greeterReply.queue
      </soapjms:replyToName>
      ...
    </wsdl:port>
    ...
  </wsdl:service>
  ...
</wsdl:definitions>
Copy to Clipboard Toggle word wrap
The WSDL in Example 26.7, “WSDL contract with SOAP/JMS configuration” does the following:
1
Declare the namespace for the SOAP/JMS extensions.
2
Configure the JNDI connections in the binding scope.
3
Configure the JMS delivery style to non-persistent and each message to live for one minute.
4
Specify the target destination.
5
Configure the JMS transport so that reply messages are delivered on the greeterReply.queue queue.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat