12 Participating in Transactions Managed by a Third-Party Transaction Manager

This chapter describes how WebLogic Server participates in distributed transactions coordinated by third-party systems (referred to as foreign transaction managers). The WebLogic Server processing occurs as part of the work of the external transaction. The foreign transaction manager then drives the WebLogic Server transaction manager as part of its commit processing. This is referred to as "importing" transactions into WebLogic Server.

The following sections describe the process for configuring and participating in foreign-managed transactions:

Overview of Participating in Foreign-Managed Transactions

The WebLogic Server transaction manager exposes a javax.transaction.xa.XAResource implementation using the weblogic.transaction.InterposedTransactionManager interface. A foreign transaction manager can access the InterposedTransactionManager interface to coordinate the WebLogic Server transaction manager XAResource during its commit processing.

When importing a transaction from a foreign transaction manager into the WebLogic Server transaction manager, you must register the WebLogic Server interposed transaction manager as a subordinate with the foreign transaction manager. The WebLogic Server transaction manager then acts as the coordinator for the imported transaction within WebLogic Server.

WebLogic Server supports two configuration schemes for importing transactions:

  • Using a client-side gateway (implemented externally to WebLogic Server) that uses the client interposed transaction manager

  • Using a server-side gateway implemented on a WebLogic Server instance that uses the server interposed transaction manager

Although there are some differences in limitations and in implementation details, the basic behavior is the same for importing transactions in both configurations:

  1. Lookup the WebLogic Server transaction manager and register it as an XAResource as necessary in the third-party system.

  2. Enlist and delist applicable transaction participants during transaction processing.

  3. Send the prepare message to the WebLogic Server transaction manager, which then acts as a subordinate transaction manager and coordinates the prepare phase for transaction participants within WebLogic Server.

  4. Send the commit or roll back message to the WebLogic Server transaction manager, which then acts as a subordinate transaction manager and coordinates the second phase of the two-phase commit process for transaction participants within WebLogic Server.

  5. Unregister, as necessary.

Importing Transactions with the Client Interposed Transaction Manager

You can use the client interposed transaction manager in WebLogic Server to drive the two-phase commit process for transactions that are coordinated by a third-party transaction manager and include transaction participants within WebLogic Server, such as JMS resources and JDBC resources. The client interposed transaction manager is an implementation of the javax.transaction.xa.XAResource interface. You access the client interposed transaction manager directly from the third-party application, typically from a gateway in the third-party application. The transaction manager in the third-party system then sends the prepare and commit messages to the gateway, which propagates the message to the WebLogic Server transaction manger. The WebLogic Server transaction manager then acts as a subordinate transaction manager and coordinates the transaction participants within WebLogic Server. Figure 12-1 shows the interaction between the two transaction managers and the client-side gateway.

Figure 12-1 Importing Transactions into WebLogic Server Using a Client-Side Gateway

Description of Figure 12-1 follows
Description of "Figure 12-1 Importing Transactions into WebLogic Server Using a Client-Side Gateway"

Figure 12-2 shows the flow of interactions between a foreign transaction manager, WebLogic Server client-side JTA objects, and the WebLogic Server transaction manager.

Figure 12-2 State Diagram Illustrating Steps to Import a Transaction Using the Client Interposed Transaction Manager

Description of Figure 12-2 follows
Description of "Figure 12-2 State Diagram Illustrating Steps to Import a Transaction Using the Client Interposed Transaction Manager"

To access the interposed transaction manager in WebLogic Server using a client-side gateway, you must perform the following steps:

Get the Client Interposed Transaction Manager

In a client-side gateway, the you can get the WebLogic server interposed transaction manager's XAResource with the getClientInterposedTransactionManager method. For example:

import javax.naming.Context;
import weblogic.transaction.InterposedTransactionManager;
import weblogic.transaction.TxHelper;
Context initialCtx;
String serverName;
InterposedTransactionManager itm = TxHelper.getClientInterposedTransactionManager(initialCtx, serverName);

The server name parameter is the name of the server that acts as the interposed transaction manager for the foreign transaction. When the foreign transaction manager performs crash recovery, it must contact the same WebLogic Server server to obtain the list of in-doubt transactions that were previously imported into WebLogic Server.

For more information, see weblogic.transaction.TxHelper in the Oracle WebLogic Server API Reference.

Get the XAResource from the Interposed Transaction Manager

After you get the interposed transaction manager, you must get the XAResource object associated with the interposed transaction manager:

import javax.transaction.xa.XAResource;
XAResource xar = itm.getXAResource();

Limitations of the Client Interposed Transaction Manager

Note the following limitations when importing transactions using a client-side gateway:

  • You cannot use the TxHelper.getServerInterposedTransactionManager() method in client-side gateways.

  • You can only use one WebLogic Server client interposed transaction manager at a time. Do not use multiple client interposed transaction managers (connecting to different WebLogic Server servers) to import transactions at the same time. (See Transaction Processing for Imported Transactions for more information about this limitation and how transactions are processed with the WebLogic Server interposed transaction manager.)

Importing Transactions with the Server Interposed Transaction Manager

You can use the server interposed transaction manager in WebLogic Server to drive the two-phase commit process for transactions that are coordinated by a third-party transaction manager and include transaction participants within WebLogic Server, such as JMS resources and JDBC resources. The server interposed transaction manager is an implementation of the javax.transaction.xa.XAResource interface. You access the server interposed transaction manager by creating a server-side gateway on WebLogic Server and then accessing the gateway from a third-party system. The transaction manager in the third-party system then sends the prepare and commit messages to the server-side gateway, which propagates the message to the WebLogic Server transaction manager. The WebLogic Server transaction manager then acts as a subordinate transaction manager and coordinates the transaction participants within WebLogic Server. Figure 12-3 shows the interaction between the two transaction managers and the server-side gateway.

Figure 12-3 Importing Transactions into WebLogic Server Using a Server-Side Gateway

Description of Figure 12-3 follows
Description of "Figure 12-3 Importing Transactions into WebLogic Server Using a Server-Side Gateway"

To access the interposed transaction manager in WebLogic Server using a server-side gateway, you must perform the following steps:

Get the Server Interposed Transaction Manager

In a server-side gateway, you can get the interposed transaction manager's XAResource as follows:

import javax.naming.Context;
import weblogic.transaction.InterposedTransactionManager;
import weblogic.transaction.TxHelper;
InterposedTransactionManager itm = TxHelper.getServerInterposedTransactionManager();

For more information, see weblogic.transaction.TxHelper in the Oracle WebLogic Server API Reference.

After you get the interposed transaction manager, you must get the XAResource. See Get the XAResource from the Interposed Transaction Manager.

Limitations of the Server Interposed Transaction Manager

Note the following limitations when importing transactions using a server-side gateway:

  • Do not use the TxHelper.getClientInterposedTransactionManager() method in a server-side gateway on a WebLogic Server server. Doing so causes performance issues.

  • You can only use one WebLogic Server server interposed transaction manager at a time. Do not use multiple server interposed transaction managers (on the same thread) to import transactions at the same time. (See Transaction Processing for Imported Transactions for more information about this limitation and how transactions are processed with the WebLogic Server interposed transaction manager.)

Transaction Processing for Imported Transactions

To import a foreign transaction into WebLogic Server, the foreign transaction manager or gateway can do the following:

xar.start(foreignXid, TMNOFLAGS);

This operation associates the current thread with the imported transaction. All subsequent calls made to other servers propagate the imported WebLogic Server transaction, until the transaction is disassociated from the thread.

Note:

The flag is ignored by the WebLogic Server transaction manager. If the foreign Xid has been imported previously on the same WebLogic Server server, WebLogic Server associates the current thread with the previously imported WebLogic Server transaction.

To disassociate the imported transaction from the current thread, the foreign transaction manager or gateway should do the following:

xar.end(foreignXid, TMSUCCESS);

Note that the WebLogic Server transaction manager ignores the flag.

Transaction Processing Limitations for Imported Transactions

Note the following processing limitations and behavior for imported transactions:

  • After a WebLogic Server transaction is started, the gateway cannot call start again on the same thread. With a client-side gateway, you can only call xar.start on one client interposed transaction manager at a time. Attempting to call xar.start on another client interposed transaction manager (before xar.end was called on the first one) throws an XAException with XAER_RMERR. With a server-side gateway, attempting to call xar.start on a client or server interposed transaction manager also throws a XAException with XAER_RMERR if there is an active transaction associated with the current thread.

  • The WebLogic Server interposed transaction manager's XAResource exhibits loosely-coupled transaction branching behavior on different WebLogic Server servers. That is, if the same foreign Xid is imported on different WebLogic Server servers, they are imported to different WebLogic Server transactions.

  • The WebLogic Server transaction manager does not flatten the transaction tree, for example, the imported transaction of a previously exported WebLogic Server transaction are in a separate branch from the original WebLogic Server transaction.

  • A foreign transaction manager should ensure that all foreign Xids that are imported into WebLogic Server are unique and are not reused within the sum of the transaction abandon timeout period and the transaction timeout period. Failure to do so may result in log records that are never released in the WebLogic Server transaction manager. This could lead to inefficient crash recovery.

Commit Processing for Imported Transactions

The foreign transaction manager should drive the interposed transaction manager in the 2PC protocol as it does the other XAResources. Note that the beforeCompletion callbacks registered with the WebLogic Server JTA (for example, the EJB container) are called when the foreign transaction manager prepares the interposed transaction manager's XAResource. The afterCompletion callbacks are called during XAResource.commit or XAResource.rollback.

The WebLogic Server interposed transaction manager honors the XAResource contract as described in the Java Transaction API at http://www.oracle.com/technetwork/java/javaee/jta/index.html.

  • Once prepared by a foreign transaction manager, the WebLogic Server interposed transaction manager waits persistently for a commit or rollback outcome from the foreign transaction manager until the transaction abandon timeout expires.

  • The WebLogic Server interposed transaction manager remembers heuristic outcomes persistently until being told to forget about the transaction by the foreign transaction manager or until transaction abandon timeout.

The WebLogic Server transaction manager logs a prepare record for the imported transaction after all the WebLogic Server participants are successfully prepared. If there are multiple WebLogic Server participants for the imported transaction, the transaction manager logs a prepare record even if the XAResource.commit is a one-phase commit.

Recovery for Imported Transactions

During the crash recovery of the foreign transaction manager, the foreign transaction manager must get the XAResource of the WebLogic Server interposed transaction manager again, and call recover on it. The WebLogic Server interposed transaction manager then returns the list of prepared or heuristically completed transactions. The foreign transaction manager should then resolve those in-doubt transactions: either commit or rollback the prepared transactions, and call forget on the heuristically completed transactions.