Usage Scenarios of XA Transactions

As a Standalone Application

A standalone JMS application can use FioranoMQ's implementation of JMS XA API (JMS XA SPI) to participate in a distributed transaction. The JMS application should write the XA specific code to run a XA transaction.

Figure: A stand-alone application uses FioranoMQ XA Support

As shown in the diagram above, the JMS application should:

Use JMS XA interfaces (XAConnectionFactory, XAConnection, XASession) instead of non-XA interfaces (ConnectionFactory, Connection, Session).
Use the XAResource interface (XAResource.start() and XAResource.end() ) to demarcate transaction boundaries.
Explicitly commit/rollback the transaction (XAResource.commit() or XAResource.rollback()) as per the business logic.
Examine the changes that need to be made to the JMS Client application that participates in a distributed transaction.

Follow the steps describe below:

Lookup ConnectionFactories and create related JMS resources.

As the implementation stack for XA-related resources is distinct from non-XA resources, XA connectionFactories need to be created. The Admin API sections of this document explain the creation of ConnectionFactories.

CODE

XAQueueConnectionFactory m_xaQueueConnectionFactory = 
(XAQueueConnectionFactory) ic.lookup("primaryXAQCF");

The lookup call for these connectionFactories returns an instance of the XAConnectionFactory.

CODE

XAQueueConnection m_xaQueueConnection = 
m_xaQueueConnectionFactory.createXAQueueConnection();

Customize all the other JMS-specific resources to either send or receive data. Note the use of the createXAQueueConnection method. The above JMS API call results in the creation of a XAQueueConnection with the MQServer.

CODE

XAQueueSession m_xaQueueSession = m_xaQueueConnection.createXAQueueSession();

Create an instance of XAQueueSession. All distributed transactions are associated with a session context. Any operation performed on a session can potentially take part in a distributed transaction.

2. Using XA resources and creating XID.

The next critical step involves retrieving the XAResource that identify the session context. A uniqueID (XID) is associated with every XAResource to uniquely identify each instance of a distributed transaction. The XID is used to recover failed transactions as well.

CODE

XAResource m_xaResource = m_xaQueueSession.getXAResource();
String branchId = "BranchID11";
String globalId = "globalId1";
Xid m_xid = new FioranoXid(globalId,branchId.getBytes(),0);

3. Marking the Start and the end transactions.

Mark the beginning and end of transactions. All operations performed on the session between the start and end statements can be part of distributed transactions.

CODE

m_xaResource.start(m_xid,XAResource.TMNOFLAGS);
// Perform all operations on the associated Session
m_xaResource.end(m_xid,XAResource.TMSUCCESS);

4. Completing the transaction

CODE

int type0= m_xaResource.prepare(m_xid);
m_xaResource.commit(m_xid,false);

These APIs are typically used by the Transaction Co-ordinator that manages the transaction across XA Resources. The commit or rollback call completes the transaction. Where applications control distributed transactions, the APIs are used directly by the applications.

Users are strongly urged to use the JTA specification and read up literature on distributed transactions in order to understand the implementation and usage of the JTA APIs. This section only illustrates the use of JMS APIs for a client application that needs to use distributed transactions. Please view the distributed transaction samples, which are available with the installation package, for more details.

Normally, a stand-alone application takes part in a distributed transaction when a single server is involved in the transaction. Where more than one server (or different parties) are involved in the distributed transaction, the application must use a third-party external Transaction Manager to co-ordinate the transaction.