Chapter 5. Using the Narayana transaction manager

The JTA UserTransaction interface is defined as follows:

public interface javax.transaction.UserTransaction {

    public void begin();

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public void setTransactionTimeout(int seconds);
}

The UserTransaction interface defines the following methods:

The JTA TransactionManager interface has the following definition:

interface javax.transaction.TransactionManager {

    // Same as UserTransaction methods

    public void begin();

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public void setTransactionTimeout(int seconds);

    // Extra TransactionManager methods

    public Transaction getTransaction();

    public Transaction suspend() ;

    public void resume(Transaction tobj);
}

The TransactionManager interface supports all of the methods found in the UserTransaction interface. You can use a TransactionManager object for transaction demarcation. In addition, a TransactionManager object supports these methods:

The JTA Transaction interface has the following definition:

interface javax.transaction.Transaction {

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public boolean enlistResource(XAResource xaRes);

    public boolean delistResource(XAResource xaRes, int flag);

    public void registerSynchronization(Synchronization sync);
}

The commit(), rollback(), setRollbackOnly(), and getStatus() methods have the same behavior as the corresponding methods from the UserTransaction interface. In fact, a UserTransaction object is a convenient wrapper that retrieves the current transaction and then invokes the corresponding methods on the Transaction object.

Additionally, the Transaction interface defines the following methods, which have no counterparts in the UserTransaction interface:

Enlisting an XA resource with a transaction involves invoking the enlistResource() method on the Transaction interface. For example, given a TransactionManager object and an XAResource object, you could enlist the XAResource object as follows:

// Java
import javax.transaction.Transaction;
import javax.transaction.TransactionManager;
import javax.transaction.xa.XAResource;
...
// Given:
// 'tm' of type TransactionManager
// 'xaResource' of type XAResource

// Start the transaction
tm.begin();

Transaction transaction = tm.getTransaction();
transaction.enlistResource(xaResource);

// Do some work...
...

// End the transaction
tm.commit();

The tricky aspect of enlisting resources is that the resource must be enlisted on each new transaction and the resource must be enlisted before you start to use the resource. If you enlist resources explicitly, you could end up with error-prone code that is littered with enlistResource() calls. Moreover, sometimes it can be difficult to call enlistResource() in the right place, for example, this is the case if you are using a framework that hides some of the transaction details.

Instead of explicitly enlisting XA resources, it is easier and safer to use features that support auto-enlistment of XA resources. For example, in the context of using JMS and JDBC resources, the standard technique is to use wrapper classes that support auto-enlistment.

The common pattern, both for JDBC and JMS access is:

In this way, application code still uses javax.sql.DataSource and javax.jms.ConnectionFactory, but internally when these are accessed, there is additional functionality, which usually concerns:

With auto-enlistment, application code does not have to change.

For more information about pooling and enlisting wrappers for JDBC data sources and JMS connection factories, see Chapter 6, Using JDBC data sources and Chapter 7, Using JMS connection factories.