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
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
PlatformTransactionManagerinterface 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
TransactionManagerinterface 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
falsefor 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 tofalseand initialize thetransactionManagerproperty with a reference to an XA transaction manager.This property gets its name from thesessionTransactedproperty in the underlying Spring transaction layer. Thetransactedproperty ultimately gets injected into thesessionTransactedproperty 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
PlatformTransactionManagerinterface 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 toCACHE_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
truewould direct the Spring transaction layer to create its own local transaction manager instance, whenever it is needed.)
