Implementing Transaction Support 

Use

The J2EE Connector Architecture defines three levels of transaction support for the resource adapters:

·        NoTransaction

·        LocalTransaction

·        XATransaction

The transaction support level is defined by the implemented interface – either javax.transaction.xa.XAResource or javax.resource.spi.LocalTransaction, or both. Additionally, the adapter may implement javax.resource.cci.LocalTransaction to enable the application components to demarcate local transactions.

You must declare the transaction support at deployment time; otherwise, the container will not be able to handle its transaction support properly. For more information, see Resource Adapter Transaction Support.

Choosing the proper transaction support for your resource adapter is critical for its usage, especially in a managed environment. For example, a resource adapter with XATransaction support provides connections that can be used in distributed transactions. Also, if a connection from your resource adapter will be used with a connection from another one in a single transaction, at least one of the adapters must have a transaction support level, which is different from LocalTransaction, because it is not possible to use more than one local resources in a transaction.

Procedure

LocalTransaction Interfaces

To enable LocalTransaction support for the resource adapter, you must implement the javax.resource.spi.LocalTransaction interface. It is a system-level interface, which enables the application server to manage the local transactions for the resource adapter. Such adapter provides support for transactions that are managed locally by the resource manager of the EIS. You cannot work with multiple resource managers in a single transaction; you can do this with distributed transactions. For resource adapters with LocalTransaction support, the J2EE Engine provides local transaction optimization.

For example, the Connector Container uses local transaction optimization when access to a single resource manager is required. Also, if the application uses a resource adapter with local transaction support and another one with XA transaction support, the container first gets a connection from the adapter with local transaction support, and then applies local transaction optimization for the other resource adapter.

If you want to enable the application components that use the adapter to demarcate local transactions, you must implement the javax.resource.cci.LocalTransaction interface. It provides begin(), commit() and rollback() methods, which the application component may invoke to start and complete a local transaction. For component-defined local transactions, the resource adapter is required to send events to the container using the javax.resource.spi.ConnectionEventListener interface. One exception to this requirement is the case when the adapter implements an API, which supports implicit begin of local transactions, such as JDBC (the java.sql.Connection interface does not provide a begin() method, which explicitly starts a transaction). The adapter does not have to send events for container-driven local transactions as well.

XATransaction Support

A resource adapter with XATransaction support implements both the javax.resource.spi.LocalTransaction and the javax.transaction.xa.XAResource interface. The XAResource interface enables the applications to use connections obtained from this resource adapter in JTA transactions, which are managed by the Transaction Service in the J2EE Engine. The resources coming from the adapter also support thetwo-phase commit protocol.

Additional Considerations

·        If the resource adapter implements the javax.resource.cci.LocalTransaction interface, the getLocalTransaction() method of the javax.resource.cci.Connection implementation must return a LocalTransaction instance. The application components will be able to start a local transaction by obtaining the LocalTransaction instance and calling its begin() method. To complete the transaction, they must use LocalTransaction.commit() or LocalTransaction.rollback().

The addConnectionEventListener() method of the ManagedConnection registers ConnectionEventListeners, which enable the application server to receive events about component-driven local transactions. The listeners are unregistered by the removeConnectionEventListener() method.

·        The methods getXAResource() and getLocalTransaction() from the javax.resource.spi.ManagedConnection interface are related to the transaction support level of the resource adapter. The getXAResource() method returns the XAResource for the connection. It is registered with Transaction Service, which uses it to associate the resource with the relevant global transaction, and to communicate with the underlying resource managers. If the resource manager is with NoTransaction or LocalTransaction support, the getXAResource() method must throw an exception. The getLocalTransaction() method returns a LocalTransaction object, which is used by the application server for local transaction demarcation. If the adapter does not support transactions at all, this method must throw an exception.