Fuse ESB Enterprise - EIP Transaction Guide - Enabling XA on the Camel JMS Component

Overview

Figure 10 shows an overview of how to configure the Camel JMS component to use XA transactions in the Fuse ESB Enterprise 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 10. 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 JCA 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 Spring XML, you can use the following code:

<beans ...>

    <!--
        OSGi TM Service
    -->
    <!-- access through Spring's PlatformTransactionManager -->
    <osgi:reference id="osgiPlatformTransactionManager"
                    interface="org.springframework.transaction.PlatformTransactionManager"/>
    <!-- access through JTA TransactionManager -->
    <osgi: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.

JCA pooled connection factory bean

The JCA pooled connection factory bean, which is an instance of JcaPooledConnectionFactory 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 JCA 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.)