Looking for the perfect configuration that avoids issues and maximises performance? Our commercial support can help! Click the button to start your free trial today:

Free Trial

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.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. See this blog post for details. 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
com.atomikos.icatch.throw_on_heuristic Should heuristic exceptions be thrown to the application or not? Defaults to false. Enable this if you are doing transactions that cross different microservices. 5.x

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 (in millis). 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
com.atomikos.icatch.jvm_id ID of the JVM - needed for recovery in the LogCloud Documentation. Should be set as a system property, if absent then a default is generated. 5.x

Transaction logs

Property name Meaning Since release
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
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.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 in the open source - tuned for performance in the commercial versions. 3.0


Property name Meaning Since release
com.atomikos.monitoring.logs.format Specifies the transactions output format for monitoring. Defaults to key-value. Set to json if you prefer JSON output. 5.0
com.atomikos.monitoring.interval_seconds The interval between output of system health statistics. Defaults to 60 seconds. 5.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.

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

Fast track: start your free trial

Our support is the fastest way to a solution. Click the button to start your free trial today:

Free Trial

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 2021 Atomikos BVBA | Our Privacy Policy
By using this site you agree to our cookies. More info. That's Fine