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.
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
.
While connection objects are participating in distributed transactions,
invoking any of following XQConnection
methods will cause
an XQException
to be thrown:
setAutoCommit(true)
commit()
rollback()
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.
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.