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>How to use BTM as the transaction manager in Tomcat 5.5.x</h1>
<p>These instructions have been verified against BTM 1.1.</p>

<table class="wysiwyg-macro" data-macro-name="warning" data-macro-parameters="title=This is for BTM 1.2 and earlier" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3dhcm5pbmc6dGl0bGU9VGhpcyBpcyBmb3IgQlRNIDEuMiBhbmQgZWFybGllcn0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>These instructions are for BTM 1.2 and earlier only. BTM 1.3 instructions are <a class="confluence-link" href="/display/BTM/Tomcat13" data-linked-resource-id="109478174" data-linked-resource-type="page" data-linked-resource-default-alias="Tomcat13" data-base-url="http://docs.codehaus.org">here</a>.</p></td></tr></table>

<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>Step 1: Copy the BTM jars</h2>
<p>Copy the following jars from the BTM distribution to the Tomcat <code>common/lib/</code> directory:</p>

<ul>
	<li>btm-1.1.jar</li>
	<li>geronimo-spec-jta-1.0.1B-rc4.jar</li>
	<li>slf4j-jdk14.jar (<em>or any other one available <a class="confluence-link" href="/display/BTM/DebugLogging12" data-linked-resource-id="7995434" data-linked-resource-type="page" data-linked-resource-default-alias="DebugLogging12" data-base-url="http://docs.codehaus.org">here</a></em>)</li>
</ul>

<h2>Step 2: Configure BTM as the transaction manager</h2>
<p>Windows: Create a file named <code>setenv.bat</code> with the following commands under Tomcat's <code>bin/</code> directory:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
set CATALINA_OPTS=-Dbtm.root=%CATALINA_HOME% -Dbitronix.tm.configuration=%CATALINA_HOME%\conf\btm-config.properties
</pre></td></tr></table>

<p>Unix: Create a file named <code>setenv.sh</code> with the following commands under Tomcat's <code>bin/</code> directory:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
CATALINA_OPTS="-Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties"
</pre></td></tr></table>

<p>Now create a file named <code>btm-config.properties</code> with the following properties under Tomcat's <code>conf/</code> directory:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
bitronix.tm.serverId=tomcat-btm-node0
bitronix.tm.journal.disk.logPart1Filename=${btm.root}/work/btm1.tlog
bitronix.tm.journal.disk.logPart2Filename=${btm.root}/work/btm2.tlog
bitronix.tm.resource.configuration=${btm.root}/conf/resources.properties
</pre></td></tr></table>

<p>Finally, create an empty file named <code>resources.properties</code> under Tomcat's <code>conf/</code> directory.</p>

<h2>Step 3: Configure datasources that are transaction aware</h2>
<p>You have to put your datasources configurations in Tomcat's <code>conf/resources.properties</code> file. Here's an example of using BTM with a DataSource that implements javax.sql.XADataSource:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
resource.ds1.className=org.apache.derby.jdbc.EmbeddedXADataSource
resource.ds1.uniqueName=jdbc/mydatasource
resource.ds1.minPoolSize=0
resource.ds1.maxPoolSize=5
resource.ds1.driverProperties.databaseName=db1
resource.ds1.driverProperties.createDatabase=create
</pre></td></tr></table>

<p>This will create a <code>bitronix.tm.resource.jdbc.PoolingDataSource</code> that implements <code>javax.sql.DataSource</code> and interacts with the <code>javax.sql.XADataSource</code> provided in this instance by <a href="http://db.apache.org/derby">Derby</a>.</p>

<p>If your database vendor does not provide an <code>XADataSource</code>, you can use BTM's <code>bitronix.tm.resource.jdbc.lrc.LrcXADataSource</code> as the <code>XADataSource</code> to allow your database connections to be controlled by the transaction manager:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
resource.ds2.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
resource.ds2.uniqueName=jdbc/exampleNonXADS
resource.ds2.minPoolSize=0
resource.ds2.maxPoolSize=5
resource.ds2.driverProperties.driverClassName=org.apache.derby.jdbc.EmbeddedDriver
resource.ds2.driverProperties.url=jdbc:derby::db2;create=true
</pre></td></tr></table>

<p>Again, we've used <a href="http://db.apache.org/derby">Derby</a> as an example, but as the <code>LrcXADataSource</code> uses only the class name and url of a <code>java.sql.Driver</code>, you can use it with any database providing a JDBC driver.</p>

<h2>Step 4: Configure transaction manager and datasources initialization in your META-INF/context.xml</h2>
<p>In the web application where you want one or more datasource to be used, you have to create a <a href="http://tomcat.apache.org/tomcat-5.5-doc/config/context.html">META-INF/context.xml</a> file.</p>

&lt;Resource name="jdbc/mydatasource" auth="Container" type="javax.sql.DataSource"
        factory="bitronix.tm.resource.ResourceObjectFactory" uniqueName="jdbc/mydatasource" />

&lt;Resource name="jdbc/exampleNonXADS" auth="Container" type="javax.sql.DataSource"
        factory="bitronix.tm.resource.ResourceObjectFactory" uniqueName="jdbc/exampleNonXADS" />

&lt;Transaction factory="bitronix.tm.BitronixUserTransactionObjectFactory" />

&lt;/Context>
</pre></td></tr></table>

<p>The <code>&lt;Resource&gt;</code> tags will bind a <a href="http://btm.codehaus.org/api/1.2/bitronix/tm/resource/ResourceObjectFactory.html">bitronix.tm.resource.ResourceObjectFactory</a> object each, passing it a <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/Reference.html">javax.naming.Reference</a> containing a <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/StringRefAddr.html">javax.naming.StringRefAddr</a> containing the datasource's <code>uniqueName</code> as <code>addrType</code>.</p>

<table class="wysiwyg-macro" data-macro-name="info" data-macro-parameters="title=Tomcat specific" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm86dGl0bGU9VG9tY2F0IHNwZWNpZmljfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>This mechanism is internal to Tomcat. You do not have to worry about how it works, the <code>bitronix.tm.resource.ResourceObjectFactory</code> class will handle those details.</p></td></tr></table>

<p>The <code>bitronix.tm.resource.ResourceObjectFactory</code> class will return the datasource previously configured in in Tomcat's <code>conf/resources.properties</code> with the specified <code>uniqueName</code> when it is fetched from JNDI.</p>

<p>The <code>&lt;Transaction&gt;</code> tag will just bind the transaction manager at the standard JNDI location <code>java:comp/UserTransaction</code>.</p>

<h2>Step 5: Configure datasources references in your web.xml</h2>
<p>Before your code can access configured datasources via JNDI ENC URLs, you need to declare resource references in your <code>web.xml</code>:</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="XML" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6WE1MfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;?xml version="1.0" encoding="ISO-8859-1"?>
 &lt;!DOCTYPE web-app PUBLIC
	"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
	"http://java.sun.com/dtd/web-app_2_3.dtd">

&lt;web-app>
  &lt;resource-env-ref>
    &lt;resource-env-ref-name>jdbc/mydatasource&lt;/resource-env-ref-name>
    &lt;resource-env-ref-type>javax.sql.DataSource&lt;/resource-env-ref-type>
  &lt;/resource-env-ref>

&lt;resource-env-ref>
    &lt;resource-env-ref-name>jdbc/exampleNonXADS&lt;/resource-env-ref-name>
    &lt;resource-env-ref-type>javax.sql.DataSource&lt;/resource-env-ref-type>
  &lt;/resource-env-ref>
&lt;/web-app>
</pre></td></tr></table>

<p>Now you can perform JNDI lookups on those URLs to access the configured datasources:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
DataSource exampleNonXADS = ctx.lookup("java:comp/env/jdbc/exampleNonXADS");
DataSource mydatasource = ctx.lookup("java:comp/env/jdbc/mydatasource");
</pre></td></tr></table>
<p><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>