Administration Console Online Help

JTA

[Attributes and Console Screen Reference for JTA]

The following sections explain how to configure the Java Transaction API (JTA) attributes in WebLogic Server:

Configuring Transactions

Configuring Domains for Inter-Domain Transactions

Monitoring Transactions

Transaction Log Files

Handling Heuristic Completions

Moving a Server

Abandoning Transactions

Transaction Recovery After a Server Fails

Overview of Transaction Management

Also see Attributes and Console Screen Reference for JTA for information about JTA pages in the Administration Console.

Configuring Transactions

Configuration settings for JTA (transactions) are applicable at the domain level. This means that configuration attribute settings apply to all servers within a domain. Monitoring and logging tasks for JTA are performed at the server level.

You can configure any transaction attributes before starting the server (static configuration) or, with one exception, while the server is running (dynamic configuration). The TransactionLogFilePrefix attribute must be set before starting the server.

Configuring JTA

In the left pane of the Administration Console, select the domain node (right below the word "console"). The Configuration tab for the domain is displayed by default.

Click the JTA tab.

Enter values in the Timeout Seconds, Abandon Timeout Seconds, Before Completion Iteration Limit, Max Transactions, Max Unique Name Statistics, and Checkpoint Interval Seconds attribute fields or accept the default values as assigned. For details about JTA attributes, see Attributes.

Enable or disable the Forget Heuristics attribute as desired.

Click Apply to save any changes you made.

Ensure that the TransactionLogFilePrefix attribute is set appropriately when you configure the server. For more information about setting the logging attribute, see Transaction Log Files.

Related Information

Transaction attributes at Attributes
Additional Attributes for Managing Transactions
Monitoring Transactions
Transaction Log Files
Configuring JDBC DataSources
Emulating Two-Phase Commit
Configuring JDBC Connection Pools

Additional Attributes for Managing Transactions

By default, if an XA resource that is participating in a global transaction fails to respond to an XA call from the WebLogic Server transaction manager, WebLogic Server flags the resource as unhealthy and unavailable, and blocks any further calls to the resource in an effort to preserve resource threads. The failure can be caused by either an unhealthy transaction or an unhealthy resource—there is no distinction between the two causes. In both cases, the resource is marked as unhealthy.

To mitigate this limitation, WebLogic Server provides the configuration attributes listed in Table 54-1:

Table 54-1 XA Resource Health Monitoring Configuration Attributes

Attribute	MBean	Definition
`EnableResourceHealthMonitoring`	`weblogic.management.configuration.JDBCConnectionPoolMBean`	Enables or disables resource health monitoring for the JDBC connection pool. This attribute only applies to connection pools that use an XA JDBC driver for database connections. It is ignored if a non-XA JDBC driver is used. If set to `true`, resource health monitoring is enabled. If an XA resource fails to respond to an XA call within the period specified in the `MaxXACallMillis` attribute, WebLogic Server marks the connection pool as unhealthy and blocks any further calls to the resource. If set to `false`, the feature is disabled. Default: `true`
`MaxXACallMillis`	`weblogic.management.configuration.JTAMBean`	Sets the maximum allowed duration (in milliseconds) of XA calls to XA resources. This setting applies to the entire domain. Default: `120000`
`MaxResourceUnavailableMillis`	`weblogic.management.configuration.JTAMBean`	The maximum duration (in milliseconds) that an XA resource is marked as unhealthy. After this duration, the XA resource is declared available again, even if the resource is not explicitly re-registered with the transaction manager. This setting applies to the entire domain. Default: `1800000`
`MaxResourceRequestOnServer`	`weblogic.management.configuration.JTAMBean`	Maximum number of concurrent requests to resources allowed for each server in the domain. Default: `50` Minimum: `10` Maximum: `java.lang.Integer.MAX_VALUE`

You set these attributes directly in the config.xml file when the domain is inactive. These attributes are not available in the Administration Console. The following example shows an excerpt of a configuration file with these attributes:

...

   <JTA
    MaxUniqueNameStatistics="5"
    TimeoutSeconds="300"
    RecoveryThresholdMillis="150000"
    MaxResourceUnavailableMillis="900000"
    MaxResourceRequestOnServer="60"
    MaxXACallMillis="180000"
   />

 <JDBCConnectionPool
  Name="XAPool"
  Targets="myserver"
  DriverName="weblogic.qa.tests.transaction.
    testsupport.jdbc.XADataSource"
  InitialCapacity="1"
  MaxCapacity="10"
  CapacityIncrement="2"
  RefreshMinutes="5"
  TestTableName="dual"
  EnableResourceHealthMonitoring="true"
  Properties="user=scott;password=tiger;server=dbserver1"
 />

 <JDBCTxDataSource
  Name="XADataSource"
  Targets="myserver"
  JNDIName="weblogic.jdbc.XADS"
  PoolName="XAPool"
 />

...

Configuring Domains for Inter-Domain Transactions

For a transaction manager to manage distributed transactions, the transaction manager must be able to communicate with all participating servers to prepare and then commit or rollback the transactions. This applies to cases when your WebLogic domain acts as the transaction manager or a transaction participant (resource) in a distributed transaction. The following sections describe how to configure your domain to enable inter-domain transactions.

Limitations for Inter-Domain Transactions

Please note the following limitations for inter-domain transactions:

You cannot manually resolve incomplete transactions on resources from a WebLogic Server domain from WebLogic Server version 7.0 or earlier.
The domains and all participating resources must have unique names. That is, you cannot have a JDBC connection pool, a server, or a domain with the same name as an object in another domain or the domain itself.
Only one data source with both of the following attribute conditions can participate in a global transaction, regardless the domain in which the data source is configured:

Emulate Two-Phase Commit is selected (EnableTwoPhaseCommit=true in config.xml).
The Pool Name attribute in the data source specifies a connection pool that uses a non-XA driver to create database connections.

Note: BEA recommends that you use an XA driver instead of a non-XA driver (with Emulate Two-Phase Commit) in global transactions. There are risks involved with using a non-XA driver in a global transaction. See Limitations and Risks When Using a Non-XA Driver in Global Transactions for more details about the risks.

Inter-Domain Transactions for WebLogic Server Domains

To manage or participate in transactions that span multiple WebLogic Server domains (that is, all participating domains run on WebLogic Server 9.x, 8.x, 7.x, and 6.x domains or a combination of 9.x, 8.x, 7.x and 6.x ), you must enable inter-domain transactions by establishing domain trust and setting the Security Interoperability Mode. For all participating domains:

In all participating WebLogic Server 6.x domains, change the password for the system user to the same value in all participating domains on the Security—>Users tab in the Administration Console. See Changing the System Password.

Establish domain trust by setting a security credential for all domains to the same value in all participating domains. If you have participating 6.x domains, set the security credential for all domains to the same value as the system password in all participating WebLogic Server 6.x domains.

For 7.x domains, see Enabling Trust Between WebLogic Domains in Managing WebLogic Security.
For 8.x domains, see Enabling Trust Between WebLogic Domains in Managing WebLogic Security.
For 9.x domains, see Enable trust between domains in Administration Console Online Help.

For each server participating in the transaction, set the Security Interoperability Mode flag according to Table 54-1 before rebooting. See Using Security Interoperability Mode.

Using Security Interoperability Mode

Security Interoperability Mode enables you to configure compatible communication channels between servers in global transactions.

Configuring Security Interoperability Mode

To configure Security Interoperability Mode, every participating server must set the following flag to the same value:

-Dweblogic.transaction.SecurityInteropMode=value

Where value is:

performance—The transaction coordinator makes calls using anonymous at all times. This implies a security risk since a malicious third party could then try to affect the outcome of transactions using a man-in-the-middle attack.
compatibility—The transaction coordinator makes calls as the kernel identity over an unsecure channel. This is a high security risk because a successful man-in-the-middle attack would allow the attacker to gain administrative control over both domains. This setting should only be used when strong network security is in place.

The default value of this flag is performance.

Determining the Security Interoperability Mode

Use the following table to determine the Security Interoperability Mode settings required when configuring communication channels for inter-domain transactions.

Table 54-1 Security Interoperability Settings for Inter-Domain Transactions

Domain	9.x	8.1 SP5 and higher	7.0 SP7 and higher	8.1 SP4 and lower	7.0 SP6 and lower	6.x
9.x	Set both domains to `default` or `performance`	Set both domains to `performance`	Set both domains to `performance`	Set the 9.x domain to `compatibility`	Set the 9.x domain to `compatibility`	Set the 9.x domain to `compatibility`
8.1 SP5 and higher	Set both domains to `performance`	Set both domains to `performance`	Set both domains to `performance`	Set the 8.1 SP5 and higher domain to `compatibility`	Set the 8.1 SP5 and higher domain to `compatibility`	Set the 8.1 SP5 and higher domain to `compatibility`
7.0 SP7 and higher	Set both domains to `performance`	Set both domains to `performance`	Set both domains to `performance`	Set the 7.0 SP7 and higher domain to `compatibility`	Set the 7.0 SP7 and higher domain to `compatibility`	Set the 7.0 SP7 and higher domain to `compatibility`
8.1 SP4 and lower	Set the 9.x domain to `compatibility`	Set the 8.1 SP5 and higher domain to `compatibility`	Set the 7.0 SP7 and higher domain to `compatibility`	N/A	N/A	N/A
7.0 SP6 and lower	Set the 9.x domain to `compatibility`	Set the 8.1 SP5 and higher domain to `compatibility`	Set the 7.0 SP7 and higher domain to `compatibility`	N/A	N/A	N/A
6.x	Set the 9.x domain to `compatibility`	Set the 8.1 SP5 and higher domain to `compatibility`	Set the 7.0 SP7 and higher domain to `compatibility`	N/A	N/A	N/A

Note: When Security Interoperability Mode is set to performance, you are not required to set domain trust between the domains.

Monitoring Transactions

In the Administration Console, you can monitor transactions for each server in the domain. Transaction statistics are displayed for a specific server, not the entire domain, even though transaction settings apply to the entire domain.

Viewing Transaction Statistics for a Server

To view transaction statistics for a server, follow these steps:

In the Administration Console, click the server node in the left pane and select a server.

In the right pane, select the Monitoring tab and then the JTA tab. Totals for transaction statistics are displayed. For information about the specific information displayed, see Attributes.

Optionally, click the text links at the bottom of the page to view transaction details by server resource or by transaction name, or for all active transactions on the server.

Viewing Transaction Statistics for Named Transactions

To view aggregate statistics about named transactions coordinated by a server, follow these steps:

In the Administration Console, click the server node in the left pane and select a server.

In the right pane, select the Monitoring tab and then the JTA tab.

Click the Monitor All Transactions by Name text link at the bottom of the page. See Attributes for details about the information displayed.

Viewing Transaction Statistics for Server Resources

To view aggregate statistics for each transactional resource accessed on a server, follow these steps:

In the Administration Console, click the server node in the left pane and select a server.

In the right pane, select the Monitoring tab and then the JTA tab.

Click the Monitor All Transactions by Resource text link at the bottom of the page. See Attributes for details about the information displayed.

Viewing Current (Inflight) Transactions for a Server

To view aggregate statistics for each transactional resource accessed on a server, follow these steps:

In the Administration Console, click the Servers node in the left pane and select a server.

In the right pane, select the Monitoring tab and then the JTA tab.

Click the Monitor All Inflight Transactions text link at the bottom of the page. See Attributes for details about the information displayed.

Manually Resolving Current (Inflight) Transactions

In some cases, a transaction may not complete normally due to system or network failures. In such situations there may be locks held on behalf of the pending transaction that are inhibiting the progress of other transactions. After the Abandon Timeout period has elapsed, the WebLogic Server Transaction Manager removes the transaction from its internal data structures and writes a heuristic error to the server log. You can also manually resolve "stuck" transactions.

To manually resolve a transaction, you view current (inflight) transactions for a server from the Server—>Monitoring—>JTA tab (see Viewing Current (Inflight) Transactions for a Server) and then view details about a specific transaction by clicking the transaction id. You can then force a commit or a rollback, depending on the status of the transaction. Table 54-2 lists the transaction states and manual resolution options for each transaction state.

Table 54-2 Transaction Status Definitions and Manual Resolution Options

Status	Definition	Forced Commit?	Forced Rollback?
Active	The application is processing the transaction. The transaction has not yet reached the two-phase commit processing.		Y
Preparing	Corresponds to the interval between when the transaction manager starts the javax.transaction.Synchronization `beforeCompletion()` callback processing, through the first phase of the 2PC protocol, and up to the point when all participants have responded, "ready to commit."		Y
Prepared	The interval between when all participants have responded to prepare up to the commit point (commit log record is flushed to disk) or to the initiation of rollback processing.	Y	Y
Committing	The time from when the commit decision is made up to the point when all participants have been informed of the outcome and the javax.transaction.Synchronization `afterCompletion()` callback processing has completed.	Y
Committed	The transaction has been committed. It is likely that heuristics exists, otherwise the transaction would have been completed and would not have been displayed in the list of current transactions.	Y
Rolling Back	This state occurs from the point when rollback processing is initiated up to the point when all participants have been instructed to rollback and the javax.transaction.Synchronization `afterCompletion()` callback processing has completed.		Y
Rolled Back	The transaction has been rolled back. It is likely that heuristics exists, otherwise the transaction would have been destroyed and would not have been displayed in the list of current transactions.		Y
Marked Roll Back	The transaction has been marked for rollback, perhaps as a result of a setRollbackOnly operation.		Y
No Transaction
Unknown	Current status cannot be determined.	Y	Y

Note that it is possible for a transaction to have different states at different servers. For instance, a transaction may have been committed at the coordinating server, but a remote participant may not have received the commit instruction.

Manual Commit and Rollback Options

To manually resolve a transaction, you can choose from the following options. Options are restricted as described in Table 54-2.

Force Local Commit—Each participating resource that is registered on the server is issued a commit operation for the specified transaction and the transaction will be removed from the local transaction manager's data structures. If the local server is the coordinator for the transaction, the commit record is released.
Force Global Commit—A local commit operation is attempted at each participating server for the specified transaction. If this option is invoked on a non-coordinating server, the coordinator will be contacted to process the operation. The coordinating server will issue asynchronous requests to each participant server.
Force Local Rollback—Each participating resource that is registered on the local server is issued a rollback operation for the specified transaction. The transaction will then be removed from the local transaction manager's data structures.
Force Global Rollback—A local rollback operation is attempted at each participating server for the specified transaction. If this option is invoked on a non-coordinating server, the coordinator will be contacted to process the operation. The coordinating server will issue asynchronous requests to each participant server.

When you select any of these options, WebLogic Server writes entries to the server log.

The difference between the Local and Global options is that Local options act only upon the current server resources (resources on the server that you select in the navigation tree in the left pane of the Administration Console), whereas the Global options attempt to perform the operation across all participating servers. If a Global operation is invoked for a transaction that is not coordinated by the local server then an attempt will be made to contact the coordinator of the transaction in order to perform the operation . If the coordinator cannot be reached, the operation will fail with a javax.transaction.SystemException.

In the case where a transaction may have been committed at the coordinating server (committing status), but a remote participant did not receive the commit instruction (prepared status). You can force a local commit on the remote participant to complete the transaction. In this case it is possible to force a rollback on the remote participant since its transaction state will still be prepared, but the transaction will complete heuristically. If you try to force a global rollback, the operation will fail because the state at the coordinator is committing. You cannot roll back a transaction with the committing status.

To Manually Resolve a Transaction

In the Administration Console, click the Servers node in the left pane and select a server.

In the right pane, select the Monitoring tab and then the JTA tab.

Click the Monitor All Inflight Transactions text link at the bottom of the page.

Click a Transaction Id to view details about the transaction. For information about the transaction statistics shown on the page, see Attributes.

Choose one of the following options: (options are restricted by transaction status; see Table 54-2)

Click Force Local Rollback to roll back the transaction on resources on the current server.
Click Force Global Rollback to roll back the transaction on all resources that participate in the transaction.
Click Force Local Commit to commit the transaction on resources on the current server.
Click Force Global Commit to commit the transaction on all resources that participate in the transaction.

See Manually Resolving Current (Inflight) Transactions for more information about manually resolving transactions.

Transaction Log Files

Each server has a transaction log which stores information about committed transactions coordinated by the server that may not have been completed. WebLogic Server uses the transaction log when recovering from system crashes or network failures. You cannot directly view the transaction log—the file is in a binary format.

The transaction log consists of multiple files. Each file is subject to garbage collection by the transaction manager. That is, when none of the records in a transaction log file are needed, the system deletes the file and returns the disk space to the file system. In addition, the system creates a new transaction log file if the previous log file becomes too large or a checkpoint occurs.

Caution: Do not manually delete transaction log files. Deleting transaction log files may cause inconsistencies in your data.

Transaction log files are uniquely named using a pathname prefix, the server name, a four-digit numeric suffix, and a file extension. The pathname prefix determines the storage location for the file. You can specify a value for the TransactionLogFilePrefix server attribute using the WebLogic Administration Console. The default TransactionLogFilePrefix is the server's root directory (see "A Server's Root Directory" in Configuring and Managing WebLogic Server).

You should set the TransactionLogFilePrefix so that transaction log files are created on a highly available file system, for example, on a RAID device. To take advantage of the migration capability of the Transaction Recovery Service for servers in a cluster, you must store the transaction log in a location that is available to a server and its backup servers, preferably on a dual-ported SCSI disk or on a Storage Area Network (SAN). See Preparing to Migrate the Transaction Recovery Service for more information.

On a UNIX system with a server name of websvr and with the TransactionLogFilePrefix set to /usr7/applog1/, you might see the following log files:

/usr7/applog1/websvr0000.tlog
/usr7/applog1/websvr0001.tlog
/usr7/applog1/websvr0002.tlog

Similarly, on a Windows system with the TransactionLogFilePrefix set to C:\weblogic\logA\, you might see the following log files:

C:\weblogic\logA\websvr0000.tlog
C:\weblogic\logA\websvr0001.tlog
C:\weblogic\logA\websvr0002.tlog

If you notice a large number of transaction log files on your system, this may be an indication of multiple long-running transactions that have not completed. This can be caused by resource manager failures or transactions with especially large timeout values.

If the file system containing the transaction log runs out of space or is inaccessible, commit() throws SystemException, and the transaction manager places a message in the system error log. No transactions are committed until more space is available.

Note: The transaction log buffer is limited to 250 KB. If your application includes very large transactions that require transaction log writes that exceed this value, WebLogic Server will throw an exception. In that case, you must reconfigure your application to work around the buffer size.

When migrating a server to another machine, move the transaction log files as well, keeping all the log files for a server together. See Transaction Recovery After a Server Fails for more information.

Setting the Transaction Log File Location (Prefix)

To set the prefix for the transaction log files, which determines the location of the transaction log files, follow these steps:

In the Administration Console, click the server node in the left pane and select a server.

In the right pane, select the Logging tab and then the JTA tab.

Enter a transaction log file prefix (storage location for transaction logs) then click Apply to save the attribute setting. The new transaction log file prefix takes effect after you restart the server.

The default transaction log file prefix is the server's root directory. You can specify a relative path from the server's root directory or an absolute path to another storage location.

Setting the Transaction Log File Write Policy

You can select a transaction log file write policy to change the way WebLogic Server writes transaction log file entries. You can select either of the following options:

Cache-Flush—(the default) Flushes operating system and on-disk caches after each entry to the transaction log. Transactions cannot commit until the commit record is written to stable storage.
Direct-Write—Forces the operating system to write transaction log entries directly to disk with each write. This option is available on Windows, Solaris and HP-UX platforms.

Warning: On Windows, the Direct-Write transaction log file write policy may leave transaction data in the on-disk cache without immediately writing it to disk. This is not transactionally safe because a power failure can cause loss of on-disk cache data. To prevent cache data loss when using the Direct-Write transaction log file write policy on Windows, disable all write caching for the disk (enabled by default) or use a battery backup for the system. See Disabling the On-Disk Cache For a Disk Drive on Windows 2000 for instructions.

The transaction log file write policy can affect transaction performance. You should test these options with your system to see which performs better. Direct-Write typically performs as well or better than Cache-Flush, depending on operating system and OS parameter settings, and is available on Windows, HP-UX, and Solaris. Windows systems optimize serial writes to disk such that subsequent writes to a file get faster after the first write to the file. Transaction log file entries are written serially, so this could improve performance. On some UNIX systems, the Cache-Flush option will flush all cached disk writes, not only those for the transaction log file, which could degrade transaction performance.

To set the transaction log file write policy, follow these steps:

In the Administration Console, click the server node in the left pane and select a server.

In the right pane, select the Logging tab and then the JTA tab.

Select a Transaction Log File Write Policy: Cache-Flush (the default) or Direct Write.

Click Apply to save the attribute setting. The new transaction log file write policy takes effect after you restart the server.

Heuristic Log Files

When importing transactions from a foreign transaction manager into WebLogic Server, the WebLogic Server transaction manager acts as an XA resource coordinated by the foreign transaction manager. In rare catastrophic situations, such as after the transaction abandon timeout expires or if the XA resources participating in the WebLogic Server imported transaction throw heuristic exceptions, the WebLogic Server transaction manager will make a heuristic decision. That is, the WebLogic Server transaction manager will decide to commit or roll back the transaction without input from the foreign transaction manager. If the WebLogic Server transaction manager makes a heuristic decision, it stores the information of the heuristic decision in the heuristic log files until the foreign transaction manager tells it to forget the transaction.

Heuristic log files are stored with transaction log files and look similar to transaction log files with .heur before the .tlog extension. They use the following format:

<TLOG_file_prefix>\<server_name><4-digit number>.heur.tlog

On a UNIX system with a server name of websvr, you might see the following heuristic log files:

/usr7/applog1/websvr0000.heur.tlog
/usr7/applog1/websvr0001.heur.tlog
/usr7/applog1/websvr0002.heur.tlog

Similarly, on a Windows system, you might see the following heuristic log files:

C:\weblogic\logA\websvr0000.heur.tlog
C:\weblogic\logA\websvr0001.heur.tlog
C:\weblogic\logA\websvr0002.heur.tlog

Handling Heuristic Completions

A heuristic completion (or heuristic decision) occurs when a resource makes a unilateral decision during the completion stage of a distributed transaction to commit or rollback updates. This can leave distributed data in an indeterminate state. Network failures or resource timeouts are possible causes for heuristic completion. In the event of an heuristic completion, one of the following heuristic outcome exceptions may be thrown:

HeuristicRollback—one resource participating in a transaction decided to autonomously rollback its work, even though it agreed to prepare itself and wait for a commit decision. If the Transaction Manager decided to commit the transaction, the resource's heuristic rollback decision was incorrect, and might lead to an inconsistent outcome since other branches of the transaction were committed.
HeuristicCommit—one resource participating in a transaction decided to autonomously commit its work, even though it agreed to prepare itself and wait for a commit decision. If the Transaction Manager decided to rollback the transaction, the resource's heuristic commit decision was incorrect, and might lead to an inconsistent outcome since other branches of the transaction were rolled back.
HeuristicMixed—the Transaction Manager is aware that a transaction resulted in a mixed outcome, where some participating resources committed and some rolled back. The underlying cause was most likely heuristic rollback or heuristic commit decisions made by one or more of the participating resources.
HeuristicHazard—the Transaction Manager is aware that a transaction might have resulted in a mixed outcome, where some participating resources committed and some rolled back. But system or resource failures make it impossible to know for sure whether a Heuristic Mixed outcome definitely occurred. The underlying cause was most likely heuristic rollback or heuristic commit decisions made by one or more of the participating resources.

When an heuristic completion occurs, a message is written to the server log. Refer to your database vendor documentation for instructions on resolving heuristic completions.

Some resource managers save context information for heuristic completions. This information can be helpful in resolving resource manager data inconsistencies. If the ForgetHeuristics attribute is selected (set to true) on the JTA panel of the WebLogic Console, this information is removed after an heuristic completion. When using a resource manager that saves context information, you may want to set the ForgetHeuristics attribute to false.

Moving a Server

A server instance is identified by its URL (IP address or DNS name plus the listening port number). Changing the URL by moving the server to a new machine or changing the Listening Port of a server on the same machine effectively moves the server so the server identity may no longer match the information stored in the transaction logs.

If the new server has the same URL as the old server, the Transaction Recovery Service searches all transaction log files for incomplete transactions and completes them as described in Transaction Recovery Service Actions After a Crash.
If the new server does not have the same URL, any pending transactions stored in the transaction log files are unrecoverable. If you wish, you can delete the transaction log files. This step prevents the Transaction Recovery Service from attempting to resolve these transactions until the value of the AbandonTimeoutSeconds parameter is exceeded. See Abandoning Transactions for more information.
If a server acting as a remote transaction sub-coordinator fails and its URL changes, any ongoing transactions will not complete (commit or rolledback) because the coordinator is unable to communicate with the remote sub-coordinator. The coordinator will attempt the commit or rollback request until AbandonTimeoutSeconds is exceeded. See Abandoning Transactions for more information.

BEA recommends configuring server instances using DNS names rather than IP addresses to promote portability.

Moving a Server to Another Machine

Note: BEA recommends moving the transaction log files to the new machine before starting the server on the new machine. By doing so, you ensure that the transaction recovery process runs properly. When you start WebLogic Server on the new system, the server reads the transaction log files to recover pending transactions, if any.

When an application server is moved to another machine, it must be able to locate the transaction log files on the new disk. If the pathname is different on the new machine, update the TransactionLogFilePrefix attribute with the new path before starting the server. For instructions on how to change the TransactionLogFilePrefix, see Setting the Transaction Log File Location (Prefix).

Abandoning Transactions

You can choose to abandon incomplete transactions after a specified amount of time. In the two-phase commit process for distributed transactions, the transaction manager coordinates all resource managers involved in a transaction. After all resource managers vote to commit or rollback, the transaction manager notifies the resource managers to act—to either commit or rollback changes. During this second phase of the two-phase commit process, the transaction manager will continue to try to complete the transaction until all resource managers indicate that the transaction is completed. Using the AbandonTimeoutSeconds attribute, you can set the maximum time, in seconds, that a transaction manager will persist in attempting to complete a transaction during the second phase of the commit protocol. The default value is 86400 seconds, or 24 hours. After the abandon transaction timer expires, no further attempt is made to resolve the transaction with any resources that are unavailable or unable to acknowledge the transaction outcome. If the transaction is in a prepared state before being abandoned, the transaction manager will roll back the transaction to release any locks held on behalf of the abandoned transaction and will write an heuristic error to the server log.

Related Information

For instructions on how to set the AbandonTimeoutSeconds attribute, see Configuring Transactions.
For information about manually resolving a transaction, see Manually Resolving Current (Inflight) Transactions.
For more information about the two-phase commit process, see Distributed Transactions and the Two-Phase Commit Protocol in Programming WebLogic JTA.

Transaction Recovery After a Server Fails

The WebLogic Server transaction manager is designed to recover from system crashes with minimal user intervention. The transaction manager makes every effort to resolve transaction branches that are prepared by resource managers with a commit or roll back, even after multiple crashes or crashes during recovery.

To facilitate recovery after a crash, WebLogic Server provides the Transaction Recovery Service, which automatically attempts to recover transactions on system startup. The Transaction Recovery Service owns the transaction log for a server. On startup, the Transaction Recovery Service parses all log files for incomplete transactions and completes them as described in Transaction Recovery Service Actions After a Crash.

Because the Transaction Recovery Service is designed to gracefully handle transaction recovery after a crash, BEA recommends that you attempt to restart a crashed server and allow the Transaction Recovery Service to handle incomplete transactions.

If a server crashes and you do not expect to be able to restart it within a reasonable period of time, you may need to take action. Procedures for recovering transactions after a server failure differ based on your WebLogic Server environment. For a non-clustered server, you can manually move the server (with transaction log files) to another system (machine) to recover transactions. See Recovering Transactions for a Failed Non-Clustered Server for more information. For a server in a cluster, you can manually migrate the Transaction Recovery Service to another server in the same cluster. Migrating the Transaction Recovery Service involves selecting a server with access to the transaction logs to recover transactions, and then migrating the service using the Administration Console or the WebLogic command line interface.

Note: For non-clustered servers, you can only move the entire server to a new system. For clustered servers, you can temporarily migrate the Transaction Recovery Service.

For more information about migrating the Transaction Recovery Service, see Recovering Transactions for a Failed Clustered Server. For more information about clusters, see Using WebLogic Server Clusters.

Transaction Recovery Service Actions After a Crash

When you restart a server after a crash or when you migrate the Transaction Recovery Service to another (backup) server, the Transaction Recovery Service does the following:

Complete transactions ready for second phase of two-phase commit

For transactions for which a commit decision has been made but the second phase of the two-phase commit process has not completed (transactions recorded in the transaction log), the Transaction Recovery Service completes the commit process.

Resolve prepared transactions

For transactions that the transaction manager has prepared with a resource manager (transactions in phase one of the two-phase commit process), the Transaction Recovery Service must call XAResource.recover() during crash recovery for each resource manager and eventually resolve (by calling the commit(), rollback(), or forget() method) all transaction IDs returned by recover().

Report heuristic completions

If a resource manager reports a heuristic exception, the Transaction Recovery Service records the heuristic exception in the server log and calls forget() if the Forget Heuristics configuration attribute is enabled. If the Forget Heuristics configuration attribute is not enabled, refer to your database vendor's documentation for information about resolving heuristic completions. See Handling Heuristic Completions for more information.

The Transaction Recovery Service provides the following benefits:

Maintains consistency across resources

The Transaction Recovery Service handles transaction recovery in a consistent, predictable manner: For a transaction for which a commit decision has been made but is not yet committed before a crash, and XAResource.recover() returns the transaction ID, the Transaction Recovery Service consistently calls XAResource.commit(); for a transaction for which a commit decision has not been made before a crash, and XAResource.recover() returns its transaction ID, the Transaction Recovery Service consistently calls XAResource.rollback(). With consistent, predictable transaction recovery, a transaction manager crash by itself cannot cause a mixed heuristic completion where some branches are committed and some are rolled back.

Persists in achieving transaction resolution

If a resource manager crashes, the Transaction Recovery Service must eventually call commit() or rollback() for each prepared transaction until it gets a successful return from commit() or rollback(). The attempts to resolve the transaction can be limited by setting the AbandonTimeoutSeconds configuration attribute. See Abandoning Transactions for more information.

Recovering Transactions for a Failed Non-Clustered Server

To recover transactions for a failed server, follow these steps:

Move (or make available) all transaction log files from the failed server to a new server.

Set the TransactionLogFilePrefix attribute with the path to the transaction log files. For instructions, see Setting the Transaction Log File Location (Prefix).

Start the new server. The Transaction Recovery Service searches all transaction log files for incomplete transactions and completes them as described in Transaction Recovery Service Actions After a Crash.

When moving transaction logs after a server failure, make all transaction log files available on the new machine before starting the server there. You can accomplish this by storing transaction log files on a dual-ported disk available to both machines. As in the case of a planned migration, update the TransactionLogFilePrefix attribute with the new path before starting the server if the pathname is different on the new machine. Ensure that all transaction log files are available on the new machine before the server is started there. Otherwise, transactions in the process of being committed at the time of a crash might not be resolved correctly, resulting in application data inconsistencies.

Note: The Transaction Recovery Service is designed to gracefully handle transaction recovery after a crash. BEA recommends that you attempt to restart a crashed server and allow the Transaction Recovery Service to handle incomplete transactions, rather than move the server to a new machine.

Recovering Transactions for a Failed Clustered Server

When a clustered server crashes, you can manually migrate the Transaction Recovery Service from the crashed server to another server in the same cluster using the Administration Console or the command line interface. The following events occur:

The Transaction Recovery Service on the backup server takes ownership of the transaction log from the crashed server.

The Transaction Recovery Service searches all transaction log files from the failed server for incomplete transactions and completes them as described in Transaction Recovery Service Actions After a Crash.

If the Transaction Recovery Service on the backup server successfully completes all incomplete transactions from the failed server, the server releases ownership of the Transaction Recovery Service (including transaction log files) for the failed server so the failed server can reclaim it upon restart.

For instructions to migrate the Transaction Recovery Service using the Administration Console, see Migrating the Transaction Recovery Service to a Server in the Same Cluster.

A server can perform transaction recovery for more than one failed server. While recovering transactions for other servers, the backup server continues to process and recover its own transactions. If the backup server fails during recovery, you can migrate the Transaction Recovery Service to yet another server, which will continue the transaction recovery. You can also manually migrate the Transaction Recovery Service back to the original failed server using the Administration Console or the command line interface. See Manually Migrating the Transaction Recovery Service Back to the Original Server for more information.

When a backup server completes transaction recovery for a server, it releases ownership of the Transaction Recovery Service (and transaction logs) for the failed server. When you restart a failed server, it attempts to reclaim ownership of its Transaction Recovery Service. If a backup server is in the process of recovering transactions when you restart the failed server, the backup server stops recovering transactions, performs some internal cleanup, and releases ownership of the Transaction Recovery service so the failed server can reclaim it and start properly. The failed server will then complete its own transaction recovery.

If a backup server still owns the Transaction Recovery Service for a failed server and the backup server is inactive when you attempt to restart the failed server, the failed server will not start because the backup server cannot release ownership of the Transaction Recovery Service. This is also true if the fail back mechanism fails or if the backup server cannot communicate with the Administration Server. You can manually migrate the Transaction Recovery using the Administration Console or the command line interface.

Limitations of Migrating the Transaction Recovery Service

When migrating the Transaction Recovery Service, the following limitations apply:

You cannot migrate the Transaction Recovery Service to a backup server from a server that is running. You must stop the server before migrating the Transactions Recovery Service.
The backup server does not accept new transaction work for the failed server. It only processes incomplete transactions.
The backup server does not process heuristic log files.
The backup server only processes log records written by WebLogic Server. It does not process log records written by gateway implementations, including WebLogic Tuxedo Connector.

Preparing to Migrate the Transaction Recovery Service

To migrate the Transaction Recovery Service from a failed server in a cluster to another server (backup server) in the same cluster, the backup server must have access to the transaction log files from the failed server. Therefore, you must store transaction log files on persistent storage available to both (or more) servers. BEA recommends that you store transaction log files on a Storage Area Network (SAN) device or a dual-ported disk. Do not use an NFS file system to store transaction log files. Because of the caching scheme in NFS, transaction log files on disk may not always be current. Using transaction log files stored on an NFS device for recovery may cause data corruption.

When migrating the Transaction Recovery Service from a server, you must stop the failing or failed server before actually migrating the Transaction Recovery Service. If the original server is still running, you cannot migrate the Transaction Recovery Service from it.

For detailed instructions to migrate the Transaction Recovery Service, see Migrating the Transaction Recovery Service to a Server in the Same Cluster in the Administration Console Online Help.

Migrating the Transaction Recovery Service to a Server in the Same Cluster

To migrate the Transaction Recovery Service from a failed server in a cluster, follow these steps:

Make sure the failed or failing server is not running:

Click the Servers node in the left pane in the Administration Console to expand it.

Right-click the failed server and select Start/Stop this server.

In the right pane of the Administration Console, click Graceful shutdown of this server. If that action fails, retry these steps and select Force shutdown of this server.

In the left pane in the Administration Console, select the failed server from which you want to migrate the Transaction Recovery Service. A dialog displays in the right pane with tabs for configuring the server.

Select the Control tab, then select the JTA Migration tab. The JTA Migration tab includes the following:

Cluster—The name of the cluster to which the server belongs.
Current Server—The server that currently owns the Transaction Recovery Service for the selected server. (The selected server name is displayed at the top of the page.)
Destination Server—A list of servers in the cluster. This list shows all servers in the cluster or a list of servers that you specify. See Constraining the Servers to Which the Transaction Recovery Service can Migrate.

In Destination Server, select the server that you want to recover transactions for the failed server.

Click Migrate and follow any additional instructions in the right pane.

Constraining the Servers to Which the Transaction Recovery Service can Migrate

You may want to limit the choices of the servers to use as a Transaction Recovery Service backup for a server in a cluster. For example, all servers in your cluster may not have access to the transaction log files for a server. You can limit the list of destination servers available on the Server—>Control—>Migrate JTA tab in the Administration Console by following these instructions:

In the Administration Console, click the Servers node in the left pane to expand it.

Select the server for which you want to specify Transaction Recovery Service backup servers. A dialog displays in the right pane with tabs for configuring the server.

Select the Control tab, then select the JTA Migration Config tab.

In the Available list of Constrained Candidate Servers, select the servers you want to use as a Transaction Recovery Service backup and click the right arrow to move the servers to the Chosen list.

Note: You must include the original server in the list of chosen servers so that you can manually migrate the Transaction Recovery Service back to the original server, if need be. The Administration Console enforces this rule.

Click Apply to save your changes.

Viewing Current Owner of the Transaction Recovery Service

When you migrate the Transaction Recovery Service to another server in the cluster, the backup server takes ownership of the Transaction Recovery Service until it completes all incomplete transactions. After which, it releases ownership of the Transaction Recovery Service and the original server can reclaim it. You can see the current owner on the Server—>Control—>Migrate JTA tab in the Administration Console. Follow these instructions:

In the Administration Console, click the Servers node in the left pane to expand it.

Select the server for which you want to see the owner of the Transaction Recovery Service. A dialog displays in the right pane with tabs for configuring the server.

Select the Control tab. If necessary, select the JTA Migration tab. On the JTA Migration tab, the Current Server indicates the current owner of the Transaction Recovery Service.

Manually Migrating the Transaction Recovery Service Back to the Original Server

After completing transaction recovery for a failed server, a backup server releases ownership of the Transaction Recovery Service so that the original server can reclaim it when the server is restarted. If the backup server stops (crashes) for any reason before it completes transaction recovery, the original server cannot reclaim ownership of the Transaction Recovery Service and will not start. You can manually migrate the Transaction Recovery Service back to the original server by selecting the original server as the Destination Server. The backup server must not be running when you migrate the service back to the original server. Follow the instructions below.

Note: Please note the following:

A backup server will continue to recover incomplete transactions after you restart it. You will not need to manually migrate the Transaction Recovery Service back to the original server if the backup server completes the transaction recovery.
If you restart the original server while the backup server is recovering transactions, the backup server will gracefully release ownership of the Transaction Recovery Service. You do not need to stop the backup server. See Recovering Transactions for a Failed Clustered Server.

Make sure the backup server is not running. To do this, click the Servers node in the left pane in the Administration Console to expand it, then right-click the backup server and select Stop this server. Follow any additional instructions.

In the Administration Console, click the Servers node in the left pane to expand it.

Select the failed server that you want to migrate the Transaction Recovery Service back to. A dialog displays in the right pane with tabs for configuring the server.

Select the Control tab. If necessary, select the JTA Migration tab.

In Destination Server, select the original server.

Click Migrate and follow any additional instructions in the right pane.

Overview of Transaction Management

You use the Administration Console to access tools for configuring the WebLogic Server features, including the Java Transaction API (JTA). The transaction configuration process involves specifying values for attributes. These attributes define various aspects of the transaction environment:

Transaction timeouts and limits
Transaction Manager behavior
Transaction log file prefix

Settings you make in the Administration Console, including configuration settings for JTA, are persisted in the config.xml file for the domain. For information about entries in this file, see the following sections of the Configuration Reference Guide:

Before configuring your transaction environment, you should be familiar with the J2EE components that can participate in transactions, such as EJBs, JDBC, and JMS.

EJBs (Enterprise JavaBeans) use JTA for transaction support. Several deployment descriptors relate to transaction handling. For more information about programming with EJBs and JTA, see Programming WebLogic Enterprise JavaBeans.
JDBC (Java Database Connectivity) provides standard interfaces for accessing relational database systems from Java. JTA provides transaction support on connections retrieved using a JDBC driver and transaction data source. For more information about programming with JDBC and JTA, see Programming WebLogic JDBC.
JMS (Java Messaging Service) uses JTA to support transactions across multiple data resources. WebLogic JMS is an XA-compliant resource manager. For more information about programming with JMS and JTA, see Programming WebLogic JMS.