WebLogic Server XA Resource Provider Requirements

e-docs > WebLogic Server > Programming WebLogic JTA > WebLogic Server XA Resource Provider Requirements

Programming WebLogic JTA

WebLogic Server XA Resource Provider Requirements

BEA WebLogic Server supports the Java Transaction API (JTA) and includes a Transaction Manager that coordinates distributed transactions with any XA-compliant resource. This chapter describes the requirements for XA resources to be able to participate in distributed transactions in WebLogic Server.

For information on JTA, see the Java Transaction API (JTA) Specification version 1.0.1a, published by Sun Microsystems, Inc.

This chapter is targeted at third-party application integrators. It includes the following sections:

Overview

An XA resource provider must support the JTA XAResource interface with no thread affinity limitations to be able to participate in distributed transactions in WebLogic Server.

For non-JDBC resources, the resource provider also needs to do the following:

Register the XA resource with the WebLogic Server transaction manager on startup
Optionally enlist and delist the XA resource with the WebLogic Server transaction manager before and after resource usage
Optionally implement the weblogic.transaction.XAResource interface

Registering with the Transaction Manager

The JTA specification does not define how to bootstrap an XA resource into a server's transaction manager. WebLogic Server defines a registration API for this purpose.

XA resource providers must perform the following steps to register their XAResource implementation with the local transaction manager on startup:

Obtain the JTA transaction manager using JNDI or the TxHelper interface. The following code shows how to use the TxHelper interface to obtain the current transaction manager:

import javax.transaction.xa.XAResource;
import javax.transaction.TransactionManager;
import weblogic.transaction.TxHelper;

TransactionManager tm = TxHelper.getTransactionManager();

XAResource res = ... // Resource provider's implementation of XAResource

tm.registerStaticResource(name, res); // Static enlistment resource
tm.registerDynamicResource(name, res2); // Dynamic enlistment resource

The resource provider supplies its name and implementation using either the static or dynamic registration method. See XAResource Enlistment and Delistment for information on static and dynamic enlistment.
The resource name determines the transaction branch. If the resource supports different instances, each resource instance should use a different name. This name is also the resource name that is used in administration.
Note that it is important that resource providers register the XA resource with the transaction manager before enlisting the XA resource for any transactional work.

Unregister the XA resource with the JTA transaction manager
```
XAResource res =  // Resource provider's implementation of XAResource
```
```
tm.unregisterResource(name);
```
The resource provider associated with this name on the current server is unregistered. If there are any transactions outstanding for this resource, unregistering a resource might result in rolled back transactions or transaction branch abandonment.

XAResource Enlistment and Delistment

In the JTA architecture, the application server plays the role of transactional resource manager, including enlisting and delisting resources implicitly with the transaction manager when necessary.

WebLogic Server supports two modes of XA resources enlistment: static and dynamic.

Static Enlistment and Delistment

If the XA resources are registered using static enlistment, WebLogic Server plays the role of application server and performs enlistment and delistment implicitly for the XA resource provider.

In particular, WebLogic Server enlists resources on transaction begin and resume. Note that a transaction is implicitly resumed upon the start of method calls for bean-managed transaction beans that have transactions previously associated with the beans, and also when an outgoing call to another server returns.

Similarly, WebLogic Server delists resources on transaction suspend, commit and rollback. Note that a transaction is implicitly suspended when making calls to another server, and also when method calls return to the client. The delist flag used is either obtained from the getDelistFlag() method if the resource provider supports it, or is TMSUSPEND if the resource provider does not support the getDelistFlag() method. Please refer to Optional weblogic.transaction.XAResource Interface for more details about the getDelistFlag() method.

Dynamic Enlistment and Delistment

XA resource providers can also perform enlistment and delistment themselves by registering as using dynamic enlistment. In this case, the XA resource provider itself plays the role of JTA application server partially in performing enlistment and delistment. The advantage of dynamic enlistment is that resource provider can optionally perform lazy enlistment to avoid enlisting resources unnecessarily.

To dynamically enlist the XA resource, the XA resource provider does the following:

import javax.transaction.Transaction;
// Obtain the current transaction via JNDI or TxHelper
Transaction tx = TxHelper.getTransaction();
tx.enlistResource(res);

Resource enlistment and delistment are potentially expensive operations. As an optimization, the WebLogic Server transaction manager ignores duplicate enlistments of the same resource in the same thread.

To dynamically delist the XA resource, the XA resource provider obtains the transaction as above, and calls the delistResource method, supplying the delist flag as well.

tx.delistResource(res, flag);

Note that for resources that are registered as dynamically enlisted, the enlistment step is essential. However, the delistment step is optional.

WebLogic Server transaction manager performs delayed delistment. That is, the transaction manager will actually call the end() method on XA resource on transaction suspend and completion. The transaction manager obtains the delist flag in the following order:

If the resource provider has previously delisted the XA resource, then use the delist flag that the resource provider previously supplied.
If the resource provider supports getDelistFlag() method, then obtain the delist flag by calling the method. See Optional weblogic.transaction.XAResource Interface for details.
If the resource provider supports neither of the above, conservatively use TMSUSPEND.

Optional weblogic.transaction.XAResource Interface

For the case of static delistment or omitted dynamic delistment, the WebLogic Server JTA transaction manager conservatively delists the XA resources with TMSUSPEND across method invocations to preserve potentially opened cursors. However, for some resources, it may hold up more internal resources than delisting with TMSUCCESS. XA resource provider can override the default delist flag used by WebLogic Server by supporting the optional weblogic.transaction.XAResource interface.

The weblogic.transaction.XAResource interface supports the following methods:

package weblogic.transaction;

public interface XAResource extends javax.transaction.xa.XAResource {
  int getDelistFlag();
}

If the resource provider supports it, the WebLogic Server transaction manager calls the getDelistFlag() method to obtain the delist flag to be used to delist it at transaction suspend and method end.