13.2. Configuration Essentials

Configuration of the default JBossTS JTA is managed though a combination of the transaction manager's own properties file and the application server's deployment configuration. The configuration file resides at <JBOSS_HOME>/server/<PROFILE>/conf/jbossts-properties.xml. It contains defaults for the most commonly used properties. Many more are detailed in the accompanying JBoss Transaction Service Administration Guide. Each setting has a hard-coded default, but the system may not function properly if a configuration file does not exist. Additional configuration is also possible as part of the Microcontainer beans configuration found in the <JBOSS_HOME>/server/<PROFILE>/deploy/transaction-jboss-beans.xml file. This ties the transaction manager into the overall server profile, overriding the transaction configuration file settings with values specific to the application server where appropriate. In particular, it uses the Service Binding Manager to set port binding information, as well as overriding selected other properties. Configuration properties are read by the Transaction Service at server initialization, and the server must be restarted to incorporate any changes made to the configuration files.

Table 13.1. Most Critical Properties for JBoss Transaction Service

Property Name
Default Value
Description
transactionTimeout
300 seconds
the default time, in seconds, after which a transaction will time out and be rolled back by. Adjust this to suit your environment and workload.
It may come as a surprise that transactions are processed asynchronously. This was a design decision, and needs to be accounted for by your code.
objectStoreDir
The directory where transaction data is logged. The transaction log is required to complete transactions in the case of system failure, and needs to be on reliable storage. Normally one file is generated per transaction, and each file is a few kilobytes in size. These are distributed over a directory tree for optimal performance. If a RAID controller is used, it should be configured for write through cache, in much the same manner as database storage devices. Writing of the transaction log is automatically skipped in the case of transactions that are rolling back or contain only a single resource.
max-pool-size
The Java EE Connector Architecture container keeps a dedicated physical connection open against the EIS where recovery is performed. Therefore, set the max-pool-size to the maximum number of connection possible minus 1.

Table 13.2. Additional Properties for JBoss Transaction Service

Property Name
Default Value
Description
com.arjuna.common.util.logging.DebugLevel
0x00000000, which equates to no logging
determines the internal log threshold for the transaction manager codebase. It is independent of the overall server's log4j logging configuration, and acts to suppress extraneous log entries from being printed. When the default value is active, INFO and WARN messages are still printed, and this setting provides optimal performance. 0xffffffff enables full debug logging. This setting results in large log files.
Log messages that pass the internal DebugLevel check are passed to the server's logging system for further processing. In theory, full debugging may be left on and log4j can be used to turn logging on or off, but in reality this has a performance impact.
com.arjuna.ats.arjuna.coordinator.commitOnePhase
YES
Determines whether the transaction manager automatically applies the one-phase commit optimization to the transaction completion protocol, when only a single resource is registered with the transaction. Enabled by default to prevent writing transaction logs needlessly.
com.arjuna.ats.arjuna.objectstore.transactionSync
ON
Controls the flushing of transaction logs to disk during transaction termination. The default value results in a FileDescriptor.sync call for each committing transaction. This behavior is required to provide recovery and ACID properties. If these features are unimportant to the application in question, you can achieve better performance by disabling this property. This is discouraged, since it is usually better to write such applications in a way that avoids using transactions at all.
com.arjuna.ats.arjuna.xa.nodeIdentifier
com.arjuna.ats.jta.xaRecoveryNode
These properties determine the behavior of the transaction recovery system. They must be configured correctly to ensure that transactions are resolved correctly so that recovery can happen if the server crashes. Please refer to the Recovery chapter of the JBoss Transactions Administration Guide for more details.
com.arjuna.ats.arjuna.coordinator.enableStatistics
NO
Enables gathering of transaction statistics. The statistics can be viewed using methods on the TransactionManagerService bean or its corresponding JMX MBean. Disabled by default.