Programming WebLogic JTA
Configuring Transactions
The following sections provide configuration tasks related to transactions:
- Overview of Transaction Configuration
- Configuring JTA
- Configuring Domains for Inter-Domain Transactions
- Configuring Domains for Intra-Domain Transactions
- Transaction Log Files
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 can participate in transactions, such as EJBs, JDBC data sources, and JMS.
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 Configure 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:
| 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.
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:
- 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.
Oracle 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 Configure WebLogic JDBC.
Configuring Communication Channels
You must correctly configure compatible communication channels using either Cross Domain Security or Security Interoperability Mode for all participating domains in global transactions.
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.
The following sections provide more information on configuring communication channels for global transactions:
Use the following table to determine the type of communication channel configuration required for inter-domain transactions.
When Security Interoperability Mode is set to performance, you are not required to set domain trust between the domains.
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 can have a different set of credentials which belong to the CrossDomainConnector security role.
See “Configuring Cross-Domain Security” and “Configure a credential mapping for Cross-Domain Security” in Securing 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, you need to do the following:
- Set cross-domain security in DomainA for DomainB
- Set cross-domain security in DomainB for DomainA
- Set cross-domain security in DomainA for DomainC
- Set cross-domain security in DomainC for DomainA
- Set cross-domain security in DomainB for DomainC
- Set cross-domain security in DomainC for DomainB
Because DomainD does not participate in the transaction there is no need to set cross-domain credential mapping. 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-3. The checkmark (
) indicates that configure cross domain security for this domain combination.
| DomainA | DomainB | DomainC | DomainD | |
|---|---|---|---|---|
| DomainA | ||||
| DomainB | ||||
| DomainC | ||||
| DomainD |
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-4. The checkmark () indicates that configure cross domain security for this domain combination.
| DomainA | DomainB | DomainC | DomainD | DomainE | |
|---|---|---|---|---|---|
| DomainA |
| ||||
| DomainB |
|
|
|
| |
| DomainC |
|
|
|
| |
| DomainD |
|
|
|
| |
| DomainE |
|
|
|
|
Adding Domains to the Exclude List Based on Transaction Participation
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, you need to add that domain to the exclude list of the domain that has cross domain security configured.
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 will fail. See Configure a credential mapping for Cross-Domain Security in Securing 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 disable, 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 will 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 will be 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 rolledback. 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:
- Establish Domain Trust
- Configuring Security Interoperability Mode using the values from Table 3-2.
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.
- 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 10.x domains, see Enable trust between domains in Administration Console Online Help.
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 10.x domains, see Configure securityity interoperabilty mode.
- For servers in WebLogic Server 9.x domains, see Configure the security mode for XA transactions.
- For servers in WebLogic Server 8.1 domains, see Using Security Interoperability Mode.
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 7.0sp7 and higher and 8.1sp5 higher then set SecurityInteropMode=compatibility and enable domain trust.
When SecurityInteropMode is set to compatibility Man-in-the-middle attacks are possible.
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.
Use the following information to determine the type of communication channel configuration required for intra-domain transactions.
- For servers in a WebLogic Server 10.x domain, set participating servers to either default or performance.
- For servers in a WebLogic Server 9.x domain, set participating servers to either default or performance.
- For servers in a WebLogic Server 8.1 SP5 and higher domain, set participating servers to performance.
- For servers in a WebLogic Server 8.1 SP4 and lower domain, Security Interoperability Mode is not available.
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, 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, 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.
|