14.2. 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.
Important
In CXF 3.0, the JMS transport no longer has a dependency on Spring JMS, so some Spring JMS-related options have been removed.
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  [Required] Specifies a reference to a bean that defines a JMS ConnectionFactory.
wrapInSingleConnectionFactory true [pre v3.0]
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies whether to wrap the ConnectionFactory with a Spring SingleConnectionFactory.
Enable this property when using a ConnectionFactory that does not pool connections, as it will improve the performance of the JMS transport. This is so because the JMS transport creates a new connection for each message, and the SingleConnectionFactory is needed to cache the connection, so it can be reused.
reconnectOnException false
[Deprecated in CXF 3.0] CXF always reconnects when an exception occurs.
[pre CXF 3.0] Specifies whether to create a new connection when an exception occurs.
When wrapping the ConnectionFactory with a Spring SingleConnectionFactory:
  • true—on an exception, create a new connection
    Do not enable this option when using a PooledConnectionFactory, as this option only returns the pooled connection, but does not reconnect.
  • false—on an exception, do not try to reconnect
targetDestination  Specifies the JNDI name or provider-specific name of a destination.
replyDestination  Specifies the JMS name of the JMS destination where replies are sent. This property allows the use of a user-defined destination for replies. For more details see Section 14.6, “Using a Named Reply Destination”.
destinationResolver DynamicDestinationResolver
Specifies a reference to a Spring DestinationResolver.
This property allows you to define how destination names are resolved to JMS destinations. Valid values are:
  • DynamicDestinationResolver—resolve destination names using the features of the JMS provider.
  • JndiDestinationResolver—resolve destination names using JNDI.
transactionManager  Specifies a reference to a Spring transaction manager. This enables the service to participate in JTA transactions.
taskExecutor SimpleAsyncTaskExecutor
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies a reference to a Spring TaskExecutor. This is used in listeners to decide how to handle incoming messages.
useJms11 false
[Removed in CXF 3.0] CXF 3.0 supports JMS 1.1 features only.
[pre CXF 3.0] Specifies whether JMS 1.1 features are used. Valid values are:
  • true—JMS 1.1 features
  • false—JMS 1.0.2 features
messageIdEnabled true
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies whether the JMS transport wants the JMS broker to provide message IDs. Valid values are:
  • true—broker needs to provide message IDs
  • false—broker need not provide message IDs
    In this case, the endpoint calls its message producer's setDisableMessageID() method with a value of true. The broker is then given a hint that it need not generate message IDs or add them to the endpoint's messages. The broker either accepts the hint or ignores it.
messageTimestampEnabled true
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies whether the JMS transport wants the JMS broker to provide message time stamps. Valid values are:
  • true—broker needs to provide message timestamps
  • false—broker need not provide message timestamps
    In this case, the endpoint calls its message producer's setDisableMessageTimestamp() method with a value of true. The broker is then given a hint that it need not generate time stamps or add them to the endpoint's messages. The broker either accepts the hint or ignores it.
cacheLevel -1 (feature disabled)
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies the level of caching that the JMS listener container may apply. Valid values are:
  • 0—CACHE_NONE
  • 1—CACHE_CONNECTION
  • 2—CACHE_SESSION
  • 3—CACHE_CONSUMER
  • 4—CACHE_AUTO
pubSubNoLocal
false
Specifies whether to receive your own messages when using topics.
  • true—do not receive your own messages
  • false—receive your own messages
receiveTimeout
60000
Specifies the time, in milliseconds, to wait for response messages.
explicitQosEnabled false Specifies whether the QoS settings (such as priority, persistence, time to live) are explicitly set for each message (true) or use the default values (false).
deliveryMode 2
Specifies whether a message is persistent. Valid values are:
  • 1 (NON_PERSISTENT)—messages are kept memory only
  • 2 (PERSISTENT)—messages are persisted to disk
priority 4 Specifies message priority. JMS priority values range from 0 (lowest) to 9 (highest). See your JMS provider's documentation for details.
timeToLive 0 (indefinitely)Specifies the time, in milliseconds, before a message that has been sent is discarded.
sessionTransacted false Specifies whether JMS transactions are used.
concurrentConsumers 1
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies the minimum number of concurrent consumers for the listener.
maxConcurrentConsumers 1
[Removed in CXF 3.0]
[pre CXF 3.0] Specifies the maximum number of concurrent consumers for the listener.
messageSelector  Specifies the string value of the selector used to filter incoming messages. This property enables multiple connections to share a queue. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification.
subscriptionDurable false Specifies whether the server uses durable subscriptions.
durableSubscriptionName  Specifies the name (string) used to register the durable subscription.
messageType text
Specifies how the message data will be packaged as a JMS message. Valid values are:
  • text—specifies that the data will be packaged as a TextMessage
  • byte—specifies that the data will be packaged as an array of bytes (byte[])
  • binary—specifies that the data will be packaged as an ByteMessage
pubSubDomain false
Specifies whether the target destination is a topic or a queue. Valid values are:
  • true—topic
  • false—queue
jmsProviderTibcoEms false
Specifies whether the JMS provider is Tibco EMS.
When set to true, the principal in the security context is populated from the JMS_TIBCO_SENDER header.
useMessageIDAsCorrelationID false
[Removed in CXF 3.0]
Specifies whether JMS will use the message ID to correlate messages.
When set to true, the client sets a generated correlation ID.
maxSuspendedContinuations -1 (feature disabled)
[CXF 3.0] Specifies the maximum number of suspended continuations the JMS destination may have. When the current number exceeds the specified maximum, the JMSListenerContainer is stopped.
reconnectPercentOfMax 70
[CXF 3.0] Specifies when to restart the JMSListenerContainer stopped for exceeding maxSuspendedContinuations.
The listener container is restarted when its current number of suspended continuations falls below the value of (maxSuspendedContinuations * reconnectPercentOfMax/100).
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="jmsConnectionFactory"
      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

<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 xmlns="http://www.springframework.org/schema/beans" 
          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

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