JTA Properties

26 Jul 2017 - 10:07 | Version 47 | | , , ,

Parameters Supported

Many TransactionsEssentials JTA settings can be tweaked. Fortunately most of them have sensible default values so most of the time you do not need to change anything to be ready.

Nevertheless it is sometimes useful to be able to change those settings. You can do so by creating a jta.properties file at the root of your classpath. All the names of the properties you can override are stored in the com.atomikos.icatch.config.TSInitInfo class.

The most common ones are explained on the rest of this page.

JVM (System) Properties

There are three properties of importance which are JVM (or System) properties and cannot be set via a properties file, nor through any programmatic configuration of Atomikos. These properties can be provided via the Java command line as follows:
 java -Dcom.atomikos.icatch.file=<path_to_your_file> ...

or they can be provided through the Spring Integration. These properties affect how Atomikos should locate an external JTA properties file. If a properties file cannot be located the following messages will be written to stderr:
No properties path set - looking for transactions.properties in classpath...
transactions.properties not found - looking for jta.properties in classpath...
Failed to open transactions properties file - using default values

Note: as of release 4.0, classpath-based property file lookup failures no longer generate any warnings on stderr.

Property name Meaning Releases
com.atomikos.icatch.file Forces Atomikos to look for a properties file in a different location (possibly off the class-path) or with a different name than the default 3.x, 4.x
com.atomikos.icatch.no_file Indicates that Atomikos should not try to locate such an external file. Note that even with this property set to true, Atomikos will still write messages to stderr that it is trying to find a file. 3.x
com.atomikos.icatch.hide_init_file_path hides all Atomikos external properties file initialization messages that are output to std err 3.x

Transaction manager

Property name Meaning Releases
com.atomikos.icatch.service Specifies the transaction manager implementation that should be started. There is no default value and this must be set. Generally, com.atomikos.icatch.standalone. UserTransactionServiceFactory is the value you should set. 3.x
com.atomikos.icatch.max_timeout Specifies the maximum timeout (in milliseconds) that can be allowed for transactions. Defaults to 300000. This means that calls to UserTransaction.setTransactionTimeout() with a value higher than configured here will be max'ed to this value. For 4.x or higher, a value of 0 means no maximum (i.e., unlimited timeouts are allowed). 3.x, 4.x
com.atomikos.icatch.default_jta_timeout The default timeout for JTA transactions (optional, defaults to 10000 ms) 3.4 and later, 4.x
com.atomikos.icatch.max_actives Specifies the maximum number of active transactions. Defaults to 50. A negative value means infinite amount. You will get an IllegalStateException with error message "Max number of active transactions reached" if you call UserTransaction.begin() while there are already n concurrent transactions running, n being this value. 3.x, 4.x
com.atomikos.icatch.enable_logging Specifies if disk logging should be enabled or not. Defaults to true. It is useful for JUnit testing, or to profile code without seeing the transaction manager's activity as a hot spot but this should never be disabled on production or data integrity cannot be guaranteed. 3.x, 4.x
com.atomikos.icatch.tm_unique_name Specifies the transaction manager's unique name. Defaults to the machine's IP address. If you plan to run more than one transaction manager against one database you must set this property to a unique value or you might run into duplicate transaction ID (XID) problems that can be quite subtle (example: http://fogbugz.atomikos.com/default.asp?community.6.2225.7). Since release 4.0, this name should not be a prefix of another instance's name accessing some of the same resources - or recovery will not work as expected. If multiple instances need to use the same properties file then the easiest way to ensure uniqueness for this property is by referencing a system property specified at VM startup. 3.x, 4.x
com.atomikos.icatch.serial_jta_transactions Specifies if subtransactions should be joined when possible. Defaults to true. When false, no attempt to call XAResource.start(TM_JOIN) will be made for different but related subtransactions. This setting has no effect on resource access within one and the same transaction. If you don't use subtransactions then this setting can be ignored. 3.x, 4.x
com.atomikos.icatch.force_shutdown_on_vm_exit Specifies whether VM shutdown should trigger forced shutdown of the transaction core. Defaults to false. 3.3 and later, 4.x
com.atomikos.icatch.allow_subtransactions Are subtransactions allowed or not? Default is true. 4.x
com.atomikos.icatch.default_max_wait_time_on_shutdown How long should normal shutdown (no-force) wait for transactions to complete? Defaults to Long.MAX_VALUE. 4.0.45

Recovery (4.x)

Property name Meaning Since release
com.atomikos.icatch.forget_orphaned_log_entries_delay Specifies the delay after which recovery can cleanup pending ('orphaned') log entries. Expressed in millis, defaults to 86400000 (i.e., one day). 4.x
com.atomikos.icatch.recovery_delay Specifies the delay between two recovery scans. Defaults to com.atomikos.icatch.default_jta_timeout. 4.x
com.atomikos.icatch.oltp_max_retries For commit failures: how many times should be retried before throwing an exception to the application? Defaults to 5. 4.x
com.atomikos.icatch.oltp_retry_interval For commit failures: How many milliseconds between retry attempts? Defaults to 10000. 4.x

Transaction logs

Property nameSorted ascending Meaning Since release
com.atomikos.icatch.checkpoint_interval Specifies the interval between checkpoints, expressed as the number of log writes between two checkpoints. A checkpoint reduces the log file size at the expense of adding some overhead in the runtime. Defaults to 500. 3.0
com.atomikos.icatch.log_base_dir Specifies the directory in which the log files should be stored. Defaults to the current working directory. This directory should be a stable storage like a SAN, RAID or at least backed up location. The transactions logs files are as important as the data themselves to guarantee consistency in case of failures. 3.0
com.atomikos.icatch.log_base_name Specifies the transactions log file base name. Defaults to tmlog. The transactions logs are stored in files using this name appended with a number and the extension .log. At checkpoint, a new transactions log file is created and the number is incremented. 3.0

Console logs

Prior to release 3.8

Property name Meaning Releases
com.atomikos.icatch.console_log_level Specifies the console log level. Defaults to WARN. Should be one of: WARN, INFO or DEBUG. 3.0 - 3.7
com.atomikos.icatch.output_dir Specifies the directory in which to store the debug log files. Defaults to the current working directory. 3.0 - 3.7
com.atomikos.icatch.console_file_name Specifies the debug logs file name. Defaults to tm.out. 3.0 - 3.7
com.atomikos.icatch.console_file_count Specifies how many debug logs files can be created. Defaults to 1. 3.0 - 3.7
com.atomikos.icatch.console_file_limit Specifies how many bytes can be stored at most in debug logs files. Defaults to -1. Negative values means unlimited. 3.0 - 3.7

As of release 3.8

More recent releases have abandoned the proprietary logging framework of Atomikos in favor of mainstream logging tools, as explained here.


Note that from release 3.2 on, Atomikos threads are pooled automatically if you use JDK 1.5 or higher. For JDK 1.4, you can use the concurrent backport utility to pool threads (just put the jar in the classpath and the backport pooling will be used by Atomikos). See http://dcl.mathcs.emory.edu/util/backport-util-concurrent/ for more on the backport utility.

Property name Meaning Since release
com.atomikos.icatch.threaded_2pc Specifies whether or not to use different (and concurrent) threads for two-phase commit on the participating resources. Setting this to true implies that the commit is more efficient since waiting for acknowledgements is done in parallel. Defaults to false since 3.7 (default was true for earlier releases). If false, then commits will happen in the order that resources are accessed within the transaction. 3.2

For maximum compatibility with JDBC and JMS implementations: set this property to false (i.e., disable threaded commits). As of release 3.7, false is the default value.

Referencing Parameter Values

As from release 3.2, a parameter value can be based on the value of some other parameter (either within the same properties file or specified as a system property). To reference the value of some parameter, use its name prefixed with '${' and suffixed with '}' - very much like in Ant, the popular Java build tool.

Typical examples are show below.

Example 1: referencing another parameter set in the same properties file

The following specifies that com.atomikos.icatch.output_dir should have the same value as com.atomikos.icatch.log_base_dir
com.atomikos.icatch.log_base_dir = ...
com.atomikos.icatch.output_dir = ${com.atomikos.icatch.log_base_dir}

IMPORTANT: note that the referenced parameter must also be set in the same properties file, or in a system property. In other words: you can't reference a default value.

Example 2: referencing a system property

The reference mechanism also works for system properties: if a property is not found in the property file itself, Atomikos will look it up in the system properties. The following example applies to Tomcat and sets the Atomikos log dir to the tomcat log dir, available via the Tomcat system property catalina.base
com.atomikos.icatch.log_base_dir = ${catalina.base}/logs

Properties that appear in the file take precedence over the properties that are set in the system. In this example, this means that if your jta.properties file contains a property named catalina.base then the system property won't be used.

Limitations (pre-4.0)

  • References of the form ${...} can only appear in a properties file. This technique won't work if you configure TransactionsEssentials programmatically.
  • You can't reference default values, only other parameters whose name appears in the properties file or in the system properties.

These issues no longer apply as of release 4.0.

Avoiding Property File Lookup (pre-4.0)

You can avoid lookup of a properties file by setting the following system property:
java -Dcom.atomikos.icatch.no_file=true

When you do this, the init parameters must be specified programmatically - see Spring Integration for an example with Spring.

Avoiding property file lookup also requires you to set the system property com.atomikos.icatch.service - since this property will NOT be looked up in the regular init properties that you supply. Note that this no longer applies to release 4.0 or later.

Property Value Lookup (4.0 and later)

Property values are now resolved as outlined here...

Contact Us

Atomikos Corporate Headquarters
Hoveniersstraat, 39/1, 2800
Mechelen, Belgium

E info@atomikos.com
E sales@atomikos.com
T +3215613055

Subscribe to our newsletter

Never miss an update

Copyright 2017 Atomikos BVBA