Distributed Transactions

Overview

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.

Note:
Distributed transaction (XA) features require version Oracle8i release 8.1.6 or later of the Oracle database with JServer option.

Distributed Transaction Components and Scenarios

In reading the remainder of the distributed transactions section, it will be helpful to keep the following points in mind:

A distributed transaction system typically relies on an external transaction manager--such as a software component that implements standard Java Transaction API (JTA) functionality--to coordinate the individual transactions.

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.
XA functionality is usually isolated from a client application, being implemented instead in a middle-tier environment such as an application server.

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.
Discussion throughout this section is intended mostly for middle-tier developers.

The term resource manager is often used in discussing distributed transactions. A resource manager is simply an entity that manages data or some other kind of resource. Wherever the term is used in this chapter, it refers to a database.

Note:
Using JTA functionality requires file jta.zip to be in the CLASSPATH. Oracle includes this file with the JDBC product. (You can also obtain it from the Sun Microsystems Web site, but it is advisable to use the version from Oracle, because that has been tested with the Oracle drivers.)

Distributed Transaction Concepts

Software that uses distributed transactions cannot use normal connection instance COMMIT, auto-commit, or ROLLBACK functionality, because all COMMIT or ROLLBACK operations in a distributed transaction must be coordinated. Any attempt to use the commit() or 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:

XA data sources--These are extensions of connection pool data sources and other data sources, and similar in concept and functionality.

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.
XA connections--These are extensions of pooled connections, and similar in concept and functionality. An XA connection encapsulates a physical database connection; individual connection instances are temporary handles to these physical 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.
XA resources--These are used by a transaction manager in coordinating the transaction branches of a distributed transaction.

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.
Transaction IDs--These are used to identify transaction branches. Each ID includes a transaction branch ID component and a distributed transaction ID component--this is how a branch is associated with a distributed transaction. All XA resource instances associated with a given distributed transaction would have a transaction ID that includes the same distributed transaction ID component.

Oracle XA Packages

Oracle supplies the following three packages that have classes to implement distributed transaction functionality according to the XA standard:

oracle.jdbc.xa (OracleXid and OracleXAException classes)
oracle.jdbc.xa.client
oracle.jdbc.xa.server

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 OracleXid and 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 OracleXid, OracleXAException, and the oracle.jdbc.xa.client package.

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 client package.

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.