Chapter 3. The Resource Manager
3.1. The XAResource Interface
Some transaction specifications and systems define a generic resource which can be used to register arbitrary resources with a transaction. The JTA is much more XA specific. The
javax.transaction.xa.XAResource interface is a Java mapping of the XA interface, and defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing environment. A resource adapter implements the XAResource interface to support association of a top-level transaction to a resource. A relational database is an example of such a resource.
The
XAResource interface can be supported by any transactional resource adapter that is intended to be used in an environment where transactions are controlled by an external transaction manager. An application can access data through multiple database connections. Each database connection is associated with an XAResource object that serves as a proxy object to the underlying resource manager instance. The transaction manager obtains an XAResource for each resource manager participating in a top-level transaction. The start and end methods associates and dissociate the transaction from the resource.
The resource manager associates the transaction with all work performed on its data between the
start and end invocations. At transaction commit time, these transactional resource managers are instructed by the transaction manager to prepare, commit, or rollback the transaction according to the two-phase commit protocol.
In order to be better integrated with Java, the
XAResource differs from the standard XA interface in the following ways:
- The resource manager initialization is done implicitly by the resource adapter when the connection is acquired. There is no
xa_openequivalent. Rmidis not passed as an argument. EachRmidis represented by a separateXAResourceobject.- Asynchronous operations are not supported because Java supports multi-threaded processing and most databases do not support asynchronous operations.
- Error return values caused by the improper handling of the
XAResourceobject by the transaction manager are mapped to Java exceptions by theXAExceptionclass. - The DTP concept of Thread of Control maps to all Java threads with access to the
XAResourceandConnectionobjects. For example, two different threads are able to perform thestartandendoperations on the sameXAResourceobject.
3.1.1. Extended XAResource Control
By default, whenever an
XAResource object is registered with a JTA-compliant transaction service, you have no control over the order in which it will be invoked during the two-phase commit protocol, with respect to other XAResource objects. However, JBoss Transaction Service supports controlling the order with the two interfaces com.arjuna.ats.jta.resources.StartXAResource and com.arjuna.ats.jta.resources.EndXAResource. By inheriting your XAResource instance from either of these interfaces, you control whether an instance of your class will be invoked at the beginning or end of the commit protocol.
Note
Only one instance of each interface type may be registered with a specific transaction.
Last Resource Commit optimization (LRCO) allows a single resource that is only one-phase aware (does not support
prepare) to be enlisted with a transaction which manipulates two-phase aware participants. JBossJTA provides LRCO support.
In order to use the LRCO feature, your
XAResource implementation must extend the com.arjuna.ats.jta.resources.LastResourceCommitOptimisation marker interface. When enlisting the resource via Transaction.enlistResource, JBoss Transaction Service allows only a single LastResourceCommitOptimisation participant to be used within each transaction. Your resource is driven last in the commit protocol, and the prepare method is not invoked.
Note
By default, an attempt to enlist more than one instance of a
LastResourceCommitOptimisation class will fail and false is returned from Transaction.enlistResource. You can override this behavior by setting the com.arjuna.ats.jta.allowMultipleLastResources property to true. Be sure to read the section on enlisting multiple one-phase aware resources fore more information.
To use the LRCO in a distributed environment, you must disable interposition support. You are still able to use implicit context propagation.
3.1.2. Enlisting Multiple One-Phase Aware Resources
In order to guarantee consistency (atomicity) of outcome between multiple participants (resources) within the same transaction, the two-phase commit protocol is used with a durable transaction log. When possessing a single one-phase aware resource, you can still achieve an atomic (all or nothing) outcome across resources by utilizing LRCO, as explained earlier.
However, you may have enlisted multiple one-phase aware resources within the same transaction. For example, a legacy database running within the same transaction as a legacy JMS implementation. In these situations, you cannot achieve atomicity of transaction outcome across multiple resources, because none of them enter the
prepare state. They commit or rollback immediately when instructed by the transaction coordinator, without knowledge of other resource states and without any way of undoing their actions if subsequent resources make a different choice. This can cause data corruption or heuristic outcomes.
In these situations, use either of the following approaches:
- Wrap the resources in compensating transactions.
- Migrate the legacy implementations to two-phase aware equivalents.
If neither of these options are viable, JBoss Transaction Service supports the enlistment of multiple one-phase aware resources within the same transaction, using LRCO. LRCO is covered earlier in this chapter.
Important
Even when LRCO support is enabled, JBoss Transaction Service issues warnings when it detects this support. The log message is
"You have chosen to enable multiple last resources in the transaction manager. This is transactionally unsafe and should not be relied upon.” or, when multiple one-phase resources are enlisted within the transaction, “This is transactionally unsafe and should not be relied on.”.
