|Oracle8i JDBC Developer's Guide and Reference
Release 3 (8.1.7)
Part Number A83724-01
A distributed transaction, sometimes referred to as a global transaction, is a set of two or more related transactions that must be managed in a coordinated way. The transactions that constitute a distributed transaction might be in the same database, but more typically are in different databases and often in different locations. Each individual transaction of a distributed transaction is referred to as a transaction branch.
For example, a distributed transaction might consist of money being transferred from an account in one bank to an account in another bank. You would not want either transaction committed without assurance that both will complete successfully.
In the JDBC 2.0 extension API, distributed transaction functionality is built on top of connection pooling functionality, described under "Connection Pooling". This distributed transaction functionality is also built upon the open XA standard for distributed transactions. (XA is part of the X/Open standard and is not specific to Java.)
The remainder of this overview covers the following topics:
For further introductory and general information about distributed transactions and XA, refer to the Sun Microsystems Specifications for the JDBC 2.0 Optional Package and the Java Transaction API.
In reading the remainder of the distributed transactions section, it will be helpful to keep the following points in mind:
Many vendors will offer XA-compliant JTA modules. This includes Oracle, which is developing a JTA module based on the Oracle implementation of XA discussed below.
In many scenarios, the application server and transaction manager will be together on the middle tier, possibly together with some of the application code as well.
Software that uses distributed transactions cannot use normal connection instance
COMMIT, auto-commit, or
ROLLBACK functionality, because all
ROLLBACK operations in a distributed transaction must be coordinated. Any attempt to use the
rollback() method or enable the auto-commit flag of a connection instance would result in a SQL exception.
When you use XA functionality, the transaction manager uses XA resource instances to prepare and coordinate each transaction branch and then to commit or roll back all transaction branches appropriately.
XA functionality includes the following key components:
There will be one XA data source instance for each resource manager (database) that will be used in the distributed transaction. You will typically create XA data source instances (using the class constructor) in your middle-tier software.
XA data sources produce XA connections.
An XA connection instance corresponds to a single database session, although the session can be used in sequence by multiple logical connection instances (one at a time), as with pooled connection instances.
You will typically get an XA connection instance from an XA data source instance (using a
get method) in your middle-tier software. You can get multiple XA connection instances from a single XA data source instance if the distributed transaction will involve multiple sessions (multiple physical connections) in the same database.
XA connections produce XA resource instances and JDBC connection instances.
You will get one XA resource instance from each XA connection instance (using a
get method), typically in your middle-tier software. There is a one-to-one correlation between XA resource instances and XA connection instances; equivalently, there is a one-to-one correlation between XA resource instances and database sessions (physical connections).
In a typical scenario, the middle-tier component will hand off XA resource instances to the transaction manager, for use in coordinating distributed transactions.
Because each XA resource instance corresponds to a single database session, there can be only a single active transaction branch associated with an XA resource instance at any given time. There can be additional suspended transaction branches, however--see "XA Resource Method Functionality and Input Parameters".
Each XA resource instance has the functionality to start, end, prepare, commit, or roll back the operations of the transaction branch running in the session with which the XA resource instance is associated.
The "prepare" step is the first step of a two-phase
COMMIT operation. The transaction manager will issue a
prepare to each XA resource instance. Once the transaction manager sees that the operations of each transaction branch have prepared successfully (essentially, that the databases can be accessed without error), it will issue a
COMMIT to each XA resource instance to commit all the changes.
Oracle supplies the following three packages that have classes to implement distributed transaction functionality according to the XA standard:
Classes for XA data sources, XA connections, and XA resources are in both the
client package and the
server package. (An abstract class for each is in the top-level package.) The
OracleXAException classes are in the top-level
oracle.jdbc.xa package, because their functionality does not depend on where the code is running.
In middle-tier scenarios, you will import
OracleXAException, and the
If you intend your XA code to run in the target Oracle database, however, you will import the
oracle.jdbc.xa.server package instead of the
If code that will run inside a target database must also access remote databases, then do not import either package--instead, you must fully qualify the names of any classes that you use from the
client package (to access a remote database) or from the
server package (to access the local database). Class names are duplicated between these packages.