10.2. Configuration Essentials

Configuration of the default JBoss Transaction Service 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 server/[name]/conf/jbossts-properties.xml It contains defaults for the most commonly used properties. Many more are detailed in the accompanying JBossTS documentation and can be added to the configuration file as needed. All also have hard-coded defaults, but the system may not function exactly as expected in the absence of a properties file. The configuration given in this file is supplemented by the microcontainer beans configuration found in the server/[name]/deploy/transaction-jboss-beans.xml file. This ties the transaction manager into the wider server configuration, overriding the transaction config file settings with application server specific values where appropriate. In particular, it uses the service binding manager to set port binding information and overrides selected other properties. Configuration properties are read by JBossTS at server initialization and changes made thereafter, either to the properties file, beans file, or programatically, will not have an effect until server (JVM) restart.

Critical Bean Properties for JTA

The default time in seconds before a transaction will be considered stuck and may be rolled back by the transaction manager. This helps to prevent poor code from blocking the system indefinitely.
The default value is 300 seconds. This should be adjusted to suit your environment and workload.
Transaction timeouts are processed asynchronously, which may not be appropriate for your application.
Defines the directory in which to log transaction data. This bean property overrides the jbossts-properties.xml configuration file value for com.arjuna.ats,arjuna,objectstore.objectStoreDir.
This transaction log is required to complete transactions in case of system failure. The storage device used must therefore be highly performant and reliable. In general, local RAID disk is preferred. Remote storage can be used if file locking is correctly implemented. However, requiring network I/O can be a significant performance bottleneck.
The ObjectStore usually contains one file of several kilobytes per in-flight transaction. These are distributed over a directory tree for optimal performance. The small file size and rapid creation/deletion of files lends itself well to SSD-based storage devices. If used, RAID controllers should be configured for write through cache, similarly to database storage devices. Writing the transaction log is automatically skipped for transactions that are rolling back or contain only a single resource.

Configuration Properties In jbossts-properties.xml

This setting determines the internal log threshold for the transaction manager codebase. It is independent of the server's wider log4j logging configuration and represents an additional hurdle that log messages must pass before being printed. The default value is 0x00000000, that is, no debug logging. INFO and WARN messages will still be printed by default. This provides optimal performance. The value 0xffffffff should be used when full debug logging is required. This is very verbose and will result in large log files. Log messages that pass the internal DebugLevel check will be passed to the server's logging system for further processing. Thus it may also be necessary to set appropriate configuration for com.arjuna code in the server/$PROFILE/conf/jboss-log4j.xml file. Note that whilst a value of 0xffffffff may be left in place permanently and the log4j settings used to turn logging on or off, this is less performant than using the internal DebugLevel checking.
This setting determines if the transaction manager will automatically apply the one-phase commit optimization to the transaction completion protocol in cases where only a single resource is registered with the transaction. It is enabled (set to YES) by default to provide optimal performance, since no transaction log write is necessary in such cases. Some resource managers may not be compatible with this optimization and it is occasionally necessary to disable it. This can be done by changing the value to NO.
This setting controls the flushing of transaction logs to disk during the transaction termination. It is enabled (set to ON) by default, which results in a FileDescriptor.sync call for each committing transaction. This is required to provide recovery guarantees and hence ACID properties. If the applications running in the server can tolerate data inconsistency or loss, greater performance may be achieved by disabling this behavior by setting the property value to “OFF”. This is not recommended – it is usually preferable to recraft such applications to avoid using the transaction manager entirely.
com.arjuna.ats.arjuna.xa.nodeIdentifier and com.arjuna.ats.jta.xaRecoveryNode
These properties determine the behavior of the transaction recovery system. Correct configuration is essential to ensure transactions are resolved correctly in the event of a server crash and restart. See the crash recovery section that follows for details.
This property enables the gathering of transaction statistics, which may be viewed via methods on the TransactionManagerService bean or, more commonly, its corresponding JMX MBean. This option is disabled by default, as the additional locking needed to record statistics accurately may cause a slight performance impact. Thus the statistics getter methods will thus normally return zero values. To enable the option, set its value to YES in the properties file.