Original http://docs.codehaus.org/display/BTM/Tomcat13
These instructions have been verified against BTM 1.3.1.
Contents
- Step 1: copy the BTM jars
- Step 2: Configure BTM as the Transaction Manager
- Step 3: Configure datasources that are transaction aware
- Step 4: Configure Transaction Manager and datasources initialization in your META-INF/context. xml
- Step 5: Configure datasources references in your web. xml
Step 1: copy the BTM jars
Copy the following jars from the BTM distribution to the TomcatLIB/
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 10.3.2.1 so we copiedDerby. Jar
In Tomcat'sLIB/
Directory.
Step 2: Configure BTM as the Transaction Manager
Windows: create a file namedSetenv. bat
With the following commands under Tomcat'sBin/
Directory:
Set catalina_opts =-dbtm. Root = % catalina_home %-dbitronix. tm. Configuration = % catalina_home % \ conf \ btm-config.properties |
UNIX: create a file namedSetenv. Sh
With the following commands under Tomcat'sBin/
Directory:
Catalina_opts = & Quot;-dbtm. Root = $ catalina_home-dbitronix. tm. Configuration = $ catalina_home/CONF/btm-config.properties & quot" |
Now create a file namedBtm-config.properties
With the following properties under Tomcat'sConf/
Directory:
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 namedServer. xml
Under Tomcat'sConf/
Directory. Under this line:
<Listener classname = "Org. Apache. Catalina. mbeans. globalresourceslifecyclelistener" /> |
Add this one:
<Listener classname = "Bitronix. tm. Integration. tomcat55.btmlifecyclelistener" /> |
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 namedContext. xml
Under Tomcat'sConf/
Directory. Under this line:
<Watchedresource> WEB-INF/Web. xml </watchedresource> |
Add this one:
<Transaction factory = "Bitronix. tm. bitronixusertransactionobjectfactory" /> |
The<Transaction>
Tag will bind the Transaction Manager at the standard JNDI locationJava: COMP/usertransaction
.
Finally, create an empty file namedResources. Properties
Under Tomcat'sConf/
Directory.
Step 3: Configure datasources that are transaction aware
You have to put your CES configurations in Tomcat'sConf/resources. Properties
File. Here's an example of using BTM with a datasource that implements javax. SQL. xadatasource:
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 |
This will createBitronix. tm. Resource. JDBC. poolingdatasource
That implementsJavax. SQL. datasource
And interacts withJavax. SQL. xadatasource
Provided in this instance by derby.
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:
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 |
Again, we 've used Derby as an example, but asLrcxadatasource
Uses only the class name and URL ofJava. 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.
< 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 > |
The<Resource>
Tags will bind a bitronix. tm. Resource. resourceobjectfactory object each, passing it a javax. Naming. Reference containing a javax. Naming. stringrefaddr containing the datasource'sUniquename
AsAddrtype
.
|
Tomcat specific This mechanism is internal to Tomcat. You do not have to worry about how it works,Bitronix. tm. Resource. resourceobjectfactory Class will handle those details. |
TheBitronix. tm. Resource. resourceobjectfactory
Class will return the datasource previusly configured in Tomcat'sConf/resources. Properties
With the specifiedUniquename
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 yourWeb. 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:
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:
Usertransaction ut = (usertransaction) CTX. Lookup ( "Java: COMP/usertransaction" ); |