-
Notifications
You must be signed in to change notification settings - Fork 151
Transaction manager configuration
BTM configuration settings are stored in a `Configuration` object. It can be obtained by calling `TransactionManagerServices.getConfiguration()`. All settings are documented in the javadoc and you should refer to it to know what can be configured.
The `Configuration` object is implemented with sensible default settings. For a first time user, all default settings are good enough. After the initial testing phase, you might want to change some settings. This can be done in two ways: via a properties configuration file or by setting values directly on the `Configuration` object.
You can create a properties file in which you'll set some configuration settings. All the ones you omit will keep their default value.
The file can be stored anywhere on the file system in which case you need to set the `bitronix.tm.configuration` system property to tell BTM where the file lies. This is generally done by adding a `-D` argument to the virtual machine's command line:
java -Dbitronix.tm.configuration=./my-btm-config.properties MyClass
Another way is to call the properties file `bitronix-default-config.properties` and store it at the root of your classpath.
The properties file is in the default format `key=value`. Ant-like references (`${some.property.name}`) to other properties or to system properties (defined with `-D` on the command line) are supported.
You can call any setter you want on the object you get from the call to `TransactionManagerServices.getConfiguration()`. This is convenient if you do not want to use the properties file to configure BTM but want to leverage - for instance - Spring instead. Since the Configuration object is a singleton, there is no need to pass it to any other object, BTM will pick it up at startup.
Configuration conf = TransactionManagerServices.getConfiguration();
conf.setServerId("jvm-1");
conf.setLogPart1Filename("./tx-logs/part1.btm");
conf.setLogPart2Filename("./tx-logs/part2.btm");
These configurable properties are related to the transaction manager's core.
A stable ASCII string that must uniquely identify this TM instance. It must not exceed 51 characters or it will be truncated.
| Configuration object property | serverId |
| Default | The machine's IP address but that's unsafe for production usage |
Should two phase commit be executed asynchronously? Asynchronous two phase commit will improve 2PC execution time when there are many resources enlisted in transactions but can be very CPU intensive when used on JDK 1.4 without the java.util.concurrent backport implementation available on the classpath. It also makes debugging more complex.
| Configuration object property | asynchronous2Pc |
| Default | false |
Should transactions executed without a single enlisted resource result in a warning or not? Most of the time transactions executed with no enlisted resource reflect a bug or a mis-configuration somewhere.
| Configuration object property | warnAboutZeroResourceTransaction |
| Default | true |
Should creation and commit call stacks of transactions executed without a single enlisted resource tracked and logged or not? This is a companion to warnAboutZeroResourceTransaction where the transaction creation and commit call stacks could help you identify the culprit code.
| Configuration object property | debugZeroResourceTransaction |
| Default | false |
The transaction manager registers objects in the JMX registry by default if available. Set this to true to never register JMX objects.
| Configuration object property | disableJmx |
| Default | false |
The name under which the transaction manager will be bound in the internal JNDI provider.
| Configuration object property | jndiUserTransactionName |
| Default | java:comp/UserTransaction |
Should the transaction manager allow multiple LRC resources to be enlisted into the same transaction? Having multiple LRC resources participate in a transaction gives up the recovery guarantee but sometimes is useful in development mode.
| Configuration object property | allowMultipleLrc |
| Default | false |
Set this to true if you run multiple instances of the transaction manager on the same JMS and JDBC resources to avoid the recovery process to try to recover transactions started by another node.
| Configuration object property | currentNodeOnlyRecovery |
| Default | true |
These configurable properties are related to the disk journal used to record recovery information.
Set the journal to be used to record transaction logs. This can be any of disk, null or a class name. The disk journal is a classic implementation using two fixed-size files and disk forces, the null journal just allows one to disable logging. This can be useful to run tests. Do not use the null journal on production as without transaction logs, atomicity cannot be guaranteed.
| Configuration object property | journal |
| Default | disk |
Journal fragment file 1.
| Configuration object property | logPart1Filename |
| Default | btm1.tlog |
Journal fragment file 1.
| Configuration object property | logPart2Filename |
| Default | btm2.tlog |
Are logs forced to disk? **Do not set to false on production since without disk force, atomicity cannot be guaranteed.**
| Configuration object property | forcedWriteEnabled |
| Default | true |
Maximum size in megabytes of the journal fragments. Larger logs allow transactions to stay longer in-doubt but the TM pauses longer when a fragment is full.
| Configuration object property | maxLogSize |
| Default | 2 |
Should only mandatory logs be written? Enabling this parameter lowers space usage of the fragments but makes debugging more complex.
| Configuration object property | filterLogStatus |
| Default | false |
Should corrupted transactions log entries be skipped? Use only at last resort when all you have to recover is a pair of corrupted files.
| Configuration object property | skipCorruptedLogs |
| Default | false |
Should transactions be appended to the log in a single-threaded fashion similar to BTM 2.x? Setting conservative journaling can have a large impact on performance and should only be set to workaround a bug in the new BTM 3.x parallel log appending support.
| Configuration object property | conservativeJournaling |
| Default | false |
The transaction manager heavily relies on timeouts. All of them can be configured.
Default transaction timeout in seconds.
| Configuration object property | defaultTransactionTimeout |
| Default | 60 |
Maximum amount of seconds the TM will wait for transactions to get done before aborting them at shutdown time.
| Configuration object property | gracefulShutdownInterval |
| Default | 60 |
Interval in seconds at which to run the recovery process in the background. Cannot be disabled.
| Configuration object property | backgroundRecoveryIntervalSeconds |
| Default | 60 |
The resource loader loads and configures XA resources using configuration stored in a properties file. See the Resource Loader page for more details.
Resource Loader configuration file name.
| Configuration object property | resourceConfigurationFilename |
| Default | none (optional) |
JDBC and JMS connection pools configuration are discussed in details in the JDBC pools configuration and the JMS pools configuration pages. Alternatively you can use the Resource Loader instead.