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.
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
Property name |
Meaning | Releases |
|---|---|---|
| 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 |
| 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 |
| 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). NOTE: as of 5.0, using 0 interferes with recovery. Instead, use Long.MAX_VALUE to specify unlimited. | 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 and later, removed as of 6.0 |
| 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 |
| com.atomikos.icatch.discard_read_only_coordinators_after_prepare | Should read only coordinators be discarded immediately after prepare? Defaults to true. Disable this to support diamond case scenario's (where the same root transaction calls a common service via 2 different call hierarchies). | 5.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 |
| 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 |
| 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 |
| com.atomikos.icatch.log_lock_acquisition_max_attempts | How many attempts to get a lock on the transaction log file on startup? Defaults to 3. | 6.0 |
| com.atomikos.icatch.log_lock_acquisition_retry_delay | How many millis between retries to get a lock on the transaction log file? Defaults to 1000. | 6.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 |
| 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 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.
Thread Pooling Design
Session Handle State
JMS Connection Classes
Borrow Connection From Pool
CheckConnectionsInPool
com.atomikos.icatch.log_base_dir = ...
com.atomikos.icatch.output_dir = ${com.atomikos.icatch.log_base_dir}
com.atomikos.icatch.log_base_dir = ${catalina.base}/logs
These issues no longer apply as of release 4.0.
You can avoid lookup of a properties file by setting the following system property:
java -Dcom.atomikos.icatch.no_file=trueWhen you do this, the init parameters must be specified programmatically - see Spring Integration for an example with Spring.
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.
Our support is the fastest way to a solution. Click the button to start your free trial today:
Free Trial