Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

These instructions have been verified against BTM 2.1.0.

Contents

Table of Contents
maxLevel3
minLevel2

Step 1: Copy the BTM jars

Copy the following jars from the BTM distribution to the Tomcat lib/ directory:

  • btm-2.1.0.1.jar
  • jta-1.1.jar
  • slf4j-api-1.6.0.jar
  • slf4j-jdk14-1.6.0.jar
  • btm-tomcat55-lifecycle-2.1.0.jar (it works with both Tomcat 5.5 and Tomcat 6)

...

Windows: Create a file named setenv.bat with the following commands under Tomcat's bin/ directory:

Code Block

set CATALINA_OPTS=-Dbtm.root=%CATALINA_HOME% -Dbitronix.tm.configuration=%CATALINA_HOME%\conf\btm-config.properties

Unix: Create a file named setenv.sh with the following commands under Tomcat's bin/ directory:

Code Block

CATALINA_OPTS="-Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties"

Now create a file named btm-config.properties with the following properties under Tomcat's conf/ directory:

Code Block

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

Then edit the file named server.xml under Tomcat's conf/ directory. Under this line:

Code Block

<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

add this one:

Code Block

<Listener className="bitronix.tm.integration.tomcat55.BTMLifecycleListener" />

...

The next step is to edit the file named context.xml under Tomcat's conf/ directory. Under this line:

Code Block

<WatchedResource>WEB-INF/web.xml</WatchedResource>

add this one:

Code Block

<Transaction factory="bitronix.tm.BitronixUserTransactionObjectFactory" />

...

You have to put your datasources configurations in Tomcat's conf/resources.properties file. Here's an example of using BTM with a DataSource that implements javax.sql.XADataSource:

Code Block

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=../work/db1
resource.ds1.driverProperties.createDatabase=create

...

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

Code Block

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:../work/db2;create=true

...

In the web application where you want one or more datasource to be used, you have to create a META-INF/context.xml file.

Code Block
XML
XML

<Context>

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

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

</Context>

...

Before your code can access configured datasources via JNDI ENC URLs, you need to declare resource references in your web.xml:

Code Block
XML
XML

<?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE web-app PUBLIC
	"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
	"http://java.sun.com/dtd/web-app_2_3.dtd">

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

  <resource-env-ref>
    <resource-env-ref-name>jdbc/exampleNonXADS</resource-env-ref-name>
    <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
  </resource-env-ref>
</web-app>

Now you can do JNDI lookups on those URLs to access the configured datasources:

Code Block

DataSource exampleNonXADS = (DataSource) ctx.lookup("java:comp/env/jdbc/exampleNonXADS");
DataSource mydatasource = (DataSource) ctx.lookup("java:comp/env/jdbc/mydatasource");

and you can do JNDI lookups on this URL to access the transaction manager:

Code Block

UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");

...