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
Property	Default	Description
`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 For details, see Class DefaultMessageListenerContainer
`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:

Set the endpoint's address attribute to jms://.
Add a jaxws:feature element to the endpoint's configuration.
Add a bean of type org.apache.cxf.transport.jms.JMSConfigFeature to the feature.
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 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” 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>

Overview

Configuration namespace

Specifying the configuration

Applying the configuration to an endpoint

Applying the configuration to the transport

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links