5 Tomcat Example

JOTM can be integrated with Tomcat 4.1.x to provide distributed transactional acces to resources from Servlets or JSP.// As for the jdbc example, the Tomcat one can work with any database providing a JDBC driver. It uses XAPool to take care of the transactional behaviors and the pooling of JDBC objects.

5.1 Scenario

The scenario of the Tomcat is very simple. It is based on the example provided by Tomcat in their JNDI Datasource HOW-TO with the addition of some transaction code.

The user send a request to a JSP file (test.jsp) which asks to commit or rollback the incrementation of an integer stored in a database. The JSP delegates the JDBC and transaction code to a JavaBean (foo.DBTest class).

The code of foo.DBTest is simple:

• a JDBC Connection is created from a DataSource retrieved through JNDI
• a UserTransaction is also retrieved from JNDI
• a transaction is started
• the value of the integer foo which is stored in the database is read (SQL query)
• we increment the value of foo by 1 in the database (SQL update)
• depending of the choice of the user (commit or rollback), the transaction is either committed or rolled back
• we read once more foo value from the database (SQL query) and display it in the JSP.

5.2 Setup and compilation

5.2.1 Tomcat setup

The tomcat example uses Tomcat 4.1.18. It can be downloaded from http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.1.18/bin/.

There's no setup needed for Tomcat. You just have to unzip it to use it.

5.2.2 Database setup

The database setup for the Tomcat example is exactly the same than for the JDBC example. Please refer to the Database setup of the JDBC example.

You also need to copy the JDBC driver jar file of your database in the common/lib/ directory of Tomcat.

5.2.3 Compilation

In example/tomcat/ directory, type

$ ant war

to compile Java files and creates a WAR file (examples/tomcat/output/dbtest.war) containing your web application and all that is needed to use JOTM.

5.2.4 Deployment

Copy the output/dbtest.war file which has just been created to the webapps/ directory of Tomcat.

Also copy example/tomcat/dbtest.xml XML file to the webapps/ directory of Tomcat.
This files describes the context associated with your web application. In this file, you set the properties to access your database:

• driverClassName - Name of the JDBC driver
• url - URL to connect to the data base
• username - user login
• password - user password

By default, dbtest.xml is configured to use PostgreSQL as its database.
To use another database, you just have to change these properties (especially driverClassName and url).

This file also described the resource factories (JDBC and Transaction) used by your web application.

5.2.5 JOTM jar files

You also need to copy JOTM jar files so that Tomcat can see them.
Copy the following jars located in the lib/ directory of JOTM:

• jotm.jar
• jotm_jrmp_stubs.jar
• jonas_timer.jar
• carol.jar
• jta-spec1_0_1.jar
• jts1_0.jar
• commons-logging.jar
• log4j.jar
• objectweb-datasource.jar
• xapool.jar

They have to be placed on common/lib/ directory of Tomcat.

You've also to copy the file in config/

• trace.properties

You've have to created a file name carol.properties with the following properties:

# lmi stands for Local Method Invocation
carol.protocols=lmi

# do not use CAROL JNDI wrapper
carol.start.jndi=false

# do not start a name server
carol.start.ns=false

These files have to be placed in common/classes/ directory of Tomcat.

5.3 Run the example

Go to the bin/ directory of Tomcat and type

$ ./catalina.sh run

Use your favorite browser to go to the URL

http://localhost:8080/dbtest/test.jsp

Choose if you want to commit or rollback the incrementation of the value of the integer and click on the completion button.

If you've chosen commit, the integer value displayed on the page should have been incremented by one.
If you've chosen rollback, the integer value displayed on the page should be the same as before.

5.4 Integration of JOTM and Tomcat

For a more technical explanation on the integration of JOTM in Tomcat, please refer to the Tomcat/JOTM HOW-TO.