Managing WebLogic JTA

The Administration Console lets you configure and monitor the transaction service for a WebLogic domain. The configuration settings for JTA are persisted in the domain's config.xml configuration file. You can specify values for the transaction timeouts, set the behavior of the transaction manager, and define how transaction logs are maintained. The JTA configuration attributes apply at the domain level, while the monitoring and logging tasks apply at the individual server level. You can access the configuration attributes for the JTA by selecting the domain from the left panel and then choosing the Configuration/JTA tab. All of these JTA settings can be altered dynamically while the servers are running. Here's a description of the JTA settings you can modify for the domain:

Timeout Seconds

This determines the transaction timeout for active transactions. This is relevant to active transactions that have not yet entered the prepare phase (defaults to 30 seconds).

Abandon Timeout Seconds

The server will abandon a transaction after this amount of time has passed (defaults to 24hrs). A transaction can be abandoned after it has entered the prepare phase of a two-phase commit.

Before Completion Iteration Limit

This setting determines the limit on the number of Synchronization objects that can be registered for a transaction (defaults to 10).

Max Transactions

This setting determines the maximum number of simultaneous transactions allowed on a WebLogic Server instance (defaults to 10000).

Max Unique Name Statistics

This determines the maximum number of transactions for which statistics will be maintained (defaults to 1000).

Checkpoint Interval Seconds

This setting determines the duration after which WebLogic's transaction manager creates a new transaction log and checks old log files to see whether they can be deleted (defaults to 5 minutes).

Forget Heuristics

If this setting has a value of true, the transaction manager instructs all registered XA-compliant resources to "forget" about the heuristically completed transaction branch. This means that when a resource manager reports a heuristic exception, the transaction manager records the heuristic outcome and invokes the forget( ) method on the participating XAResource. By default, this setting is enabled. Refer to Heuristic Completions in this chapter for more information on distributed transactions that result in a heuristic outcome.

Abandoning Transactions

In a two-phase commit protocol, the transaction manager coordinates all resource managers involved in a transaction. After all resource managers have voted to commit or roll back, the transaction manager conveys the final decision to all resource managers in the second phase. Then, the transaction manager will continue to wait until completion of the transaction until all resource managers have successfully completed their work. The AbandonTimeoutSeconds attribute defines the maximum amount of time that the transaction manager will wait for the resource managers to complete their work. After the timeout expires, the transaction manager will abandon the transaction and make no further attempt to resolve resources that have failed to acknowledge their outcome. If the transaction had completed its prepare phase, the transaction manager will roll it back and report a heuristic error in the server log.

Heuristic Completions

The transaction manager coordinates updates to all resources involved in a distributed transaction. Depending on how the resource managers vote during the prepare phase, a decision will be made as to whether all resources may commit their updates. A heuristic completion occurs when a resource makes a unilateral decision (without waiting for a decision from the transaction manager) to commit or roll back all updates. A heuristic decision can occur due to several reasonsfor instance, if a network failure occurs that results in a premature rollback, or if the transaction times out. Whenever a heuristic decision is made, there is a risk that the decision may conflict with the eventual decision of the transaction manager, and therefore result in loss of data integrity.

A heuristic outcome can occur in one of four ways:

       

HeuristicCommit

A resource participating in a transaction decides independently to commit its work, without waiting for a decision. If the transaction manager later decides to roll back, the decision of the participating resource was incorrect and could lead to data inconsistency.

HeuristicRollback

A resource participating in a transaction decides independently to roll back its work, without waiting for a decision. If the transaction manager later decides to commit, the decision of the participating resource was incorrect and could result in inconsistencies.

HeuristicMixed

The transaction manager is aware that the transaction has resulted in a mixed outcome because some participating resources decided independently to commit their changes, while others decided to roll back their changes, without waiting for a decision.

HeuristicHazard

The transaction manager is aware that the transaction may have resulted in a mixed outcome, but because of system or resource failures, it is unable to verify whether a mixed outcome definitely occurred.

When a resource takes a heuristic decision that contravenes the eventual outcome of the transaction, it is still responsible for reporting its action to the transaction manager. In fact, we need to consider two scenarios:

• If the heuristic decision is consistent with the eventual outcome of the transaction, the transaction manager invokes the forget( ) method on the XAResource i.e., it forgets about the heuristic decision made by the resource. No further action is required because the heuristic decision was in line with the outcome of the transaction.
• If the heuristic decision is in conflict with the eventual outcome of the transaction, the resource consults its records of the decision and then returns one of the heuristic outcome exceptions.

Usually, a message indicating the nature of the heuristic outcome is added to the server logs, and retained until the resource is instructed by the transaction manager to "forget" about the transaction.

The transaction timeout is a fundamental setting because it determines the timeout behavior of all distributed transactions. You also can override the transaction timeout on a case-by-case basis, as the following code illustrates:

UserTransaction tx = 
 (UserTransaction) ctx.lookup("java:comp/UserTransaction");
tx.setTransactionTimeout(120);
tx.begin( ); 
// now do your work within the new transaction context ...

6.4.1 Monitoring Transactions

You can use the Administration Console to monitor transaction activity for each server instance. In fact, you even can use the Console to manually roll back or commit active transactions. You can view transaction statistics for each server by selecting the server in the left frame and then selecting the Monitoring/JTA tab. These statistics include the total number of transactions, transactions with a specific outcome (committed, rolled back, heuristic completions), rollbacks by specific reasons, abandoned transactions, and average commit time. You also can display further information on active transactions. If you choose the "Monitor all Transactions by Name" option, you can list all named transactions. And if you choose the "Monitor all Transactions by Resource" option, you can list all transactional resources that can be accessed by the server. So, for example, if you have configured a connection pool using an XA-aware driver, the connection pool is listed here together with statistics on all transactions associated with the pool. These statistics include the total number of transactions and the number of transactions that have committed and rolled back.

The "Monitor all Inflight Transactions" option is probably the most powerful. This option lists all the currently active transactions on the server. Note that this list is a snapshot, and it's conceivable that by the time you click an active transaction, the transaction may no longer be active. WebLogic simply informs you of this if it happens. If the transaction is still active by the time you click it, you can view information about the selected transaction, including: the transaction identifier; the name of the server coordinating the transaction; the transaction status; the number of seconds that the transaction has been active; servers participating in the transaction; XA resources participating in the transaction; and any properties assigned to the transaction by the application that created it.

You also have the option of manually resolving the transaction, by using menu controls in the Administration Console that let you manually commit or roll back the transaction. The controls that are available to you will depend on the current state of the transaction. Table 6-1 lists the various states of a transaction, as well as which controls are offered for that state.

Table 6-1. Transaction state and manual control

Status	Definition	Controls
Active	This state defines an active transaction. No commit has been issued yet.	Rollback
Preparing	This state defines the time that has elapsed from the point when the resources have been called on to prepare, up to the point when all participants have responded that they are ready to commit.	Rollback
Prepared	This state defines the time that has elapsed from the point when all participants have responded to prepare, up to the point when the commit or rollback has been initiated.	Commit/Rollback
Committing	This state defines the time that has elapsed from the Prepared state to the point when all participants have been informed of the outcome.	Commit
Committed	This state defines a committed transaction. Check to see whether the transaction completed heuristically.	Commit
Rolling Back	This state defines the time that has elapsed from the point when rollback processing is initiated, up to the point when all resources have been instructed to roll back.	Rollback
Rolled Back	This state defines a rolled-back transaction. Check to see whether the transaction completed heuristically.	Rollback
Marked Roll Back	This state defines a transaction that has been marked for rollback, perhaps as a result of a call to the setRollbackOnly( ) method.	Rollback
Unknown	This status is shown if the current status cannot be determined.	Commit/Rollback

For example, if your transaction is in the Preparing state, you will be allowed to manually roll back the transaction (but not force a commit). Each control is presented in two forms: a global and a local form. For example, if you are allowed to commit a transaction, you will find options to Force Local Commit and to Force Global Commit:

• The Force Local Commit and Force Local RollBack options act only on those participating resources that are hosted on the current server instance. If you select either option, WebLogic issues a commit (or rollback) on all participating resources hosted on the selected server only, after which the transaction is removed from the local transaction manager.
• On the contrary, the Force Global Commit and Force Global RollBack options act on all resources involved in the distributed transaction. If you select either option, the server on which the transaction originated (i.e., the coordinating server) asynchronously issues a local commit (or rollback) on all servers participating in the transaction. However, if the coordinating server cannot be reached, a javax.transaction.SystemException will be thrown.

6.4.2 Transaction Logs

Each WebLogic Server instance has a transaction log that captures information about committed transactions that may not have completed. The transaction log enables WebLogic Server to recover transactions that could not be completed before the server failed. This recovery procedure is executed the next time you restart the server after a system crash or network failure. As part of the recovery procedure, the server inspects the transaction log for incomplete transactions and tries to complete them.

Log files for the transaction log cannot be viewed because they are in binary format. You can locate the transaction files (.tlog files) in the server's folder in the domain's directory. If you wish to modify the default location of the transaction log files, you can use the Administration Console to set a value for the Transaction Log File Prefix setting for the server. You can access this setting for the server under the Logging/ JTA tab.

The transaction logs maintain a log of transactions that are ready to commit but have not yet completed. The log files are vital to WebLogic's transaction recovery when the server restarts after a failure. Therefore, in order to maintain data integrity, it is recommended that you do not delete the transaction log files manually. WebLogic automatically deletes them when the records in the log file are no longer required.

Transaction log files are critical for the WebLogic transaction service, so you should ensure that log files are stored on highly available filesystems (such as on a RAID disk, dual-ported SCSI disk, or a SAN [Storage Area Network] solution). When migrating a server to another machine, you must transfer the transaction log files as well. Too many log files are an indication of many long-running transactions that haven't yet completed, due to either a resource failure or perhaps a large timeout value for the transaction. WebLogic throws a SystemException on a commit if the filesystem holding the transaction logs runs out of space.

6.4.3 Transaction Recovery

WebLogic Server is able to recover failed transactions that occur because of a system crash or even crashes that happen during recovery. The Transaction Recovery Service automatically tries to recover transactions after restarting a failed server. The recovery service, which owns the transaction logs for the server, looks for incomplete transactions in the log files and attempts to complete them. Because WebLogic Server is designed to gracefully handle transaction recovery after a system crash, you should restart the failed server and allow the Transaction Recovery Service to complete pending transactions.

WebLogic executes a series of steps as part of the transaction recovery procedure:

1. If a transaction has reached the second phase of a two-phase commit and a commit decision has been made, the recovery service commits all updates for the transaction.
2. For transactions that already have been prepared with a resource manager, the recovery service invokes the recover( ) method for each XAResource and then resolves each Xid returned by the recover( ) method by invoking either the commit( ), rollback( ), or forget( ) method on the XAResource.
3. If a transaction has recorded a heuristic completion, the recovery service records the heuristic exception in the server log, and tells the transaction manager to forget about the heuristically completed transaction (that is, if the Forget Heuristics attribute has been enabled for the server).

The Transaction Recovery Service provides predictable, consistent handling of failed transactions. If a transaction is ready to commit (or to roll back) but has not been committed (or rolled back) before the crash, and the recover( ) method on the XAResource resolves to the same transaction ID, the recovery service consistently tries to commit (or roll back) the transaction. This way, the transaction recovery after a crash can never result in heuristic completions. Also, the transaction manager persists in trying to resolve each pending transaction to either a commit or a rollback. Only a timeout attribute forces the Transaction Recovery Service to abandon the recovery for that transaction.

6.4.4 Handling Failed Servers

If you are unable to restart a failed server within a reasonable amount of time, you need to be able to offload the task of recovering incomplete transactions to a backup server. In the case of a nonclustered server, you can manually move the transaction log files from the failed server to the new server. Alternatively, you can make them available to the new server if you are using a shared storage solution. You need to adjust the Transaction Log File Prefix setting to the path for the log files and start the new server. The new server instance will then attempt to recover the failed transactions using the log files.

If a clustered server crashes, you can use the Administration Console to manually migrate the Transaction Recovery Service to another member of the same cluster. You can migrate the recovery service from the Control/JTA Migrate tab for the failed server. This way, the recovery service on the backup server takes ownership of the transaction log files for the failed server and attempts to resolve all pending transactions. Make sure that the failed server is not running when you attempt this. Once the Transaction Recovery Service has completed all failed transactions, the backup server relinquishes control over the service and the log files. The failed server can reclaim the recovery service and the log files the next time it is restarted. If the failed server is restarted while the backup server is recovering transactions, the backup server abandons recovery, does some internal cleanup, and relinquishes control of the recovery service and log files so that the failed server can handle them properly. You can use the Control/JTA Migration Configuration tab to specify which members of the cluster can access the transaction logs of the selected server, and hence which servers can perform a JTA migration if this server fails.

Migrating the Transaction Recovery Service to a backup server imposes certain constraints as well:

• You can migrate the Transaction Recovery Service only from a failed server or a server instance that is not running. You must stop a server instance if you decide to manually migrate the recovery service.
• The backup server processes incomplete transactions only and does not handle heuristic log files.
• Backup servers must have access to the same transaction log files, so they must reside on a shared storage device.

Remember, WebLogic is designed to handle transaction recovery when it's restarted after a system crash. You should consider moving the transaction logs or migrating the recovery service to a backup server only if you are unable to restart the server within a reasonable time period.

6.4.5 Interdomain Transactions

You also can configure WebLogic so that distributed transactions can span multiple domains. Multiple servers across WebLogic domains can participate in interdomain transactions. However, only domains that trust each other can participate in inter-domain transactions.

Resources using the two-phase commit emulation may not participate in an interdomain transaction.

Chapter 17 shows how to enable this trust between two WebLogic domains.