Programming WebLogic JTA

Configuring Transactions

The following sections provide configuration tasks related to transactions:

Overview of Transaction Configuration

The Administration Console provides the interface used to configure features of WebLogic Server, including WebLogic JTA. The configuration process involves specifying values for attributes. These attributes define the transaction environment, including the following:

Transaction timeouts and limits
Transaction manager behavior

You should also be familiar with the administration of J2EE components that can participate in transactions, such as EJBs, JDBC data sources, and JMS.

Note: You can also use the WebLogic Scripting Tool (WLST; see WebLogic Scripting Tool) or JMX (see Developing Custom Management Utilities with JMX) to configure transaction-related settings.

Configuring JTA

Once you configure WebLogic JTA and any transaction participants, the system can manage transactions using the JTA API and the WebLogic JTA extensions. Note the following:

Configuration settings for JTA (transactions) are applicable at the domain level. This means that configuration attribute settings apply to all servers within a domain. See "Configure JTA" in the Administration Console Online Help.
Monitoring tasks for JTA are performed at the server level. See "Monitor JTA" in the Administration Console Online Help.
Configuration settings for participating resources (such as JDBC data sources) are per configured object. The settings apply to all instances of a particular object. See "Transaction Options" in Configuring and Managing WebLogic JDBC and "Configure global transaction options for a JDBC data source" in the Administration Console Online Help.

Unregister Resource Grace Period

If you have resources that you may occasionally undeploy and redeploy such as a JDBC data source module packaged with an application, you can minimize the risk of abandoned transactions because of an unregistered resource by setting the Unregistered Resource Grace Period for the domain. The grace period is the number of seconds that the transaction manager waits for transactions to complete before unregistering a resource.

During the specified grace period, the unregisterResource call will block until the call can return, and no new transactions are started for the associated resource. If the number of outstanding transactions for the resource goes to 0, the unregisterResource call returns immediately.

At the end of the grace period, if there are still outstanding transactions associated with the resource, the unregisterResource call returns and a log message is written on the server on which the resource was previously registered.

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 3-1:

Table 3-1 XA Resource Health Monitoring Configuration Attributes

Attribute	MBean	Definition
`ResourceHealthMonitoring`	weblogic.managment.configuration.JDBCXAParamsBean	ResourcehealthMonitoring attribute in JDBCXAParamsBean MBean Enables or disables resource health monitoring for the JDBC data source. This attribute only applies to data sources 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 data source as unhealthy and blocks any further calls to the resource. If set to `false`, the feature is disabled. Default: `true` You can set the Resource Health Monitoring attribute for a JDBC data source on the JDBC Data Source: Configuration: Connection Pool tab in the Administration Console.
`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`

Except for Resource Health Monitoring for a JDBC data source, 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"
   />

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 resources 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. To learn more about interoperability between WebLogic domains, see "Enabling Trust Between WebLogic Domains" in Securing WebLogic Server.

The following sections provide information on how to configure domains for 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 data source, 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 of the domain in which the data source is configured:

Logging Last Resource or Emulate Two-Phase Commit is selected.
The data source 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 Emulating Two-Phase Commit Using a Non-XA Driver in Configuring and Managing WebLogic JDBC.

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 3-2 before rebooting. See Setting Security Interoperability Mode.

Setting Security Interoperability Mode

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

Configuring Security Interoperability Mode

Every participating server must set the Security Interoperability Mode parameter to the same value:

Valid values are:

default—The transaction coordinator makes calls using the kernel identity over an admin channel if it is enabled, and anonymous otherwise. Man-in-the-middle attacks are possible if the admin channel is not enabled.
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.

To configure Security Interoperability Mode for participating servers, see:

For servers in Weblogic Server 9.x domains, see Configure the security mode for XA transactions.
For servers in WebLogic Server 8.x domains, see Using Security Interoperability Mode.
For servers in WebLogic Server 7.x domains, see Using Security Interoperability Mode.

Determining the Security Interoperability Mode Setting

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

Table 3-2 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 either `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.

JMX Incompatibility

There is a known issue which may occur when performing inter-domain transactions due incompatibilities between JMX 1.0 and JMX 1.2. To correct this incompatibility, use the JVM flag -Djmx.serial.form=1.0 as described in JMX 1.2 Implementation in Upgrading WebLogic Application Environments.

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 records are in a binary format and are stored in the default persistent store for the server.

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 Setting the Path for the Default Persistent Store for more information.

If the file system on which the default store saves transaction log records 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.

Setting the Path for the Default Persistent Store

Each server instance, including the administration server, has a default persistent store, which is a file-based store that is available to subsystems that do not require explicit selection of a particular store and function best by using the system's default storage mechanism. The transaction manager uses the default persistent store to store transaction log records. In many cases, the default persistent store requires no configuration. However, to enable migration of the Transaction Recovery Service, you must configure the default persistent store so that it stores its data files on a persistent storage solution that is available to other servers in the cluster if the original server fails.

See "Configure the default persistent store for Transaction Recovery Service migration" in the Administration Console Online Help for instructions.

Setting the Default Persistent Store Synchronous Write Policy

WebLogic Server uses the default persistent store to store transaction log records. You can select a write policy for the default store to change the way WebLogic Server writes records to disk. You can select one of the following options:

Cache-Flush - Flushes operating system and on-disk caches after each entry to the store. Transactions cannot commit until the commit record is written to stable storage.
Disabled - Transactions are complete as soon as their writes are cached in memory, instead of waiting for the writes to successfully reach the disk. This policy is the fastest, but is not transactionally safe. Power outages or operating system failures can cause lost or duplicate entries.

Warning: The Disabled synchronous write policy is not transactionally safe. Do not select this option if your applications use global transactions.

Direct-Write - Forces the operating system to write directly to disk with each write. This option is available on Windows, Solaris and HP-UX platforms.

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 (which is enabled by default) or use a battery backup for the system.

See "Configure the default persistent store for Transaction Recovery Service migration" in the Administration Console Online Help for instructions.