weblogic.jdbc.wrapper (Java API Reference for Oracle WebLogic Server)

Provides classes that implements the generic JDBC 2.0 resource adapter, which wraps any JDBC 2.0 compliant XA drivers.

Package weblogic.jdbc20.xapool Description

JDBC 2.0 core API assumes a 2-tier data access model, where applications access physical connections provided by the database driver directly. JDBC 2.0 Optional (formerly known as Standard Extension) API adds provisions for a 3-tier data access model, where applications access logical connections via middle-tier server. This allows the middle-tier server to optionally implement more sophisticated features like connection pooling and distributed transactions.

WLS JDBC 2.0 resource adapter encapsulates the middle-tier logic between the application and the driver to implement connection pooling, and also the middle-tier logic between the transaction manager and the driver to implement distributed transactions.

In the WLS environment, the WLS JDBC 2.0 resource adapter serves the following purposes:

1. Acts as a bridge between application and JDBC 2.0 resource:

It provides implementation of javax.sql.DataSource interface on top of JDBC 2.0 XA driver's javax.sql.XADataSource interface.

2. Manages usage of JDBC 2.0 resources:

It implements connection pooling for JDBC 2.0 XA driver's XA connections, and manages the usage of XA connections efficiently.

3. Acts as a bridge between WLS transaction manager and JDBC 2.0 resource:

As part of the distributed transactions protocol, it performs and optimizes enlistment and delistment of the JDBC 2.0 XA driver's XA resources with the WLS transaction manager.
It provides resource descriptors to transaction manager which encapsulates various resource OA&M information:

JTA does not specify any formal mechanism for boostrapping XAResource during failure recovery. Resource descriptors provide XAResource given the resource name.
It also provides the reverse mapping of a XA resource object to its corresponding configured resource name. This is needed by the transaction manager to use the resource names of the enlisted XA resources as the transaction branch qualifier for the XAResource.start operation. It is also needed by the transaction object's propagation logic to be included in the participant resource list in the transaction propagation context.
It provides the list of sub-coordinators that have access to a particular XA resource to transaction manager's root coordinator for it to determine the sub-coordinators to be used for completing a particular XA resource's transaction branch and for recovering the XA resource on startup.

4. Acts as a bridge between WLS OA&M subsystem and JDBC 2.0 resource:

It communicates bidirectionally with the WLS OA&M subsystem about resource properties and any changes. It initializes the JDBC 2.0 XA driver's data source and makes it available to be used by doing the following:

Creates the JDBC 2.0 XA driver's XA data source.
Initializes the JDBC 2.0 XA driver's XA data source by setting data source properties via introspection.
Registers a DataSource object with JNDI on behalf of the JDBC XA driver's data source.

Logical connections, statements, result sets, and XA resources

Being a bridge between application and JDBC 2.0 XA drivers, the JDBC 2.0 resource adapter provides logical data sources, connections, statements, result sets on top of the physical ones provided by the drivers. These logical JDBC objects implements the standard java.sql and javax.sql interfaces.

Similarly, being a bridge between the transaction manager and JDBC 2.0 XA drivers, the JDBC 2.0 resource adapter provides logical XA resources on top of the physical XA resource provided by the drivers. This logical XA resource object is only used internally by the WLS transaction manager, and implements the standard javax.transaction.xa.XAResource interface and a WLS extension tbd interface.

The resource adapter's logical XA resource differs from the physical ones provided by the drivers as follow:

The resource adapter always has one logical XA resource object per data source, so that all the XA resource enlistments of the same data source to the transaction manager uses the same logical XA resource object, irrespective of the XA connection that is being used for the data access. This allows the WLS transaction manager to use pointer comparison to efficiently determine whether two XA resource objects are from the same data source. And it also allows the transaction manager to hold on to a single XA resource object for all of its operations performed to the same data source, instead of acquiring a XA resource every time it is needed and freeing it afterwards.
Some drivers' (e.g. Oracle) implementation has one XA resource object per XA connection object, and the corresponding XA resource object should be used for enlistment for data access work performed with a particular XA connection object. In this case, users have to use the XAResource.isSameRM() method to determine whether two XA resource objects are from the same data source.

Having logical JDBC and XA resource objects allows the JDBC 2.0 resource adapter to intercept various JDBC and XA resource calls and performs various optimizations in addition to providing basic connection pooling and distributed transactions functionality. See Database connection management and Optimizations sections below.

Database connection management

Each XA connection corresponds to a physical database connection. To ensure the most efficient use of XA connections, the resource adapter pools the XA connections and manages the XA connections as follow:

1. For JDBC operations (called by the application onto the resource adapter's logical connections) that do not require a XA connection, the resource adapter just returns the required logical JDBC objects (e.g. statements) without obtaining a XA connection from the pool.

2. For JDBC operations (called by the application onto the resource adapter's logical JDBC objects) that require XA connection but do not require a transaction context, the resource adapter obtains a XA connection on demand and return the XA connection back to pool after usage.

3. For JDBC operations (called by the application onto the resource adapter's logical JDBC objects) that require a transaction context, the resource adapter obtains a XA connection on demand.

If there is a (global) transaction context, the resource adapter also enlists its logical XA resource to the transaction manager. Multiple requests for XA connection in the same transaction will use the same XA connection. The XA connection is returned back to the pool when the transaction manager calls XAResource.end(TMSUCCESS or TMFAIL) on the resource adapter's logical XA resource object. This happens either when making outcall or when method returns with no result sets in the transaction, or when the transaction is committed or rolled back.

If there is no transaction context, no resource enlistment is done. For some RM, e.g. Oracle, the RM will start a local transaction implicitly. In this case, the XA connection is returned back to the pool when the application completes the local transaction via calling Connection.commit() or Connection.rollback() on the resource adapter's logical connection object. XA resource operations will not be called for local transactions.

4. For XA resource operations other than start/end that is being called by the transaction manager onto the resource adapter's logical XA resource object, the resource adapter obtains a XA connection and returns the connection back to pool every time.

Enlistment and delistment (for global transaction)

As part of the distributed transactions protocol, the resource adapter is responsible for enlisting and delisting XA resources with and from the transaction manager by calling Transaction.enlistResource and Transaction.delistResource respectively. The transaction object in turns performs the transaction association and disassociation with and from the XA resources by calling XAResource.start and XAResource.end respectively. This is done so that data access performed with the associating XA connections will be done in the same transaction context.

The resource adapter and the transaction manager handles resource enlistment and delistment as follow:

1. The resource adapter enlists its logical XA resource object with the transaction manager blindly before any JDBC operations (called by the application onto the logical JDBC objects) that need a transaction context. The transaction manager will ignore duplicate enlists and will call XAResource.start on the resource adapter's logical XA resource object with the appropriate flag if needed. The resource adapter's logical XA resource will delegate the XAResource.start call to the driver's XAResource.start directly.

2. The resource adapter does not perform any Transaction.delistResource. It always rely on the transaction manager to ask it for the proper delist flag when it is ready to call XAResource.end on the resource adapter's logical XA resource object (when making outcalls or returning from method). The resource adapter's logical XA resource will delegate the XAResource.end call to the driver's XAResource.end directly. In addition, the logical XA resource object will return the XA connection back to the pool if the delist flag is TMSUCCESS or if there is no result sets opened in the transaction.

Role in Recovery

The transaction manager is responsible for driving recovery and resolving in-doubt transactions of the XA resources that are caused by server crashes. XA resource only needs to provide an implementation of recover method in this case.

However, resources can also crash or become unreachable due to network partition etc. For these cases, when the resource comes back up or becomes reachable again, the only recoverable action that needs to be done is to refresh the connections of the resources. The resource adapter will attempt to reconnect implicitly when XAER_RMERR results from XA operations. An administrative command should also be available to force the refresh of connections. After the connection refresh, the normal 2PC protocol of the transaction manager will take over to drive the pending transactions to completion as normal.

What is supported

The resource adapter supports the following scenarios:

1. Getting connection before transaction begin.

2. Completing transaction before connection is closed.

3. Getting and closing connections in a nested manner.

4. Leave result sets open across outcall.

5. Leave result sets open across method invocations.

6. Usage of both local and global transactions with same connection.

7. Setting auto commit to true when connection is used in local transaction. However, auto commit will be reset to default (false) when local transaction is completed.

8. Interleave different global transactions with the same connection.

Optimizations

The resource adapter performs the following optimizations:

1. Obtaining XA connections lazily on demand. (for both local and global transaction)

2. Different logical connections share the same XA connection if they are in the same transaction. (for global transaction)

3. Returning XA connections back to pool as early as possible:

Before making outcall, if XA connection has no opened result sets. (for global transaction)
On method return, if XA connection has no opened result sets. (for global transaction)
When transaction is completed. (for both local and global transaction)

4. Delay XAResource.end until making outcalls or method end. This avoid unnecessary XAResource.start later in the same method call when additional data access work is done in the same transaction. (for global transaction)

Assumptions

The JDBC 2.0 resource adapter assumes that the JDBC/XA driver supports JDBC 2.0 standard extension spec interfaces and semantics and does not assume any thread affinity restrictions of the JDBC/XA driver. For RMs that has specific thread affinity restrictions, it is up to individual JDBC/XA driver to bridge that gap.

Limitations

The resource adapter and the transaction manager do not support the following:

Doing database work in the same transaction in different threads (or processes) simultaneously is not supported. Attempting to do so may have unpredicted behavior. However, it is normal to do database work in the same transaction in different threads (or processes) one at a time.

Package weblogic.jdbc.wrapper