3 Configuring Transactions

Learn about basic configuration tasks related to transactions. These tasks include using JTA, configuring secure transaction communication, using transaction log (TLog) files, and using read-only, one-phase commit optimizations.

This chapter includes the following sections:

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 Java EE components that participate in transactions, such as EJBs, JDBC data sources, and JMS.

Note:

You can also use the WebLogic Scripting Tool (WLST; see Understanding the WebLogic Scripting Tool) or JMX (see Developing Custom Management Utilities Using JMX for Oracle WebLogic Server) to configure transaction-related settings.

Configuring JTA

You can configure JTA settings at domain or cluster level. Once you configure WebLogic JTA and any transaction participants, the system manages transactions using the JTA API and the WebLogic JTA extensions.

Note the following:

  • Configuration settings for JTA (transactions) are applicable at the domain and cluster level:

    • At the domain level, attribute settings apply to all servers within a domain. These settings are superseded by any settings at the cluster level. See Table 3-1

    • At the cluster level, attribute settings apply to a cluster within a domain. These settings supersede any settings at the domain level. See Cluster: Configuration: JTA in the Oracle WebLogic Server Administration Console Online Help.

  • Monitoring tasks for JTA are performed at the server level. See Monitor JTA in the Oracle WebLogic Server 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 JDBC Data Source Transaction Options in Administering JDBC Data Sources for Oracle WebLogic Server and Configure global transaction options for a JDBC data source in the Oracle WebLogic Server Administration Console Online Help.

Table 3-1 Configuration Options for JTA (transactions)

Name Description
Timeout Seconds Specifies the maximum amount of time, in seconds, an active transaction is allowed to be in the first phase of a two-phase commit transaction. If the specified amount of time expires, the transaction is automatically rolled back.

MBean Attribute:JTAMBean.TimeoutSeconds

Minimum value: 1

Maximum value: 2147483647

Note:

The DBMS has its own DISTRIBUTED_LOCK_TIMEOUT, with a default of 60 seconds, the maximum period it will allow an XA transaction to hold DBMS locks. It is important that this DBMS option be tuned to accommodate the longest expected WebLogic transaction. If this DBMS timeout is lower than the WebLogic JTA/tx timeout, the DBMS may roll back and ‘forget’ an on-going transaction out from under WebLogic. This will cause ‘NOTA’ (transaction ID unknown) errors in WebLogic when WebLogic subsequently asks the DBMS to do something more on behalf of the transaction, and the DBMS now knows nothing about it.
Abandon Timeout Seconds

Specifies the maximum amount of time, in seconds, a transaction manager persists in attempting to complete the second phase of a two-phase commit transaction.

During the second phase of a two-phase commit transaction, the transaction manager continues to try to complete the transaction until all resource managers indicate that the transaction is completed. After the abandon transaction timer expires, no further attempt is made to resolve the transaction. If the transaction is in a prepared state before being abandoned, the transaction manager rolls back the transaction to release any locks held on behalf of the abandoned transaction.

MBean Attribute: JTAMBean.AbandonTimeoutSeconds

Minimum value: 1

Maximum value: 2147483647

Before Completion Iteration Limit

The maximum number of cycles that the transaction manager performs the beforeCompletion synchronization callback for this WebLogic Server domain.

Nothing prevents a Synchronization object from registering another during beforeCompletion, even those whose beforeCompletions have already been called. For example, an EJB can call another in its ejbStore() method. To accommodate this, the transaction manager calls all Synchronization objects, then repeats the cycle if new ones have been registered. This count sets a limit to the number of cycles that synchronization occurs.

MBean Attribute: JTAMBean.BeforeCompletionIterationLimit

Minimum value: 1

Max Transactions

The maximum number of simultaneous in-progress transactions allowed on a server in this WebLogic Server domain.

MBean Attribute: JTAMBean.MaxTransactions

Minimum value: 1

Maximum value: 2147483647

Max Unique Name Statistics

The maximum number of unique transaction names for which statistics are maintained.

The first 1001 unique transaction names are maintained as their own transaction name and stored in each statistic. After the 1001st transaction name is reached, the transaction name is stored as weblogic.transaction.statistics.namedOverflow, and the transaction statistic is also merged and maintained in weblogic.transaction.statistics.namedOverflow.

A transaction name typically represents a category of business transactions, such as "funds-transfer."

MBean Attribute: JTAMBean.MaxUniqueNameStatistics

Minimum value: 0

Maximum value: 2147483647

Checkpoint Interval Seconds The interval at which the transaction manager creates a new transaction log file and checks all old transaction log files to see if they are ready to be deleted.

MBean Attribute: JTAMBean.CheckpointIntervalSeconds

Minimum value: 10

Maximum value: 1800

Write recovery logs when determiners configured

Indicates two-phase transaction recovery logs are written even if one or more determiners are configured.

MBean Attribute: JTAMBean.TLOGWriteWhenDeterminerExistsEnabled

Determiners

Select a transaction resource (determiner) from the list of resources. For JMS, select WebLogic JMS as the determiner. When a determiner is configured, the determiner's in-doubt transaction records are used during transaction recovery.

MBean Attribute: JTAMBean.Determiners

Forget Heuristics

Specifies whether the transaction manager automatically performs an XA Resource forget operation for heuristic transaction completions.

When enabled, the transaction manager automatically performs an XA Resource forget() operation for all resources as soon as the transaction learns of a heuristic outcome. Disable this feature only if you know what to do with the resource when it reports a heuristic decision.

MBean Attribute: JTAMBean.ForgetHeuristics

Unregister Resource Grace Period

The amount of time, in seconds, a transaction manager waits for transactions involving the resource to complete before unregistering a resource. This grace period helps minimize the risk of abandoned transactions because of an unregistered resource, such as a JDBC data source module packaged with an application.

During the specified grace period, the unregisterResource call blocks until the call returns 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 outstanding transactions are associated with the resource, the unregisterResource call returns and a log message is written to the server on which the resource was previously registered.

MBean Attribute: JTAMBean.UnregisterResourceGracePeriod

Minimum value: 0

Maximum value: 2147483647

Execute XA Calls In Parallel

Indicates that XA calls are executed in parallel if there are available threads.

MBean Attribute: JTAMBean.ParallelXAEnabled

Enable Two Phase Commit

Indicates that the two-phase commit protocol is used to coordinate transactions across two or more resource managers.

If not selected:

  • Two-phase commit is disabled and any attempt to use two-phase commit results in a RollbackException being thrown.

  • All transaction logging is disabled, including checkpoint records.

MBean Attribute: JTAMBean.TwoPhaseEnabled

Changes take effect after you redeploy the module or restart the server

Enable Tightly Coupled Transactions

Indicates tight coupling of transaction branches that span different transaction manager systems.

When enabled, WebLogic uses the transaction identifier of a transaction imported by the InterposedTransactionManager for XA calls rather than an internally mapped Xid. This applies to inter-domain WebLogic transactions and transactions imported from Tuxedo. This allows for tight coupling of transaction branches for transactions that span across different transaction manager systems.

If a transaction between WebLogic and Tuxedo resources uses a GridLink Data Source with GridLink Affinity enabled, the XA Affinity context is automatically used for the transaction.

MBean Attribute: JTAMBean.TightlyCoupledTransactionsEnabled

Enable Cluster-Wide Recovery

Indicates that cluster-wide recovery is used for distributed transactions.

When enabled, recovery operations for a distributed transaction are applied to all the servers of the cluster hosting a InterposedTransactionManager rather than just the server hosting the InterposedTransactionManager.

MBean Attribute: JTAMBean.ClusterwideRecoveryEnabled

For advanced configuration options, see Advanced Configuration Options in the Oracle WebLogic Server 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, 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 blocks until the call returns, 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 following configuration attributes:

  • Maximum Duration of XA Calls—Sets the maximum allowed duration (in milliseconds) of XA calls to XA resources.

  • Maximum Duration XA Resource Unavailable—The maximum duration (in milliseconds) that an XA resource is marked as unhealthy.

  • Maximum Resource Requests on a Server—Maximum number of concurrent requests to resources allowed for each server in the domain.

These attributes are configurable at the domain and the cluster level. See Cluster: Configuration: JTA and Domains: Configuration: JTA in the Oracle WebLogic Server Administration Console Online Help.

XA Transaction Cluster Affinity

XA transaction affinity allows server instances that are participating in a global transactions to service related requests rather than load-balancing these requests to other member servers. When Enable Transaction Affinity=true, cluster throughput can be increased by:

  • Reducing inter-server transaction coordination traffic

  • Improving resource utilization, such as reducing JDBC connections

  • Simplifying asynchronous processing of transactions

If the cluster does not have a member participating in the transaction, the request is load balanced to an available cluster member. If the selected cluster member fails, the JTA Transaction Recovery Service can be migrated using the Roadmap for Configuring Automatic Migration of the JTA Transaction Recovery Service in Administering Clusters for Oracle WebLogic Server.

See Configure clusters in Oracle WebLogic Server Administration Console Online Help. You can also enable XA transaction affinity on the command line using -Dweblogic.cluster.TxnAffinityEnabled=true.

Using Transaction Log Files to Recover Transactions

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 (TLogs) 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 either the default persistent store or a JDBC TLog store for the server.

Using the Default Persistent Store

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.

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 Oracle WebLogic Server 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. Select a write policy for the default store to change the way WebLogic Server writes records to disk, see Guidelines for Configuring a Synchronous Write Policy.

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

Using a JDBC TLOG Store

You can configure a JDBC TLog store to persist transaction logs to a database, which allows you to leverage replication and HA characteristics of the underlying database, simplify disaster recovery, and improve Transaction Recovery service migration. See Administering the Persistent Store.

Last Logging Resource

LLR is a performance enhancement option that enables one non-XA resource to participate in a global transaction with the same ACID guarantee as XA. See Logging Last Resource Transaction Optimization.

XA Transactions without Transaction TLog Write

As described in Using Transaction Log Files to Recover Transactions, TLogs are used to resolve in-doubt transactions. However, there can be a significant cost associated with creating and maintaining these files, such as read/write costs, network calls between resource managers, and HA storage.

Note:

Server and resource checkpoints in a XA transaction are still written to the TLog. These checkpoints are written when the resources are first involved in a global transaction, updated only if there are changes to the transaction participants, and purged only if they are no longer used or become unavailable.

The following section provides information on how to improve XA transaction performance by eliminating TLogs when XA transactions span a single transaction manager (TM):

What is a Determiner Resource?

Determiners are JDBC XA and JMS XA resources whose in-doubt transaction records are used during transaction recovery when a TLog is not present.

Best Practices When Using Determiner Resources

The following section provides information on best practices for using determiner resources in global transactions:

  • The Determiner resource must be targeted to the server where the global transaction will execute. In a clustered environment, the determiner resource should target a cluster to ensure high availability during a service or server migration.

  • To support Transaction Recovery Service migration:

    • For JDBC XA resources, target the determiner DataSource to the cluster.

    • For JMS XA resources, target the JMS service to the same migratable target used by the custom persistent store. See Custom Store Availability for JMS Services in Administering Clusters for Oracle WebLogic Server.

  • Configure the minimum number of determiner resources possible. This reduces the number of resources that must be available for recovery.

Configuring XA Transactions without TLogs

The following sections provide information on how to configure, update, and remove determiners in your environment.

How to Configure a Determiner

To configure a determiner:

  1. Ensure that all XA transactions are complete on the server or servers that will host the JDBC XA or JMS XA resources you want to configure as a determiner resource.
  2. Stop any server or cluster hosting JDBC XA resources to be used as a determiner.
  3. If you have not already done so, in the Change Center of the WebLogic Server Administration Console, click Lock & Edit (see Use the Change Center in Oracle WebLogic Server Administration Console Online Help).
  4. You can configure a determiner for a domain or for a cluster.
    • For a domain: In the left pane of the WebLogic Server Administration Console, select the domain name at the top of the tree.

    • For a cluster: In the left pane of the WebLogic Server Administration Console, expand Environment and select Clusters. Then in the Summary of Clusters table, select the cluster you want to configure.

  5. In the Configuration: JTA tab, specify list of one or more determiners separated by line breaks in the Determiner attribute.

    JDBCA XA resource determiner names have the pattern <XAdsname>+"_"+<dname> , where XAdsname is the name of the data source and dname is the name of the domain. For example:

    myDS1_myDomain
    myDS2_myDomain
    

    JMS XA resource determiner names have the pattern "WLStore_"+<dname>+"_"+<JMSXAResource>, where JMSXAResource is the name of the JMS persistent store and dname is the name of the domain. If no persistent store is configured, default store is used and the naming convention is "WLStore_"+<dname>"+"_"+"_"+"WLS_"+<server name>, where server name is the name of the server and dname is the name of the domain. For example:

    WLStore_myDomain_myStore1
    WLStore_myDomain_myStore2
    WLStore_XADomain__WLS_myServer
    

    Note: Target the determiner resource to ensure high availability, see Best Practices When Using Determiner Resources.

  6. Optionally, enable the Write recovery logs when determiners configured attribute to write transaction recovery logs even if one or more determiners are configured.
  7. Click Save.
  8. To activate these changes, in the Change Center of the WebLogic Server Administration Console, click Activate Changes.

    Not all changes take effect immediately—some require a restart (see Use the Change Centerin Oracle WebLogic Server Administration Console Online Help.

  9. Restart any server or cluster hosting a configured determiner resource.

Your environment is now ready to resume transaction processing.

How to Remove a Determiner

To remove a determiner:

  1. Ensure that all XA transactions are complete on the server or servers that host the JDBC XA or JMS XA resources you want to remove as a determiner resource.
  2. Stop any server or cluster hosting determiner resources to be removed.
  3. If you have not already done so, in the Change Center of the WebLogic Server Administration Console, click Lock & Edit (see Use the Change Center in Oracle WebLogic Server Administration Console Online Help).
  4. You can remove a determiner for a domain or for a cluster.
    • For a domain: In the left pane of the WebLogic Server Administration Console, select the domain name at the top of the tree.

    • For a cluster: In the left pane of the WebLogic Server Administration Console, expand Environment and select Clusters. Then in the Summary of Clusters table, select the cluster you want to configure.

  5. In the Configuration: JTA tab, remove one or more determiners from the list specified in the Determiner attribute.
  6. Click Save.
  7. To activate these changes, in the Change Center of the WebLogic Server Administration Console, click Activate Changes.

    Not all changes take effect immediately—some require a restart (see Use the Change Center in Oracle WebLogic Server Administration Console Online Help.

  8. Restart any server or cluster shut down in Step 2.

Your environment is now ready to resume transaction processing.

Limitations and Considerations When Configuring Transactions without TLogs

The following section provides important information on limitations and considerations when configuring transactions without TLogs:

  • Configuring Transactions without TLogs is not supported when:

    • More than one TM participates in global transactions

    • Global transactions include JTS or LLR resources

    • Participating transactions include WS-AT, OTS, WLS/Tuxedo transactions, and transactions that include foreign transaction managers

    • Only read operations are executed in the determiner resource as part of the global transaction work.

    • parallel-xa-enabled is set to false (default value is true).

  • Server and resource checkpoints are still written to the TLOG. Checkpoints are written when the resources are first involved in a global transaction, updated only if there are changes to the transaction participants, and purged only if they are no longer used or become unavailable. Because checkpoints are created early in the transaction, as long as there are no changes to the participants in the global transactions, there is little danger of a checkpoint being out of sync during transaction service migration or transaction recovery spanning multiple sites or data centers.

  • Abandon Timeout Seconds is not supported. Recovery is attempted on in-doubt transactions until they are resolved or the resource is administratively removed.

  • WebLogic Server will not start if a determiner resource is not available because XA transactions cannot be recovered.

  • To change the targeting of a determiner resource, you need to:

    1. Ensure that all XA transactions are complete on the server or servers that host the determiner resource.

    2. Stop any server or servers hosting the determiner resource.

    3. Retarget the determiner resource.

    4. Start any server or cluster hosting the determiner resource.

  • If more than one server is participating in a global transaction, a transaction entry is written to the TLog.

  • If more than one determiner resource is available from the list of specified determiners, the first determiner enlisted is implicitly nominated as the determiner of the transaction.

  • Applications can have a combination of global transactions, some that enlist a determiner resource and some that do not. Only those transactions that do not enlist the determiner resource will be written to the TLog.

  • This feature does not support Dynamic Clusters.

  • This feature supports Whole Server Migration (WSM), see Whole Server Migration in Administering Clusters for Oracle WebLogic Server. Service Migration (ASM) is not supported.

Read-Only, One-Phase Commit Optimizations

When resource managers, such as the Oracle Database (including AQ and RAC), provide read-only optimizations, Oracle WebLogic can provide a read-only, one-phase commit optimization. Read-only, one-phase commit optimization provides a number of benefits – even when enabling multiple connections of the same XA transactions – such as eliminating XAResource.prepare network calls and transaction log writes, both in Oracle WebLogic and in the resource manager.

Note:

Read-only, One-phase Commit Optimization requires Oracle Database 11.1.0.7.3PSU or later.

For applications that do not require two-phase commit transactions, you can further optimize performance by also disabling the WebLogic "Two Phase Commit" protocol, which coordinates transactions across two or more resource managers. Disabling two-phase commits, does the following:

  • Removes persistent in-doubt logging and locks, as well as bookkeeping overhead in the database.

  • Removes all checkpoint logging in WebLogic.

  • Enforces and/or tests the assumption that a particular server instance does not require two-phase commit.

  • Removes the need for WebLogic migration (whole server or service) recovery, which in turn removes the need for additional assets/capacity, management, etc., involved in such migrations.

Configuring Read-only, One-phase Commit Optimization and Two-phase Commit Disablement

In order to enable the read-only, one-phase commit optimization and disable two-phase commits, configure the following JTA domain configuration attributes:

  • Execute XA Calls In Parallel – Set to false to enable the read-only, one-phase commit optimization.

  • Enable Two Phase Commit – Optionally, set to false to disable two-phase commit transactions. This disables all transaction logging, including checkpoint records. Any attempt to use two-phase commit will result in a RollbackException being thrown.

    Important! The Enable Two Phase Commit setting, which is true by default, should not to be set to false unless it is well-known that the application only uses a resource manager that provides read-only optimization, such as Oracle database, or that the application only uses a single connection to a single resource manager.

Note:

If a XA resource returns an XA_OK vote from a prepare (for example, if it is not an Oracle database), and the WebLogic instance then crashes before rollback can take place, there will be an in-doubt record and locks will be held in the resource manager (database) that will need to be manually resolved.

For more information on all JTA domain configuration options, see Configuring JTA Domains in the Oracle WebLogic Server Administration Console Online Help.

Monitoring Read-only, One-phase Transaction Statistics

For monitoring purposes, there are five transaction processing statistics on the JTA Monitoring page, which together break down the Transaction Committed Total Count statistic to better track any read-only, one-phase commit transactions.

  • Transaction No Resources Committed Total Count – The total number of transactions with no enlisted resources that were committed since the server was started.

  • Transaction One Resource One Phase Committed Total Count – The total number of transactions with only one enlisted resource that were one-phase committed since the server was started.

  • Transaction Read Only One Phase Committed Total Count – The total number of transactions with more than one enlisted resource that were one-phase committed due to read-only optimization since the server was started.

  • Transaction Two Phase Committed Total Count – The total number of transactions with more than one enlisted resource that were two-phase committed since the server was started.

  • Transaction LLR Committed Total Count – The total number of LLR transactions that were committed since the server was started.

    Note: If the only resource enlisted in a JTA transaction is an LLR data source, then such transactions are included under the Transaction One Resource One Phase Committed Total Count category rather than the Transaction LLR Committed Total Count category.

For more information on JTA monitoring statistics, see Monitoring JTA Statistics in the Oracle WebLogic Server Administration Console Online Help.