Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 14. Using Generic JMS

Abstract

Apache CXF provides a generic implementation of a JMS transport. The generic JMS transport is not restricted to using SOAP messages and allows for connecting to any application that uses JMS.
The Apache CXF generic JMS transport can connect to any JMS provider and work with applications that exchange JMS messages with bodies of either TextMessage or ByteMessage.
There are two ways to enable and configure the JMS transport:

14.1. Using the JMS configuration bean

Overview

To simplify JMS configuration and make it more powerful, Apache CXF uses a single JMS configuration bean to configure JMS endpoints. The bean is implemented by the org.apache.cxf.transport.jms.JMSConfiguration class. It can be used to either configure endpoint's directly or to configure the JMS conduits and destinations.

Configuration namespace

The JMS configuration bean uses the Spring p-namespace to make the configuration as simple as possible. To use this namespace you need to declare it in the configuration's root element as shown in Example 14.1, “Declaring the Spring p-namespace”.

Example 14.1. Declaring the Spring p-namespace

<beans ...
  xmlns:p="http://www.springframework.org/schema/p"
  ... >
  ...
</beans>

Specifying the configuration

You specify the JMS configuration by defining a bean of class org.apache.cxf.transport.jms.JMSConfiguration. The properties of the bean provide the configuration settings for the transport.
Table 14.1, “General JMS Configuration Properties” lists properties that are common to both providers and consumers.

Table 14.1. General JMS Configuration Properties

PropertyDefaultDescription
connectionFactory-ref Specifies a reference to a bean that defines a JMS ConnectionFactory.
wrapInSingleConnectionFactorytrueSpecifies whether to wrap the ConnectionFactory with a Spring SingleConnectionFactory. Doing so can improve the performance of the JMS transport when the specified connection factory does not pool connections.
reconnectOnExceptionfalseSpecifies whether to create a new connection in the case of an exception. This property is only used when wrapping the connection factory with a Spring SingleConnectionFactory.
targetDestination Specifies the JNDI name or provider specific name of a destination.
replyDestination Specifies the JMS name of the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Section 14.3, “Using a Named Reply Destination”.
destinationResolver Specifies a reference to a Spring DestinationResolver. This allows you to define how destination names are resolved. By default a DynamicDestinationResolver is used. It resolves destinations using the JMS providers features. If you reference a JndiDestinationResolver you can resolve the destination names using JNDI.
transactionManager Specifies a reference to a Spring transaction manager. This allows the service to participate in JTA Transactions.
taskExecutor Specifies a reference to a Spring TaskExecutor. This is used in listeners to decide how to handle incoming messages. By default the transport uses the Spring SimpleAsyncTaskExecutor.
useJms11falseSpecifies whether JMS 1.1 features are available.
messageIdEnabledtrueSpecifies whether the JMS transport wants the JMS broker to provide message IDs. Setting this to false causes the endpoint to call its message producer's setDisableMessageID() method with a value of true. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
messageTimestampEnabledtrueSpecifies whether the JMS transport wants the JMS broker to provide message time stamps. Setting this to false causes the endpoint to call its message producer's setDisableMessageTimestamp() method with a value of true. The JMS broker is then given a hint that it does not need to generate time stamps or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
cacheLevel3Specifies the level of caching allowed by the listener. Valid values are 0(CACHE_NONE), 1(CACHE_CONNECTION), 2(CACHE_SESSION), 3(CACHE_CONSUMER), 4(CACHE_AUTO).
pubSubNoLocalfalseSpecifies whether to receive messages produced from the same connection.
receiveTimeout0Specifies, in milliseconds, the amount of time to wait for response messages. 0 means wait indefinitely.
explicitQosEnabledfalseSpecifies whether the QoS settings like priority, persistence, and time to live are explicitly set for each message or if they are allowed to use default values.
deliveryMode1
Specifies if a message is persistent. The two values are:
  • 1(NON_PERSISTENT)—messages will be kept memory
  • 2(PERSISTENT)—messages will be persisted to disk
priority4Specifies the message's priority for the messages. JMS priority values can range from 0 to 9. The lowest priority is 0 and the highest priority is 9.
timeToLive0Specifies, in milliseconds, the message will be available after it is sent. 0 specifies an infinite time to live.
sessionTransactedfalseSpecifies if JMS transactions are used.
concurrentConsumers1Specifies the minimum number of concurrent consumers created by the listener.
maxConcurrentConsumers1Specifies the maximum number of concurrent consumers by listener.
messageSelector Specifies the string value of the selector. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification.
subscriptionDurablefalseSpecifies whether the server uses durrable subscriptions.
durableSubscriptionName Specifies the string used to register the durable subscription.
messageTypetextSpecifies how the message data will be packaged as a JMS message. text specifies that the data will be packaged as a TextMessage. binary specifies that the data will be packaged as an ByteMessage.
pubSubDomainfalseSpecifies whether the target destination is a topic.
jmsProviderTibcoEmsfalseSpecifies if your JMS provider is Tibco EMS. This causes the principal in the security context to be populated from the JMS_TIBCO_SENDER header.
useMessageIDAsCorrelationIDfalseSpecifies whether JMS will use the message ID to correlate messages. If not, the client will set a generated correlation ID.
As shown in Example 14.2, “JMS configuration bean”, the bean's properties are specified as attributes to the bean element. They are all declared in the Spring p namespace.

Example 14.2. JMS configuration bean

<bean id="jmsConfig"
      class="org.apache.cxf.transport.jms.JMSConfiguration"
      p:connectionFactory-ref="connectionFactory"
      p:targetDestination="dynamicQueues/greeter.request.queue"
      p:pubSubDomain="false" />

Applying the configuration to an endpoint

The JMSConfiguration bean can be applied directly to both server and client endpoints using the Apache CXF features mechanism. To do so:
  1. Set the endpoint's address attribute to jms://.
  2. Add a jaxws:feature element to the endpoint's configuration.
  3. Add a bean of type org.apache.cxf.transport.jms.JMSConfigFeature to the feature.
  4. Set the bean element's p:jmsConfig-ref attribute to the ID of the JMSConfiguration bean.
Example 14.3, “Adding JMS configuration to a JAX-WS client” shows a JAX-WS client that uses the JMS configuration from Example 14.2, “JMS configuration bean”.

Example 14.3. Adding JMS configuration to a JAX-WS client

<jaxws:client id="CustomerService"
              xmlns:customer="http://customerservice.example.com/"
              serviceName="customer:CustomerServiceService"
              endpointName="customer:CustomerServiceEndpoint"
              address="jms://"
              serviceClass="com.example.customerservice.CustomerService">
  <jaxws:features>
    <bean class="org.apache.cxf.transport.jms.JMSConfigFeature"
          p:jmsConfig-ref="jmsConfig"/>
  </jaxws:features>
</jaxws:client>

Applying the configuration to the transport

The JMSConfiguration bean can be applied to JMS conduits and JMS destinations using the jms:jmsConfig-ref element. The jms:jmsConfig-ref element's value is the ID of the JMSConfiguration bean.
Example 14.4, “Adding JMS configuration to a JMS conduit” shows a JMS conduit that uses the JMS configuration from Example 14.2, “JMS configuration bean”.

Example 14.4. Adding JMS configuration to a JMS conduit

<jms:conduit name="{http://cxf.apache.org/jms_conf_test}HelloWorldQueueBinMsgPort.jms-conduit">
  ...
  <jms:jmsConfig-ref>jmsConf</jms:jmsConfig-ref>
</jms:conduit>