JTA Global Transactions with GemFire

Use JTA global transactions to coordinate GemFire cache transactions and JDBC transactions.

JTA is a standard Java interface you can use to coordinate GemFire cache transactions and JDBC transactions globally under one umbrella. JTA provides direct coordination between the GemFire cache and another transactional resource, such as a database. The parties involved in a JTA transaction include:
  • The Java application, responsible for starting the global transaction
  • The JTA transaction manager, responsible for opening, committing, and rolling back transactions
  • The transaction resource managers, including the GemFire cache transaction manager and the JDBC resource manager, responsible for managing operations in the cache and database respectively

Using JTA, your application controls all transactions in the same standard way, whether the transactions act on the GemFire cache, a JDBC resource, or both together. When a JTA global transaction is done, the GemFire transaction and the database transaction are both complete.

When using JTA global transactions with GemFire, you have two options:
  1. Coordinate with an external JTA transaction manager in a container (such as WebLogic or JBoss)
  2. Have GemFire act as the JTA transaction manager

An application creates a global transaction by using javax.transaction.UserTransaction bound to the JNDI context java:/UserTransaction to start and terminate transactions. During the transaction, cache operations are done through GemFire as usual as described in GemFire Cache Transactions.

Note: See the Sun documentation for more information on topics such as JTA, javax.transaction, committing and rolling back global transactions, and the related exceptions.

Coordinating with External JTA Transactions Managers

GemFire can work with the JTA transaction managers of several containers like JBoss, WebLogic, GlassFish, and so on.

At startup GemFire looks for a TransactionManager (javax.transaction.TransactionManager) that has been bound to its JNDI context. When GemFire finds such an external transaction manager, all GemFire region operations (such as get and put) will participate in global transactions hosted by this external JTA transaction manager.

This figure shows the high-level operation of a JTA global transaction whose resources include a GemFire cache and a database.

An externally coordinated JTA global transaction is run in the following manner:
  1. Each region operation looks up for presence of a global transaction. If one is detected, then a GemFire transaction is started automatically, and we register a javax.transaction.Synchronization callback with the external JTA transaction manager.
  2. At transaction commit, GemFire gets a beforeCommit() callback from the external JTA transaction manager. GemFire does all locking and conflict detection at this time. If this fails, an exception is thrown back to JTA transaction manager, which then aborts the transaction.
  3. After a successful beforeCommit() callback, JTA transaction manager asks other data sources to commit their transaction.
  4. GemFire then gets a afterCommit() callback in which changes are applied to the cache and distributed to other members.

You can disable JTA in any region that should not participate in JTA transactions. See Turning Off JTA Transactions.

How to Run a JTA Transaction Coordinated by an External Transaction Manager

Use the following procedure to run a GemFire global JTA transaction coordinated by an external JTA transaction manager.

  1. Configure the external data sources in the external container. Do not configure the data sources in cache.xml . They are not guaranteed to get bound to the JNDI tree.
  2. Configure GemFire for any necessary transactional behavior in cache.xml. For example, enable copy-on-read and specify a transaction listener, if you need one. See Setting Global Copy on Read and Configuring Transaction Plug-In Event Handlers for details.
  3. Make sure that JTA transactions are not disabled for the regions that will participate in the transaction. See Turning Off JTA Transactions for details.
  4. Start the transaction through the external container.
  5. Initialize the GemFire cache. GemFire will automatically join the transaction.
  6. Execute operations in the cache and the database as usual.
  7. Commit the transaction through the external container.

Using GemFire as the JTA Transaction Manager

You can also use GemFire as the JTA transaction manager.

GemFire ships with its own implementation of a JTA transaction manager. However, note that this implementation is not XA-compliant; therefore, it does not persist any state, which could lead to an inconsistent state after recovering a crashed member.

The GemFire JTA transaction manager is initialized when the GemFire cache is initialized. Until then, JTA is not available for use. The application starts a JTA transaction by using the UserTransaction.begin method. The UserTransaction object is the application’s handle to instruct the JTA transaction manager on what to do.

The GemFire JTA implementation also supports the J2EE Connector Architecture (JCA) ManagedConnectionFactory.

The GemFire Enterprise implementation of JTA has the following limitations:
  • Only one JDBC database instance per transaction is allowed, although you can have multiple connections to that database.
  • Multiple threads cannot participate in a transaction.
  • Transaction recovery after a crash is not supported.
In addition, JTA transactions are subject to the limitations of GemFire cache transactions such as not being supported on regions with global scope. When a global transaction needs to access the GemFire cache, JTA silently starts a GemFire cache transaction.

How to Run a JTA Global Transaction Using GemFire as the JTA Transaction Manager

This topic describes how to run a JTA global transaction in GemFire.

To run a global transaction, perform the following steps:

  1. Configure the external data sources in cache.xml. See Configuring Database Connections Using JNDI for examples.
  2. Include the JAR file for any data sources in your CLASSPATH.
  3. Configure GemFire for any necessary transactional behavior. Enable copy-on-read for your cache and specify a transaction listener, if you need one. See Setting Global Copy on Read and Configuring Transaction Plug-In Event Handlers for details.
  4. Make sure that JTA transactions are not disabled in the cache.xml file or the application code.
  5. Initialize the GemFire cache.
  6. Get an initial context through com.gemstone.gemfire.cache.Cache.getJNDIContext. For example:
    Context ctx = cache.getJNDIContext();

    This returns javax.naming.Context and gives you the JNDI associated with the cache. The context contains the TransactionManager, UserTransaction, and any configured JDBC resource manager.

  7. Look up the UserTransaction context:
    UserTransaction txManager = (UserTransaction)ctx.lookup("java:/UserTransaction");
    With UserTransaction, you can begin, commit, and rollback transactions.

    If a global transaction exists, when you use the cache, it automatically joins the transaction. Operations on a region automatically detect and become associated with the existing global transaction through JTA synchronization. If the global transaction has been marked for rollback, however, the GemFire cache is not allowed to enlist with that transaction. Any cache operation that causes an attempt to enlist throws a FailedSynchronizationException.

    The GemFire cache transaction’s commit or rollback is triggered when the global transaction commits or rolls back. When the global transaction is committed using the UserTransaction interface, the transactions of any registered JTA resources are committed, including the GemFire cache transaction. If the cache or database transaction fails to commit, UserTransaction throws a TransactionRolledBackException. If a commit or rollback is attempted directly on a GemFire transaction that is registered with JTA, that action throws an IllegalStateException.