Product SiteDocumentation Site

Chapter 3. The Resource Manager

3.1. The XAResource interface
3.1.1. Extended XAResource control
3.2. Opening a resource manager
3.3. Closing a resource manager
3.4. Thread of control
3.5. Transaction association
3.6. Externally controlled connections
3.7. Resource sharing
3.8. Local and global transactions
3.9. Transaction timeouts
3.10. Dynamic registration

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. Interface javax.transaction.xa.XAResource is a Java mapping of the XA interface. The XAResource interface defines the contract between a ResourceManager and a TransactionManager in a distributed transaction processing environment. A resource adapter for a ResourceManager implements the XAResource interface to support association of a top-level transaction to a resource such as a relational database.
The XAResource interface can be supported by any transactional resource adapter designed to be used in an environment where transactions are controlled by an external transaction manager, such a database management system. An application may access data through multiple database connections. Each database connection is associated with an XAResource object that serves as a proxy object to the underlying ResourceManager instance. The transaction manager obtains an XAResource for each ResourceManager participating in a top-level transaction. The start method associates the transaction with the resource, and the end method disassociates the transaction from the resource.
The ResourceManager associates the transaction with all work performed on its data between invocation of start and end methods. At transaction commit time, these transactional ResourceManagers are informed by the transaction manager to prepare, commit, or roll back the transaction according to the two-phase commit protocol.
For better Java integration, the XAResource differs from the standard XA interface in the following ways:
  • The resource adapter implicitly initializes the ResourceManager when the resource (the connection) is acquired. There is no equivalent to the xa_open method of the interface XA.
  • Rmid is not passed as an argument. Each Rmid is represented by a separate XAResource object.
  • 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 transaction manager’s improper handling of the XAResource object are mapped to Java exceptions via the XAException class.
  • The DTP concept of Thread of Control maps to all Java threads that are given access to the XAResource and Connection objects. For example, it is legal for two different threads to perform the start and end operations on the same XAResource object.

3.1.1. Extended XAResource control

By default, whenever an XAResource object is registered with a JTA-compliant transaction service, there is no way to manipulate the order in which it is invoked during the two-phase commit protocol, with respect to other XAResource objects. JBoss Transactions, however, provides support for controlling the order via 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 is invoked first or last, respectively.

Note

Only one instance of each interface type may be registered with a specific transaction.
The ArjunaCore Development Guide discusses the Last Resource Commit optimization (LRCO), whereby a single resource that is only one-phase aware, and does not support the prepare phase, can be enlisted with a transaction that is manipulating two-phase aware participants. This optimization is also supported within the JBoss Transactions.
In order to use the LRCO, your XAResource implementation must extend the com.arjuna.ats.jta.resources.LastResourceCommitOptimisation marker interface. A marker interface is an interface which provides no methods. When enlisting the resource via method Transaction.enlistResource, JBoss Transactions ensures that only a single instance of this type of participant is used within each transaction. Your resource is driven last in the commit protocol, and no invocation of method prepare occurs.
By default an attempt to enlist more than one instance of a LastResourceCommitOptimisation class will fail and false will be returned from Transaction.enlistResource. This behavior can be overridden by setting the com.arjuna.ats.jta.allowMultipleLastResources to true. However, before doing so you should read the section on enlisting multiple one-phase aware resources.

Important

You need to disable interposition support to use the LCRO in a distributed environment. You can still use implicit context propagation.

3.1.1.1. Enlisting multiple one-phase-aware resources

One-phase commit is used to process a single one-phase aware resource, which does not conform to the two-phase commit protocol. You can still achieve an atomic outcome across resources, by using the LRCO, as explained earlier.
Multiple one-phase-aware resources may be enlisted in the same transaction. One example is when a legacy database runs within the same transaction as a legacy JMS implementation. In such a situation, you cannot achieve atomicity of transaction outcome across multiple resources, because none of them enter the prepare state. They commit or roll back immediately when instructed by the transaction coordinator, without knowledge of other resource states and without a way to undo if subsequent resources make a different choice. This can result in data corruption or heuristic outcomes.
You can approach these situations in two different ways:
  • Wrap the resources in compensating transactions. See the XTS Transactions Development Guide for details.
  • Migrate the legacy implementations to two-phase aware equivalents.
If neither of these options is viable, JBoss Transactions support enlisting multiple one-phase aware resources within the same transaction, using LRCO, which is discussed in the ArjunaCore Development Guide in detail.

Warning

Even when this support is enabled, JBoss Transactions issues a warning when it detects that the option has been enabled: You have chosen to enable multiple last resources in the transaction manager. This is transactionally unsafe and should not be relied upon. Another warning is issued when multiple one-phase aware resources are enlisted within a transaction: This is transactionally unsafe and should not be relied on.
To override the above-mentioned warning at runtime, set the CoreEnvironmentBean.disableMultipleLastResourcesWarning property to true. You will see a warning that you have done this when JBoss Transactions starts up and see the warning about enlisting multiple one-phase resources only the first time it happens, but after that no further warnings will be output. You should obviously only consider changing the default value of this property (false) with caution.