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
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, 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:
- Lookup the WebLogic Server transaction manager and register it as an XAResource as necessary in the third-party system.
- Enlist and delist applicable transaction participants during transaction processing.
- 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.
- 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.
- 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
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
To access the interposed transaction manager in WebLogic Server using a client-side gateway, 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, 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 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
To access the interposed transaction manager in WebLogic Server using a server-side gateway, 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, 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.
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 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 (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 the Java Transaction API.
- 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.
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.