JTA Properties

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

Property name	Meaning	Since release
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
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.
com.atomikos.icatch.hide_init_file_path	hides all Atomikos external properties file initialization messages that are output to stderr

Transaction manager

Property name	Meaning	Since release
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 subtransctions. 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.0
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.0
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.0
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.	3.0
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.0
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). 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.0
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
com.atomikos.icatch.default_jta_timeout	The default timeout for JTA transactions (optional, defaults to 10000 ms)	3.4

Transaction logs

Property name	Meaning	Since&nsp;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. A checkpoint reduces the log file size at the expense of adding some overhead in the runtime. Defaults to 500.	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.

Threading

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 true. If you set this to 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

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

Avoiding Property File Lookup

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.

At the time of writing, 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. This will be fixed in a later release.