|
|
External, third-party systems can participate in distributed transactions coordinated by the WebLogic Server transaction manager by registering a javax.transaction.xa.XAResource implementation with the WebLogic Server transaction manager. The WebLogic Server transaction manager then drives the XAResource as part of its Two-Phase Commit (2PC) protocol. This is referred to as “exporting transactions.”
By exporting transactions, you can integrate third-party transaction managers with the WebLogic Server transaction manager if the third-party transaction manager implements the XAResource interface. With an exported transaction, the third-party transaction manager would act as a subordinate transaction manager to the WebLogic Server transaction manager.
WebLogic Server can also participate in distributed transactions coordinated by third-party systems (sometimes referred to as foreign transaction managers). The WebLogic Server processing is done as part of the work of the external transaction. The third-party transaction manager then drives the WebLogic Server transaction manager as part of its commit processing. This is referred to as “importing transactions.”
Details about coordinating third-party systems within a transaction (exporting transactions) are described in this section. Details about participating in transactions coordinated by third-party systems (importing transactions) are described in Participating in Transactions Managed by a Third-Party Transaction Manager. Note that WebLogic Server IIOP, WebLogic Tuxedo Connector (WTC) gateway, and Oracle Java Adapter for Mainframe (JAM) gateway internally use the same mechanism described in these chapters to import and export transactions in WebLogic Server.
The following sections describe how to configure third-party systems to participate in transactions coordinated by the WebLogic Server transaction manager:
In order to participate in distributed transactions coordinated by the WebLogic Server transaction manager, third-party systems must implement the javax.transaction.xa.XAResource interface and then register its XAResource object with the WebLogic Server transaction manager. For details about implementing the javax.transaction.xa.XAResource interface, refer to the
Java EE Javadocs at:
http://java.sun.com/javaee/5/docs/api/javax/transaction/xa/XAResource.html
During transaction processing, you must enlist the XAResource object of the third-party system with each applicable transaction object.
Figure 11-1 shows the process for third-party systems to participate in transactions coordinated by the WebLogic Server transaction manager.
Depending on the enlistment mode that you use when you enlist an XAResource object with a transaction, WebLogic Server may automatically delist the XAResource object at the appropriate time. For more information about enlistment and delistment, see Enlisting and Delisting an XAResource in a Transaction. For more information about registering XAResource objects with the WebLogic Server transaction manager, see Registering an XAResource to Participate in Transactions.
In order to participate in distributed transactions coordinated by the WebLogic Server transaction manager, third-party systems must implement the javax.transaction.xa.XAResource interface and then register its XAResource object with the WebLogic Server transaction manager. Registration is required to:
XAResource. The branch qualifier identifies the transaction branch of the resource manager instance and is used for all distributed transactions that the resource manager (RM) instance participates in. Each transaction branch represents a unit of work in the distributed transaction and is isolated from other branches. Each transaction branch receives exactly one set of prepare-commit calls during Two-Phase Commit (2PC) processing. The WebLogic Server transaction manager uses the resource name as the transaction branch qualifier.
A resource manager instance is defined by the XAResource.isSameRM method. XAResource instances that belong to the same resource manager instance should return true for isSameRM. Note that you should avoid registering the same resource manager instance under different resource names (i.e., different resource branches) to avoid confusion of transaction branches.
javax.transaction.Transaction object. The WebLogic Server transaction manager provides three enlistment modes: static, dynamic, and object-oriented. Enlistment modes are discussed in greater detail in Enlisting and Delisting an XAResource in a Transaction. XAResource in the event that the WebLogic Server transaction manager must perform crash recovery. (The JTA Specification does not define a standard API to do so; see
Java Transaction API). The Java Transaction API suggests that the transaction manager is responsible for assigning the branch qualifiers. However, for recovery to work properly, the same transaction branch qualifier needs to be supplied both at normal processing and upon crash recovery. As the transaction branch qualifier is specified during registration, registration with the WebLogic Server transaction manager is required to support crash recovery and normal transaction processing.
During recovery, the WebLogic Server transaction manager performs the following tasks:
XAResource.recover. It then commits or rolls back the returned transactions (Xids) that belonged to it. (Note that the returned Xids would already have the specified branch qualifier.)| Note: | Registration is a per-process action (compared with enlistment and delistment which is per-transaction). |
Failure to register the XAResource implementation with the WebLogic Server transaction manager may result in unexpected transaction branching behavior. If registration is not performed before the XA resource is enlisted with a WebLogic Server distributed transaction, the WebLogic Server transaction manager will use the class name of the XAResource instance as the resource name (and thus the branch qualifier), which may cause undesirable resource name and transaction branch conflicts.
Each resource manager instance should register itself only once with the WebLogic Server transaction manager. Each resource manager instance, as identified by the resource name during registration, adds significant overhead to the system during recovery and commit processing and health monitoring, increases memory used by associated internal data structures, reduces efficiency in searching through internal maps, and so forth. Therefore, for scalability and performance reasons, you should not indiscriminately register XAResource instances under different transaction branches.
Note that the JTA XAResource adopts an explicit transaction model, where the Xid is always explicitly passed in the XAResource methods and a single resource manager instance handles all of the transactions. This is in contrast to the CORBA OTS Resource, which adopts an implicit transaction model, where there is a different OTS Resource instance for each transaction that it participates in. You should use the JTA model when designing an XAResource.
Each foreign resource manager instance should register an XAResource instance with the WebLogic Server transaction manager upon server startup. In WebLogic Server, you can use startup classes to register foreign transaction managers.Follow these steps to register the resource manager with the WebLogic Server transaction manager:
TxHelper interface:import javax.transaction.xa.XAResource;
import weblogic.transaction.TransactionManager;
import weblogic.transaction.TxHelper;
InitialContext initCtx = ... ; // initialized to the initial context
TransactionManager tm = TxHelper.getTransactionManager();
TransactionManager tm = (TransactionManager)initCtx.lookup("weblogic.transaction.TransactionManager");TransactionManager tm = (TransactionManager)initCtx.lookup("javax.transaction.TransactionManager");String name = ... ; // name of the RM instance
XAResource res = ... ; // an XAResource instance of the RM instance
tm.registerResource(name, res); // register a resource with the standard enlistment mode
tm.registerDynamicResource(name, res); // register a resource with the dynamic enlistment mode
tm.registerStaticResource(name, res); // register a resource with the static enlistment mode
Refer to Enlisting and Delisting an XAResource in a Transaction for a detailed discussion of the different enlistment modes. Note that when you register the XAResource, you specify the enlistment mode that will be used subsequently, but you are not actually enlisting the resource during the registration process. Actual enlistment should be done with the transaction (not at server startup) using a different API, which is also discussed in detail in Enlisting and Delisting an XAResource in a Transaction.
Each XAResource instance that you register is used for recovery and commit processing of multiple transactions in parallel. Make sure that the XAResource instance supports resource sharing as defined in JTA Specification Version 1.0.1B Section 3.4.6.
| Note: | Duplicate registration of the same XAResource is ignored. |
You should unregister the XAResource from the WebLogic Server transaction manager when the resource no longer accept new requests. Use the following method to unregister the XAResource:
tm.unregisterResource(name, res);
For an XAResource to participate in a distributed transaction, the XAResource instance must be enlisted with the Transaction object. Depending on the enlistment mode, you may need to perform different actions. The WebLogic Server transaction manager supports the following enlistment modes:
Even though you enlist the XAResource with the Transaction object, the enlistment mode is determined when you register the XAResource with the WebLogic Server transaction manger, not when you enlist the resource in the Transaction. See Registering an XAResource to Participate in Transactions.
XAResource.start and end calls can be expensive. The WebLogic Server transaction manager provides the following optimizations to minimize the number of these calls:
Whether or not your XAResource implementation performs any explicit delistment or not, the WebLogic Server transaction manager always delays delisting of any XAResource instances that are enlisted in the current transaction until immediately before the following events, at which time the XAResource is delisted:
The WebLogic Server transaction manager ignores any explicit enlistment of an XAResource that is already enlisted. This may happen if the XAResource is explicitly delisted (which is delayed or ignored by the WebLogic Server transaction manager as mentioned above) and is subsequently re-enlisted within the duration of the same call.
By default, the WebLogic Server transaction manager delists the XAResource by calling XAResource.end with the TMSUSPEND flag. Some database management systems may keep cursors open if XAResource.end is called with TMSUSPEND, so you may prefer to delist an XAResource by calling XAResource.end with TMSUCCESS wherever possible. To do so, you can implement the weblogic.transaction.XAResource interface (instead of the javax.transaction.xa.XAResource), which includes the getDelistFlag method. See the WebLogic Server Javadocs for more details.
With standard enlistment mode, you need to enlist the XAResource instance only once with the Transaction object. Also, it is possible to enlist more than one XAResource instance of the same branch with the same transaction. The WebLogic Server transaction manager ensures that XAResource.end is called on all XAResource instances when appropriate (as discussed below). The WebLogic Server transaction manager ensures that each branch receives only one set of prepare-commit calls during transaction commit time. However, attempting to enlist a particular XAResource instance when it is already enlisted will be ignored.
Standard enlistment simplifies enlistment, but it may also cause unnecessary enlistment and delistment of an XAResource if the resource is not accessed at all within the duration of a particular method call.
To enlist an XAResource with the Transaction object, follow these steps:
TransactionHelper interface:import weblogic.transaction.Transaction; // extends javax.transaction.Transaction
import weblogic.transaction.TransactionHelper;
Transaction tx = TransactionHelper.getTransaction();
tx.enlistResource(res);
After the XAResource is enlisted with the Transaction, the WebLogic Server transaction manager manages any subsequent delistment (as described in Enlisting and Delisting an XAResource in a Transaction) and re-enlistment. For standard enlistment mode, the WebLogic Server transaction manager re-enlists the XAResource in the same Transaction upon the following occasions:
With the dynamic enlistment mode, you must enlist the XAResource instance with the Transaction object before every access of the resource. With this enlistment mode, only one XAResource instance from each transaction branch is allowed to be enlisted for each transaction at a time. The WebLogic Server transaction manager ignores attempts to enlist additional XAResource instances (of the same transaction branch) after the first instance is enlisted, but before it is delisted.
With dynamic enlistment, enlistments and delistments of XAResource instances are minimized.
The steps for enlisting the XAResource is the same as described in Standard Enlistment.
With static enlistment mode, you do not need to enlist the XAResource instance with any Transaction object. The WebLogic Server transaction manager implicitly enlists the XAResource for all transactions with the following events:
| Note: | Consider the following before using the static enlistment mode: |
XAResource.start and XAResource.end can be called on the same XAResource instance in an interleaved manner for different Xids in different threads. You must ensure that the XAResource supports such an association pattern, which is not required by the JTA specification. | Note: | Due to the performance overhead, poor fault isolation, and demanding transaction association requirement, static enlistment should only be used with discretion and after careful consideration. |
During commit processing, the WebLogic Server transaction manager will either use the XAResource instances currently enlisted with the transaction, or the XAResource instances that are registered with the transaction manager to perform the two-phase commit. The WebLogic Server transaction manager ensures that each transaction branch will receive only one set of prepare-commit calls. You must ensure that any XAResource instance can be used for commit processing for multiple transactions simultaneously from different threads, as defined in JTA Specification Version 1.0.1B Section 3.4.6.
When a WebLogic Server server is restarted, the WebLogic Server transaction manager reads its own transaction logs (with log records of transactions that are successfully prepared, but may not have completed the second commit phase of 2PC processing). The WebLogic Server transaction manager then continues to retry commit of the XAResources for these transactions. As discussed in Registering an XAResource to Participate in Transactions, one purpose of the WebLogic Server transaction manager resource registration API is for bootstrapping XAResource instances for recovery. You must make sure that an XAResource instance is registered with the WebLogic Server transaction manager upon server restart. The WebLogic Server transaction manager retries the commit call every minute, until a valid XAResource instance is registered with the WebLogic Server transaction manager.
When a transaction manager that is acting as a transaction coordinator crashes, it is possible that the coordinator may not have logged some in-doubt transactions in the coordinator’s transaction log. Thus, upon server restart, the coordinator needs to call XAResource.recover on the resource managers, and roll back the in-doubt transactions that were not logged. As with commit retries, the WebLogic Server transaction manager retries XAResource.recover every 5 minutes, until a valid XAResource instance is registered with the WebLogic Server transaction manager.
The WebLogic Server transaction manager checkpoints a new XAResource in its transaction log records when the XAResource is first enlisted with the WebLogic Server transaction manager. Upon server restart, the WebLogic Server transaction manager then calls XAResource.recover on all the resources previously checkpointed (removed from the transaction log records after the transaction completed). A resource is only removed from a checkpoint record if it has not been accessed for the last PurgeResourceFromCheckpointIntervalSeconds interval (default is 24 hours). Therefore, to reduce the resource recovery overhead, you should make sure that only a small number of resource manager instances are registered with the WebLogic Server transaction manager.
When implementing XAResource.recover, you should use the flags as described in the X/Open XA specification as follows:
XAResource.recover with TMSTARTRSCAN, the resource returns the first batch of in-doubt Xids.
The WebLogic Server transaction manager then calls XAResource.recover with TMNOFLAGS repeatedly, until the resource returns either null or a zero-length array to signal that there are no more Xids to recover. If the resource has already returned all the Xids in the previous XAResource.recover(TMSTARTRSCAN) call, then it can either return null or a zero-length array here, or it may also throw XAER_PROTO, to indicate that it has already finished and forgotten the previous recovery scan. A common XAResource.recover implementation problem is ignoring the flags or always returning the same set of Xids on XAResource.recover(TMNOFLAGS). This will cause the WebLogic Server transaction manager recovery to loop infinitely, and subsequently fail.
XAResource.recover with TMENDRSCAN flag to end the recovery scan. The resource may return additional Xids.
To prevent losing server threads to faulty XAResources, WebLogic Server JTA has an internal resource health monitoring mechanism. A resource is considered active if either there are no pending requests or the result from any of the XAResource pending requests is not XAER_RMFAIL. If an XAResource is not active within two minutes, the WebLogic Server transaction manager will declare it dead. Any further requests to the XAResource are shunned, and an XAER_RMFAIL XAException is thrown.
The two minute interval can be configured via the maxXACallMillis JTAMBean attribute. It is not exposed through the Administration Console. You can configure maxXACallMillis in the config.xml file. For example:
<Domain>
....
<JTA
MaxXACallMillis="240000"
/>
....
</Domain>
To receive notification from the WebLogic Server transaction manager and to inform the WebLogic Server transaction manager whether it is indeed dead when the resource is about to be declared dead, you can implement weblogic.transaction.XAResource (which extends javax.transaction.xa.XAResource) and register it with the transaction manager. The transaction manager will call the detectUnavailable method of the XAResource when it is about to declare it unavailable. If the XAResource returns true, then it will not be declared unavailable. If the XAResource is indeed unavailable, it can use this opportunity to perform cleanup and re-registration with the transaction manager. See the WebLogic Server Javadocs for weblogic.transaction.XAResource for more information.
Besides registering with the WebLogic Server transaction manager directly, you can also implement the Java EE Connector Architecture resource adapter interfaces. When you deploy the resource adapter, the WebLogic Server Java EE container will register the resource manager's XAResource with the WebLogic Server transaction manager automatically.
For more information, see Programming WebLogic Resource Adapters.
The following sections provide tips for exporting and importing transactions with the WebLogic Server transaction manager:
The WebLogic Server transaction manager exposes the transaction log to be shared with system applications such as gateways. This provides a way for system applications to take advantage of the box-carring (batching) transaction log optimization of the WebLogic Server transaction manager for fast logging. Note that it is important to release the transaction log records in a timely fashion. (The WebLogic Server transaction manager will only remove a transaction log file if all the records in it are released). Failure to do so may result in a large number of transaction log files, and could lead to re-commit of a large number of already committed transactions, or in an extreme case, circular collision and overwriting of transaction log files.
The WebLogic Server transaction manager exposes a transaction logger interface: weblogic.transaction.TransactionLogger. It is only available on the server, and it can be obtained with the following steps:
The XAResource’s log records must implement the weblogic.transaction.TransactionLoggable interface in order to be written to the transaction log. See the WebLogic Server Javadocs for the weblogic.transaction.TransactionLogger interface for more details and the usage of the TransactionLogger interface.
A WebLogic Server JTA transaction object is associated with both local and global properties. Global properties are propagated with the transaction propagation context among servers, and are also saved as part of the log record in the transaction log. You can access the transaction global properties as follows:
import weblogic.transaction.Transaction;
import weblogic.transaction.TransactionHelper;
Transaction tx = TransactionHelper.getTransaction(); // Get the transaction associated with the thread
Transaction tx = TxHelper.getTransaction(xid); // Get the transaction with the given Xid
tx.setProperty("foo", "fooValue");tx.getProperty("bar");See the WebLogic Server Javadocs for the weblogic.transaction.TxHelper class for more information.
You can use the TxHelper.createXid(int formatId, byte[] gtrid, byte[] bqual) method to create Xids, for example, to return to the WebLogic Server transaction manager on recovery.
See the WebLogic Server Javadocs for the weblogic.transaction.TxHelper class for more information.
WebLogic Server JTA transaction objects do not have branch qualifiers (i.e., TxHelper.getTransaction().getXid().getBranchQualifier() would be null). Since the branch qualifiers are specific to individual resource managers, the WebLogic Server transaction manager only sets the branch qualifiers in the Xids that are passed into XAResource methods.
The WebLogic Server JTA provides the TxHelper.getTransaction() API to return the transaction associated with the current thread. However, note that WebLogic Server JTA suspends the transaction context before calling the XAResource methods, so you should only rely on the Xid input parameter to identify the transaction, but not the transaction associated with the current thread.
Refer to the JTA specification 1.0.1B Section 4.1 for a connection-based Resource Usage scenario, which illustrates the JTA interaction between the transaction manager and resource manager. The JTA specification is available at http://java.sun.com/products/jta/.
|