3 Configuring Transactions

This chapter describes 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.

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 Oracle WebLogic Scripting Tool) or JMX (see Developing Custom Management Utilities With JMX for Oracle WebLogic Server) to configure transaction-related settings.

Configuring JTA

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 level, meaning that configuration attribute settings apply to all servers within a domain. See "Configure JTA" in the Oracle WebLogic Server Administration Console Help.

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

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 Secure Inter-Domain and Intra-Domain Transaction Communication

For a transaction manager to manage distributed transactions, the transaction manager must be able to communicate with all participating servers and resources to prepare and then commit or rollback the transactions. How a communication channel is configured depends on whether the transaction route is:

  • Inter-domain—The transaction communication is between servers participating in transactions that are not in the same domain.

  • Intra-domain—The transaction communication is between servers participating in transactions within the same domain.

Communication channels must be secure to prevent a malicious third-party from using man-in-the-middle attacks to affect transaction outcomes and potentially gaining administrative control over one or more domains. WebLogic Server provides the following options to secure a communication channel:

  • Cross Domain Security—Uses a credential mapper to enable you to configure compatible communication channels between servers in Inter-domain transactions. Although it requires a more complex configuration, Cross Domain Security enables you to tailor trust between individual domains.

  • Security Interoperability Mode—Establishes trust between all domains that participate in a transaction by setting a security credential of all domains to the same value so that principals in a Subject from one WebLogic Server instance are accepted as principals in another instance. It is simpler to configure than Cross Domain Security but some settings of Security Interoperability Mode rely on domain trust and offer less security than Cross Domain Security.

The following sections provide information on how to configure secure communication between servers during a transaction:

Requirements for Transaction Communication

Please note the following requirements when configuring communication channels for your transaction environment:

  • 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.

  • Keep all the domains used by your process symmetric with respect to Cross Domain Security configuration and Security Interoperability Mode. Because both settings are set at the domain level, it is possible for a domain to be in a mixed mode, meaning the domain has both Cross Domain Security and Security Interoperability Mode set.

  • If you are interoperating with WebLogic Server 8.1 domains, there is a known issue which may occur when performing inter-domain transactions due to 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 Upgrade Guide for Oracle WebLogic Server

  • Only one data source with both of the following attribute conditions 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.

Configuring Communication for Inter-Domain Transactions

You must correctly configure compatible communication channels using either Cross Domain Security or Security Interoperability Mode for all participating domains in global transactions. See:

Use the following table to determine when to use Cross Domain Security or Security Interoperability Mode:

Table 3-2 Selecting a Channel Configuration

Channel Configuration Advantage Disadvantage

Cross Domain Security

  • specific users are configured to establish communication between a domain pair.

  • With SSL, prevents man-in-the-middle attacks.

  • More complex configuration.

  • Any change to the transaction flow, such as changing participants, participant roles (coordinator versus resource or subcoordinator), adding or removing a domain, or changing the transaction route, requires a configuration change.

Security Interoperability Mode

  • Very easy to configure.

  • No need to understand the transaction flow when configuring Security Interoperability Mode.

  • Backward compatible with WebLogic 8.1.]

  • When in default mode, using the admin channel prevents man-in-the-middle attacks.

  • Trust is transitive: if Domain A trusts Domain B and Domain B trusts Domain C, then Domain A will trust Domain C.

  • When set to compatibility, inter-domain trust grants administrator privileges across domains. That is, with trust established between domains, an Administrator in Domain A has administrator privileges in Domain B.

  • In some configurations, there is a narrow possibility of man-in-the-middle attacks.


Use the following table to determine the type of communication channel configuration required for inter-domain transactions.

Table 3-3 Communication Channel Configurations for Inter-Domain Transactions

Domain 10.x and 9.2 MP2 and higher MPs 9.0, 9.1, 9.2 MP1 and lower 8.1 SP5 and higher 8.1 SP4 and lower

10.x and 9.2 MP2 and higher MPs

Configure both domains for Cross Domain Security

or

use Security Interoperability mode and set both domains to either default or performance

Configure the 10.x or 9.2 MP2 and higher MP domain for Cross Domain Security and include the 9.0, 9.1, or 9.2 MP1 and lower domain in the exception list

or

use Security Interoperability mode and set both domains to either default or performance

Configure the 10.x or 9.2 MP2 and higher MP domain for Cross Domain Security and include the 8.1 domain in the exception list

or

use Security Interoperability mode and set both domains to performance

Configure the 10.x or 9.2 MP2 and higher MP for Cross Domain Security and include the 8.1 domain in the exception list

or

use Security Interoperability mode and set the 10.x or 9.2 MP2 and higher MP to compatibility

9.0, 9.1, 9.2 MP1 and lower

Configure the 10.x or 9.2 MP2 and higher MP domain for Cross Domain Security and include the 9.0, 9.1, or 9.2 MP1 and lower domain in the exception list

or

use Security Interoperability mode and set both domains to either default or performance

Set both domains to either default or performance

Set both domains to performance

Set the 9.x domain to compatibility

8.1 SP5 and higher

Configure the 10.x or 9.2 MP2 and higher MP domain for Cross Domain Security and include the 8.1 domain in the exception list

or

use Security Interoperability mode and 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

8.1 SP4 and lower

Configure the 10.x or 9.2 MP2 and higher MP for Cross Domain Security and include the 8.1 domain in the exception list

or

use Security Interoperability mode and set the 10.x or 9.2 MP2 and higher MP to compatibility

Set the 9.x domain to compatibility

Set the 8.1 SP5 and higher domain to compatibility

N/A


Note:

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

Configuring Domains for Intra-Domain Transactions

You must correctly configure compatible communication channels between servers participating in transactions within the same domain using Security Interoperability Mode. See Configuring Security Interoperability Mode.

For servers in a WebLogic Server 10.x domain, set participating servers to either default, performance or compatibility.

Configuring Cross Domain Security

Cross Domain Security uses a credential mapper to enable you to configure compatible communication channels between servers in global transactions. For every domain pair that participates in a transaction, a credential mapper is configured. Every domain pair have a different set of credentials which belong to the CrossDomainConnector security role (see "Configuring a Cross-Domain User" in Securing Oracle WebLogic Server.

See "Enabling Cross Domain Security Between WebLogic Server Domains" and "Configure a Credential Mapping for Cross-Domain Security" in Securing Oracle WebLogic Server.

Cross Domain Security is Not Transitive

Servers participating in a transaction set cross-domain credential mapping with each other. Unlike domain-trust, the cross domain security configuration is not transitive; that is, because A trusts B and B trusts C, it is not therefore also true that A trusts C.

Consider the follow scenario:

  • DomainA has Server1 (coordinator)

  • DomainB has Server2 (sub-coordinator)

  • DomainC has Server3 and Server4 (Server3 is a sub-coordinator)

  • DomainD has Server5 (does not participate in the transaction)

To set the cross-domain credential mapping in this scenario, do the following:

  1. Set cross-domain security in DomainA for DomainB

  2. Set cross-domain security in DomainB for DomainA

  3. Set cross-domain security in DomainA for DomainC

  4. Set cross-domain security in DomainC for DomainA

  5. Set cross-domain security in DomainB for DomainC

  6. Set cross-domain security in DomainC for DomainB

Because DomainD does not participate in the transaction, using cross-domain credential mapping is not required. However, see Adding Domains to the Exclude List Based on Transaction Participation for further clarification.

To present this information in another way, consider Table 3-4. A table cell containing Yes indicates that you must configure cross domain security for this domain combination.

Table 3-4 Setting Cross Domain Security with Three Participating Domains

-- DomainA DomainB DomainC DomainD

DomainA

No

Yes

Yes

No

DomainB

Yes

No

Yes

No

DomainC

Yes

Yes

No

No

DomainD

No

No

No

No


If you were then to add both DomainD and an additional DomainE to the cross-domain security configuration, the cross-domain credential map would be as shown in Table 3-5. A table cell containing Yes indicates that you must configure cross domain security for this domain combination.

Table 3-5 Setting Cross Domain Security with Five Participating Domains


DomainA DomainB DomainC DomainD DomainE

DomainA

No

Yes

Yes

Yes

Yes

DomainB

Yes

No

Yes

Yes

Yes

DomainC

Yes

Yes

No

Yes

Yes

DomainD

Yes

Yes

Yes

No

Yes

DomainE

Yes

Yes

Yes

Yes

No


Adding Domains to the Exclude List Based on Transaction Participation

The exclude list provides a mechanism for a server in a domain with Cross Domain Security configured to participate in a transaction with a server in another domain that does not support or have Cross Domain Security enabled.

If any server in a domain in which cross domain security is not configured participates in a transaction with any server in a domain in which cross domain security is configured, add that domain to the exclude list of the domain that has cross domain security configured. Security Interoperability Mode is used to establish communication channels for participating domains as described in Important Considerations When Configuring Cross Domain Security.

You do not need to add the domain to the exclude list of all domains that have cross domain security configured; the domain must explicitly participate in a transaction with the domain in question for this requirement to take effect.

Consider the following scenario:

  • Transaction #1:

    • DomainA has Server1 (coordinator)

    • DomainB has Server2 (sub-coordinator)

    • DomainC has Server3 and Server4 (Server3 is a sub-coordinator)

    • DomainD has Server5 (does not participate in the transaction, cross-domain security not configured)

  • Transaction #2:

    • DomainB has Server6 (coordinator)

    • DomainD has Server5 (sub-coordinator, cross-domain security not configured)

In this case DomainD has to be in the exclusion list of DomainB because of Transaction #2.

You do not need to include it in the exclusion list of DomainA or DomainC because DomainD does not participate in any transactions with servers in these two domains.

Important Considerations When Configuring Cross Domain Security

When configuring Cross Domain Security, consider the following guidelines:

  • Domain trust is not required for Cross Domain Security.

  • For every domain pair that participates in a transaction, a credential mapper must be correctly configured having a set of credentials which belong to the CrossDomainConnector security role. If the credential mapping is not correct, transactions across the participating domains fail. See "Configure a Credential Mapping for Cross-Domain Security" in Securing Oracle WebLogic Server.

  • Configure one-way SSL to provide additional communication security to protect the transaction from a man-in-the-middle attack.

  • To interoperate with WebLogic domains that either do not support Cross Domain Security or have Cross Domain Security disabled, you must add these domains to the Excluded Domain Names list of every participating WebLogic Server domain that has Cross Domain Security enabled. If the configuration of the Excluded Domain Names list and the CrossDomainSecurityEnabled flag is not consistent in all participating domains, branches of the transaction fail.

  • If Cross Domain Security Enabled flag is disabled or the domain is in the Excluded Domain Names list, then Security Interoperability Mode is used to establish communication channels for participating domains.

  • When enabling or disabling the Cross Domain Security Enabled flag, there may be a period of time where transactions or other remote calls can fail. For transactions, if the commit request fails, the commit is retried after the configuration change is complete. If a transaction RMI call fails during any other request, then the transaction times out and the transaction is rolled back. The rollback is retried until AbandonTimeoutSeconds.

Configuring Security Interoperability Mode

Security Interoperability Mode enables you to configure compatible communication channels between servers in global transactions. Use the following steps to configure Security Interoperability Mode:

  1. Establish Domain Trust

  2. Configuring Security Interoperability Mode using the values from Table 3-3.

    Note:

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

Establish Domain Trust

Establish domain trust by setting a security credential for all domains to the same value in all participating domains.

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. If the admin channel is not configured, the Security Interoperability Mode behavior is the same as using performance.

  • performance—The transaction coordinator always makes calls using anonymous. 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 a non-secure channel. This mode is required when interacting with WebLogic Servers servers that do not support Security Interoperability Mode. 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 the following topics in the Oracle WebLogic Server Administration Console Help:

Configuring Domains for JNDI Lookups Requiring an Admin User

The following section provides information on how to configure SecurityInteropMode when transactions use JNDI lookups that require an admin user.

  • If the WebLogic Server domain is 9.0, 9.1, 9.2 and higher MP, 10.x or higher MP then do one of the following:

    • Set SecurityInteropMode=default, configure admin channels, and enable domain trust.

    • Set SecurityInteropMode=compatibility and enable domain trust.

  • If the WebLogic Server domain is 8.1SP5 and higher SP, then set SecurityInteropMode=compatibility and enable domain trust.

When SecurityInteropMode is set to compatibility Man-in-the-middle attacks are possible.

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 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 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 Oracle WebLogic Server Administration Console 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" in Configuring Server Environments for Oracle WebLogic Server.

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

Using a JDBC JTOG 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 "Using a JDBC TLog Store" in Configuring Server Environments for Oracle WebLogic Server.

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 that 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 DB 11.1.0.7.3PSU or above.

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 WebLogic 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 WebLogic Administration Console Online Help.