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.
You can force Atomikos to look for a properties file in a different location or with a different name than the default, by setting the VM property com.atomikos.icatch.file to the path of a valid property file:
java -Dcom.atomikos.icatch.file=<path_to_your_file> ...
where <path_to_your_file> is the file system path that points to your property file.
|
Transaction manager
| property name |
meaning |
since release |
| 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.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.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.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.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. |
3.0 |
| 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. force_shutdown_on_vm_exit |
Specifies whether VM shutdown should trigger forced shutdown of the transaction core. Defaults to true. |
3.3 |
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.lock_logs |
Whether or not a temporary .lck file should be created on startup, to prevent accidental duplicate startups with the same transaction logs. Defaults to true. |
3.3 |
Console debug logs
| property name |
meaning |
since release |
| com.atomikos.icatch.console_log_level |
Specifies the console log level. Defaults to WARN. Should be one of: WARN, INFO or DEBUG. |
3.0 |
| com.atomikos.icatch.output_dir |
Specifies the directory in which to store the debug log files. Defaults to the current working directory. |
3.0 |
| com.atomikos.icatch.console_file_name |
Specifies the debug logs file name. Defaults to tm.out. |
3.0 |
| com.atomikos.icatch.console_file_count |
Specifies how many debug logs files can be created. Defaults to 1. |
3.0 |
| 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 |
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. |
3.2 |
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.
--
GuyPardon - 26 Jul 2007
