Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Configuration</h1>

<p>BTM configuration settings are stored in a <code>Configuration</code> object. It can be obtained by calling <code>TransactionManagerServices.getConfiguration()</code>. All settings are documented in the <a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html">javadoc</a> and you should refer to it to know what can be configured.</p>

<h4>Contents</h4>
<img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0zfG1pbkxldmVsPTJ9&amp;locale=en_GB&amp;version=2" data-macro-name="toc" data-macro-parameters="maxLevel=3|minLevel=2">

<h2>How to configure BTM</h2>

<p>The <code>Configuration</code> 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 <code>Configuration</code> object.</p>

<h3>The properties configuration file</h3>

<p>You can create a properties file in which you'll set some configuration settings. All the ones you omit will keep their default value.</p>

<p>The file can be stored anywhere on the file system in which case you need to set the <code>bitronix.tm.configuration</code> system property to tell BTM where the file lies. This is generally done by adding a <code>-D</code> argument to the virtual machine's command line:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
java -Dbitronix.tm.configuration=./my-btm-config.properties MyClass
</pre></td></tr></table>
<p>Another way is to call the properties file <code>bitronix-default-config.properties</code> and store it at the root of your classpath.</p>

<p>The properties file is in the default format <code>key=value</code>. Ant-like references <code>(${some.property.name})</code> to other properties or to system properties (defined with <code>-D</code> on the command line) are supported.</p>

<h3>Setting values directly on the <code>Configuration</code> object</h3>

<p>You can call any setter you want on the object you get from the call to <code>TransactionManagerServices.getConfiguration()</code>. This is convenient if you do not want to use the properties file to configure BTM but want to leverage <em>- for instance -</em> Spring instead.</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
Configuration conf = TransactionManagerServices.getConfiguration();
conf.setServerId("jvm-1");
conf.setLogPart1Filename("./tx-logs/part1.btm");
conf.setLogPart2Filename("./tx-logs/part2.btm");
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Read only configuration" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9UmVhZCBvbmx5IGNvbmZpZ3VyYXRpb259&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>Once BTM has started, any attempt to call a set method on the <code>Configuration</code> object will throw a <code>IllegalStateException</code>.</p></td></tr></table>

<p>Since the <code>Configuration</code> object is a singleton, there is no need to pass it to any other object, BTM will pick it up at startup.</p>

<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Configuration dropped after restart" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9Q29uZmlndXJhdGlvbiBkcm9wcGVkIGFmdGVyIHJlc3RhcnR9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>The <code>Configuration</code> object is dropped during BTM shutdown. You need to call all setters methods again before you restart the transaction manager. Keep this in mind if you plan to hot-redeploy your application in your application server.</p></td></tr></table>

<h2>Configurable settings</h2>
<p>There are many different settings that are configurable in the transaction manager. Fortunately, all defaults settings are usually good enough to get started. You only need to tune them when required.</p>

<h3>Transaction engine settings</h3>
<p>These configurable properties are related to the transaction manager's core.</p>

<h3>Disk journal settings</h3>
<p>These configurable properties are related to the disk journal used to record recovery information.</p>

<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"><p>File property name</p></th>
<th class="confluenceTh"><p>Configuration property name</p></th>
<th class="confluenceTh"><p>Default value</p></th>
<th class="confluenceTh"><p>Description</p></th>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.logPart1Filename</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setLogPart1Filename(java.lang.String)">logPart1Filename</a></p></td>
<td class="confluenceTd"><p>btm1.tlog</p></td>
<td class="confluenceTd"><p>Journal fragment file 1.</p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.logPart2Filename</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setLogPart2Filename(java.lang.String)">logPart2Filename</a></p></td>
<td class="confluenceTd"><p>btm2.tlog</p></td>
<td class="confluenceTd"><p>Journal fragment file 2.</p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.forcedWriteEnabled</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setForcedWriteEnabled(boolean)">forcedWriteEnabled</a></p></td>
<td class="confluenceTd"><p>true</p></td>
<td class="confluenceTd"><p>Are logs forced to disk ? <em><strong>Do not set to false in production since without disk force, integrity is not guaranteed.</strong></em></p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.forceBatchingEnabled</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setForceBatchingEnabled(boolean)">forceBatchingEnabled</a></p></td>
<td class="confluenceTd"><p>true</p></td>
<td class="confluenceTd"><p>Are disk forces batched ? Disabling batching can seriously lower the transaction manager's throughput.</p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.maxLogSize</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setMaxLogSizeInMb(int)">maxLogSize</a></p></td>
<td class="confluenceTd"><p>2</p></td>
<td class="confluenceTd"><p>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.</p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.filterLogStatus</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setFilterLogStatus(boolean)">filterLogStatus</a></p></td>
<td class="confluenceTd"><p>false</p></td>
<td class="confluenceTd"><p>Should only mandatory logs be written ? Enabling this parameter lowers space usage of the fragments but makes debugging more complex.</p></td>
</tr>
<tr>
<td class="confluenceTd"><p>bitronix.tm.journal.disk.skipCorruptedLogs</p></td>
<td class="confluenceTd"><p><a href="http://btm.codehaus.org/api/1.2/bitronix/tm/Configuration.html#setSkipCorruptedLogs(boolean)">skipCorruptedLogs</a></p></td>
<td class="confluenceTd"><p>false</p></td>
<td class="confluenceTd"><p>Should corrupted transactions log entries be skipped ? Use only at last resort when all you have to recover is a pair of corrupted files.</p></td>
</tr>
</tbody></table>

<h3>Timers settings</h3>
<p>The transaction manager heavily relies on timeouts. All of them can be configured.</p>

<h3>Resource Loader settings</h3>
<p>The resource loader loads and configures XA resources using configuration stored in a properties file. See the <a class="confluence-link" href="/display/BTM/ResourceLoader12" data-linked-resource-id="72056885" data-linked-resource-type="page" data-linked-resource-default-alias="ResourceLoader12" data-base-url="http://docs.codehaus.org">ResourceLoader12</a> page for more details.</p>

<h2>Connection pools settings</h2>
<p>JDBC and JMS connection pools configuration are discussed in details in the <a class="confluence-link" href="/display/BTM/JdbcConfiguration12" data-linked-resource-id="6914058" data-linked-resource-type="page" data-linked-resource-default-alias="JdbcConfiguration12" data-base-url="http://docs.codehaus.org">JDBC pools configuration</a> and the <a class="confluence-link" href="/display/BTM/JmsConfiguration12" data-linked-resource-id="7995414" data-linked-resource-type="page" data-linked-resource-default-alias="JmsConfiguration12" data-base-url="http://docs.codehaus.org">JMS pools configuration</a> pages. Alternatively you can use the <a class="confluence-link" href="/display/BTM/ResourceLoader12" data-linked-resource-id="72056885" data-linked-resource-type="page" data-linked-resource-default-alias="ResourceLoader12" data-base-url="http://docs.codehaus.org">ResourceLoader12</a> instead.<br />
<img class="confluence-embedded-image confluence-external-resource" src="http://www.bitronix.be/images/shim.gif" data-image-src="http://www.bitronix.be/images/shim.gif"></p>