Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic JTA

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

WebLogic Server can participate in distributed transactions coordinated by third-party systems (referred to as foreign transaction managers). The WebLogic Server processing is done 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
- Importing Transactions with the Client Interposed Transaction Manager
- Importing Transactions with the Server Interposed Transaction Manager
- Transaction Processing for Imported Transactions
- Commit Processing for Imported Transactions
- Recovery for Imported Transactions
- JCA Resource Adapter

# Overview of Participating in Foreign-Managed Transactions

The WebLogic Server transaction manager exposes a `javax.transaction.xa.XAResource` implementation via 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 9-1 shows the interaction between the two transaction managers and the client-side gateway.

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

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

Figure 9-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
- Get the XAResource from the Interposed Transaction Manager

## 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 needs to contact the same WebLogic Server server to obtain the list of in-doubt transactions that were previously imported into WebLogic Server.

See the WebLogic Server Javadocs for the weblogic.transaction.TxHelper class for more information.

## 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 more than one client interposed transaction manager (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 manger. The WebLogic Server transaction manager then acts as a subordinate transaction manager and coordinates the transaction participants within WebLogic Server. Figure 9-3 shows the interaction between the two transaction managers and the server-side gateway.

Figure 9-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
- Get the XAResource from the Interposed Transaction Manager

## 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();

See the WebLogic Server Javadocs for the weblogic.transaction.TxHelper class for more information.

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 will cause performance issues.
- You can only use one WebLogic Server server interposed transaction manager at a time. Do not use more than one server interposed transaction manager (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 will 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 already been imported previously on the same WebLogic Server server, WebLogic Server will associate 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) will throw an `XAException` with `XAER_RMERR`. With a server-side gateway, attempting to call `xar.start` on a client or server interposed transaction manager will also throw a `XAException` with `XAER_RMERR` if there is already 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 will be 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 will be in a separate branch from the original WebLogic Server transaction.
- A foreign transaction manager should make sure 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 (see "Abandon Timeout Seconds" in the Administration Console Help) and the transaction timeout period (see "Timeout Seconds" in the Administration Console Help). 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 and overwriting of TLOG files.

# 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 (e.g., 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 section 3.4 of the JTA 1.0.1b specification:

- 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 more than one WebLogic Server participants for the imported transaction, the transaction manager logs a prepare record even if the `XAResource.commit` is a one-phase commit.

The WebLogic Server transaction manager logs a heuristic record for the imported transaction if there is heuristic outcome for `XAResource.commit` or `rollback`. The heuristic log records are stored in heuristic log files (separate from the transaction log files). The heuristic log files have extensions `heur.tlog`. For complete details about heuristic log files, see Heuristic Log Files in the Administration Console Help.

# 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.

# JCA Resource Adapter

The current JCA specification version does not have provisions for importing transactions. The JCA 1.5 specification will have APIs for importing transactions into the J2EE container. When the WebLogic Server JCA container supports the JCA 1.5 specification, resource providers can then also import transactions via JCA APIs.