Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

How to use BTM as the transaction manager in Tomcat 6.x

These instructions have been verified against BTM 1.3.1.


Table of Contents

Step 1: Copy the BTM jars

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

  • btm-1.3.1.jar
  • geronimo-jta_1.0.1B_spec-1.0.1.jar
  • slf4j-api-1.5.2.jar
  • slf4j-jdk14-1.5.2.jar
  • btm-tomcat55-lifecycle.jar (it works with both Tomcat 5.5 and Tomcat 6)

You will also need to copy your JDBC driver's JAR file in that same folder. In this example, we've used Derby so we copied derby.jar in Tomcat's lib/ directory.

Step 2: Configure BTM as the transaction manager

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%\conf\

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

Code Block

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

Code Block${btm.root}/work/btm1.tlog${btm.root}/work/btm2.tlog${btm.root}/conf/

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="" />

The <Listener> tag will make sure BTM is started when Tomcat starts up and shutdown when Tomcat shuts down.

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

Code Block

add this one:

Code Block
<Transaction factory="" />

The <Transaction> tag will bind the transaction manager at the standard JNDI location java:comp/UserTransaction.

Finally, create an empty file named under Tomcat's conf/ directory.

Step 3: Configure datasources that are transaction aware

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

Code Block

This will create a that implements javax.sql.DataSource and interacts with the javax.sql.XADataSource provided in this instance by Derby.

If your database vendor does not provide an XADataSource, you can use BTM's as the XADataSource to allow your database connections to be controlled by the transaction manager:

Code Block

Again, we've used Derby as an example, but as the LrcXADataSource uses only the class name and url of a java.sql.Driver, you can use it with any database providing a JDBC driver.

Step 4: Configure transaction manager and datasources initialization in your META-INF/context.xml

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

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

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


The <Resource> tags will bind a object each, passing it a javax.naming.Reference containing a javax.naming.StringRefAddr containing the datasource's uniqueName as addrType.

titleTomcat specific

This mechanism is internal to Tomcat. You do not have to worry about how it works, the class will handle those details.

The class will return the datasource previously configured in in Tomcat's conf/ with the specified uniqueName when it is fetched from JNDI.

Step 5: Configure datasources references in your web.xml

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

Code Block
<?xml version="1.0" encoding="ISO-8859-1"?>
	"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"



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");