##################
#                #
# Tomcat example #
#                #
##################

# $Id$

Scenario:
---------

The Tomcat example shows how to integrate and use JOTM with Tomcat 5.0 to provide
Transaction support to Servlets.

For more information, on how to configure the Database, JOTM and
Tomcat, please refer to the Examples guide[1] of JOTM

[1] http://www.objectweb.org/jotm/doc/index.html

Setup:
------

o JOTM is the Transaction Manager
o Tomcat 5.0 is the Servlet container
o A database (javatest):
	- MySQL
	- PostgreSQL

Database Setup:
---------------

The database setup is the same as the JDBC example (see
examples/jdbc/README.txt for more information)

Compilation:
------------

Set JOTM_HOME to the examples/tomcat directory of your JOTM distribution (e.g.,
.../jotm/output/dist/examples/tomcat (JOTM_HOME/examples/tomcat) from CVS)


Then, in this directory type 

    ant compile

to compile the example (generated files are put in the JOTM_HOME/examples/tomcat/output and src directories)
---------------------------------------------------------------------------------------------------

To run the example:
----------------

1. Create the Web application

   o in the JOTM_HOME/examples/tomcat directory, type

      ant war

     this creates a war file (dbtest.war) in the JOTM_HOME/examples/tomcat/output/ directory

2. Add the JDBC driver to Tomcat

   Download the JDBC driver corresponding to your database and copy it
   to the $CATALINA_HOME/common/lib/ directory
-----------------------------------------------------------------------------------------------------

   NOTE: you may need to modify DBTest.xml to utilize the MYSQL JDBC driver. DBTest.xml defaults to PostgreSQL. To work
         with MYSQL, uncomment the MYSQL <parameter> section.
------------------------------------------------------------------------------------------------------
3. Copy JOTM files

	From JOTM_HOME/lib/ directory, copy the following jar files to $CATALINA_HOME/common/lib/ :
		o jotm.jar
    	o jotm_jrmp_stubs.jar
    	o jonas_timer.jar (optional)
    	o ow_carol.jar
    	o jta-spec1_0_1.jar
    	o jts1_0.jar
    	o objectweb-datasource.jar
    	o xapool.jar
        o howl.jar
        o commons-cli-1.0.jar
        o connector-1_5.jar
        o mysql-connector-java-X.X.X-bin.jar (X = value of downloaded connector JAR file)

	Create a file named carol.properties in $CATALINA_HOME/common/classes/ with the following properties:
		carol.rmi.activated = lmi
		carol.jndi.start = false
		carol.ns.start = false
------------------------------------------------------------------------------------------------------

4. Deploy the web application

   o Copy the file JOTM_HOME/examples/tomcat/dbtest.xml to $CATALINA_HOME/webapps/ and 
     $CATALINA_HOME/conf/catalina/localhost directories of Tomcat (this sets the context 
     corresponding to the web application)
     

   o copy the file JOTM_HOME/examples/tomcat/output/dbtest.war to the webapps/ directory of
   Tomcat
--------------------------------------------------------------------------------------------------------

5. Start Tomcat

   o in the $CATALINA_HOME/bin/ directory of Tomcat, type

     UNIX:

     $ ./catalina.sh run

     WINDOWS:

     startup (startup.bat runs catalina.bat)
        NOTE: be sure JAVA_HOME is set to the JDK in windows environment
----------------------------------------------------------------------------------------------------------

6. Browse the example

   o go in your browser to the URL

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

   o choose if you wnat to commit or rollback the transaction:
     o if you choose "commit", the integer value stored in the database is
       incremented
     o if you choose "rollback", the value in the database does not change


Enjoy!
