Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 7. JMS XA Transaction Integration

Abstract

Apache ActiveMQ provides full support for XA transactions, where the broker can either be embedded in the application or deployed remotely. XA connections can be obtained through the standard javax.jms.XAConnectionFactory interface and Apache ActiveMQ also provides a wrapper class, which supports auto-enlistment of the JMS XA resource and connection pooling. In particular, this chapter describes in detail how to configure a Camel JMS component to use XA transactions in the context of an OSGi container.

7.1. Enabling XA on the Camel JMS Component

Overview

Figure 7.1, “Camel JMS Component Integrated with XA Transactions” shows an overview of how to configure the Camel JMS component to use XA transactions in the Red Hat JBoss Fuse OSGi container. In this scenario, the Camel JMS component is integrated with the built-in Aries transaction manager and a connection factory wrapper is included, to support auto-enlisting of XA resources.

Figure 7.1. Camel JMS Component Integrated with XA Transactions

Camel JMS Component Integrated with XA Transactions

Accessing the XA transaction manager

The XA transaction manager, which is embedded in the OSGi container, must be accessed through two different interfaces:
org.springframework.transaction.PlatformTransactionManager
The PlatformTransactionManager interface is needed by the Camel JMS component (which is layered over the Spring transaction API). For more details, see PlatformTransactionManager Interface.
javax.transaction.TransactionManager
The TransactionManager interface is needed by the XA pooled connection factory, which uses it to enlist the ActiveMQ XA resource.
The transaction manager interfaces are accessed as OSGi services. For example, to access the interfaces through Blueprint XML, you can use the following code: 
<beans ...>

    <!--
        OSGi TM Service
    -->
    <!-- access through Spring's PlatformTransactionManager -->
    <reference id="osgiPlatformTransactionManager"
               interface="org.springframework.transaction.PlatformTransactionManager"/>
    <!-- access through JTA TransactionManager -->
    <reference id="osgiJtaTransactionManager"
               interface="javax.transaction.TransactionManager"/>

</beans>
For more details, see Accessing the Transaction Manager.

XA connection factory bean

The basic connection factory bean for Apache ActiveMQ is an instance of the class, ActiveMQXAConnectionFactory, which exposes the javax.jms.XAConnectionFactory interface. Through the JTA XAConnectionFactory interface, it is possible to obtain a reference to an XAResource object, but the basic connection factory bean does not have the capability to auto-enlist the XA resource.

XA pooled connection factory bean

The XA pooled connection factory bean, which can be an instance of JcaPooledConnectionFactory type or XaPooledConnectionFactory type, is a connection factory wrapper class that adds the following capabilities to the basic connection factory:
  • JMS connection pooling—enables the re-use of JMS connection instances. When a transaction is completed, the corresponding JMS connection can be returned to a pool and then re-used by another transaction.
  • Auto-enlistment of XA resources—the pooled connection factory bean also has the ability to enlist an XA resource automatically, each time a transaction is started.
The JcaPooledConnectionFactory bean exposes the standard javax.jms.ConnectionFactory interface (but not the XAConnectionFactory interface).

Camel JMS component and JMS configuration bean

The JMS configuration bean encapsulates all of the required settings for the Camel JMS component. In particular, the JMS configuration bean includes a reference to the transaction manager (of PlatformTransactionManager type) and a reference to the XA pooled connection factory (of JcaPooledConnectionFactory type).
The org.apache.camel.component.jms.JmsConfiguration class supports the following bean properties, which are particularly relevant to transactions:
transacted
Must be set to false for XA transactions. The name of this property is misleading. What it really indicates is whether or not the Camel JMS component supports local transactions. For XA transactions, on the other hand, you must set this property to false and initialize the transactionManager property with a reference to an XA transaction manager.
This property gets its name from the sessionTransacted property in the underlying Spring transaction layer. The transacted property ultimately gets injected into the sessionTransacted property in the Spring transaction layer, so it is the Spring transaction layer that determines the semantics. For more details, see the Javadoc for Spring's AbstractMessageListenerContainer.
transactionManager
Must be initialized with a reference to the PlatformTransactionManager interface of the built-in OSGi transaction manager.
transactionName
Sets the transaction name. Default is JmsConsumer[destinationName].
cacheLevelName
Try setting this initially to CACHE_CONNECTION, because this will give you the best performance. If this setting turns out to be incompatible with your transaction system, you can revert to CACHE_NONE, whcih switches off all caching in the Spring transaction layer. For more details, see the Spring documentation.
transactionTimeout
Do not set this property in the context of XA transactions. To customize the transaction timeout in the context of XA transactions, you need to configure the timeout directly in the OSGi transaction manager instead (see Configuring the Transaction Manager for details).
lazyCreateTransactionManager
Do not set this boolean property in the context of XA transactions. (In the context of a local transaction, setting this property to true would direct the Spring transaction layer to create its own local transaction manager instance, whenever it is needed.)