Contains classes which allow XQConnection objects to participate in distributed transactions.

The XQJ 1.0 Specification supports local case transactions involving a single data source, but does not provide support for distributed transactions where a single transaction involves multiple connections to one or more underlying data sources. A global transaction across multiple data sources must either commit successfully across all data sources or in the event of one data source failing to commit, all data sources must be rolled back.

The XQJ2 Specification makes use of the Java Transaction API™ (JTA™) in order to enable XQConnection objects to participate in distributed transactions. The design of XA transaction management in the XQJ2 API has been influenced by XA transaction management that exists in the JDBC API.

Generally, an application programmer does not have to deal directly with classes in this package, rather an Application Server should make use of the classes found here.

Scope of distributed transactions

An XQConnection is considered to be particpating in a distributed transaction between the invocation of XAResource.start and XAResource.end methods. After the invocation of the XAResource.end method, the XQConnection will continue to operate in a local transaction mode and will behave like a regular XQConnection.

Effects on local transaction management

While connection objects are participating in distributed transactions, invoking any of following XQConnection methods will cause an XQException to be thrown:

If the XQConnection is later used for a local transaction, these operations are legal at that point.

If a XQConnection has auto-commit mode enabled at the time it joins a global transaction, the attribute will be ignored. The auto-commit behavior will resume when the XQConnection returns to local transaction mode.

Example: Using XA classes

The following example shows simple usage of the XA classes. Keep in mind that the details would be filled in with work using other data sources. This type of code usually appears within a transaction manager.

// Create an XA data source for making the XA connection.
XAXQDataSource xaDataSource = new AcmeXADataSource();

// Get an XAConnection and get the associated XAResource.
// This provides access to the resource manager.
XAConnection xaConnection = xaDataSource.getXAConnection();
XAResource xaResource = xaConnection.getXAResource();

// Generate a new Xid (this is up to the transaction manager).
Xid xid = ...;

// Start the transaction.
xaResource.start(xid, XAResource.TMNOFLAGS);

// ... Perform an "update" operation against the datasource ...

// End the transaction.
xaResource.end(xid, XAResource.TMSUCCESS);

// Prepare for a commit.
xaResource.prepare(xid);

// Commit the transaction.
xaResource.commit(xid, false);

// Close the XA connection when done. This implicitly
// closes the XA resource.
xaConnection.close();

Not all XQJ2 implementations are required to support XA functionality.