Deploying Theseus as an Apache Tomcat Servlet

Contents

1. Why on Earth would I want to do this?
2. What this document is not
3. Step-by-step details
4. Testing deployment

Apache Tomcat is an free, open-source implementation of a Java 2 Enterprise Edition (J2EE) "web container". A web container is a J2EE phrase for "a system for deploying web applications". Tomcat basically allows you to easily and quickly deploy Java applications as scalable, robust Web applications.

"Servlets" are special Java classes designed to handle HTTP Web requests (e.g., GET and POST). They can be written for an J2EE-compliant web application system (including Tomcat). Typically, one creates servlets that access other interesting Java functions/classes that have been written as a way to deploy those functions/classes to the Web. Thus, by embedding Theseus in a servlet, you can make your Theseus plan callable from the Web.

This document is not:

• a tutorial on how to write Java servlets. You will need to read and review the Tomcat documentation for that. This document will show you a quick and crude example of how to embed Theseus in a servlet, but it will not elaborate on the details of how a servlet works.

• a tutorial on "J2EE development and deployment elegance". Again, what follows is a very quick and crude example of how to get things to work. We leave the elegance to you,

The general steps involved are:

1. Download and install the Java SDK (not the same as JRE) and Apache Tomcat.
2. Edit the necessary Tomcat configuration files.
3. Write code for your Theseus servlet (relatively easy -- an example is provided below).
4. Deploy.

The requirements are:

• Windows 2000 (XP will probably also work, but this has not been verified).
• Enough disk space to install the necessary dependencies (about 100-200MB).
• Administrative access to the machine.
• Internet access.

We now describe the detailed steps below. Two words of warning before continuing:

• This process has been tested, but only somewhat. We are confident that it will work in nearly every case, but since we have not done much testing, we can't be 100% sure that you won't run into a problem. Thus, we recommend that you expect to run into a hitch or two along the way -- that way, if things work, you'll be pleasantly surprised.

• You should be fairly comfortable building and configuring Java applications. If you are new to Java, think twice before attempting to do this.

The detailed steps are:

1. Download and install the Java SDK 1.4 (latest version is 1.4.1) from the Sun website.
   Be very careful to download the SDK, not JRE.

2. Download and install Apache Tomcat 4.1 (latest version is 4.1.18) from the Apache web site.
   Note that you only need Tomcat, not anything else (not even Ant).

3. Set two environment variables to point to these installations:
   • JAVA_HOME
   • CATALINA_HOME (Catalina is the project name for Apache Jakarta Tomcat)

   You can do this in the catalina.bat file, but it is safer to put it in a separate .bat file and run this file before running Catalina.

4. Edit the $CATALINA_HOME/bin/setclasspath.bat file. You should modify the CLASSPATH setting to point to the theseus.jar in your release. For example:

   set CLASSPATH=%JAVA_HOME%\lib\tools.jar;c:\theseus\theseus310\lib\theseus.jar
   

5. Edit the $CATALINA_HOME/conf/server.xml file. This is the main configuration file that lets Tomcat know where your web application is and how it should be configured.
   • If you have Fetch Agent Runner already installed (likely), you will need to change the default Tomcat port. This is because Agent Runner assumes that it will handle all traffic on the default 8080 port. To change the default port for non-Agent Runner Tomcat requests, you should locate the following lines:

         <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
       port="8080" minProcessors="5" maxProcessors="75"
     

     Change the port setting from 8080 to 9090 (of course, any unused port will do, but we recommend 9090 for consistency across installations).

   • Next, locate the text "Tomcat Examples Context". Above this, add the following:

     <!-- Tomcat Theseus Context -->
     <Context path="/theseus" reloadable="true" docBase="theseus" debug="0">
     </Context>
     

   Note that by increasing the debugging level, you will see more information in $CATALINA_HOME/logs/localhost*log files.

6. Create the following directories:
   • $CATALINA_HOME/webapps/theseus
   • $CATALINA_HOME/webapps/theseus/html
   • $CATALINA_HOME/webapps/theseus/WEB-INF
   • $CATALINA_HOME/webapps/theseus/WEB-INF/classes

7. Edit a new file $CATALINA_HOME/webapps/theseus/WEB-INF/web.xml. This file describes configuration information about the Theseus web application.

8. Edit a new file $CATALINA_HOME/webapps/theseus/html/theseus-example.html. This HTML is the interface that users will use to trigger servlet execution.

9. Edit a new file $CATALINA_HOME/webapps/theseus/WEB-INF/classes/TheseusExample.java. This file demonstrates sample deployment of Theseus in a servlet, using the Theseus API.

10. Compile the two Java files above. When doing this, you will need to make sure that your CLASSPATH includes references to the Theseus libraries you need (such as theseus.jar) as well as the key Tomcat library $CATALINA/common/lib/servlet.jar, which implements the J2EE servlet interfaces (i.e., javax.servlet.*).

1. Start up Tomcat by doing the following:
   • cd $CATALINA_HOME/bin
   • catalina.bat run

2. Point your web browser to http://localhost:9090/theseus/html/theseus-example.html and click on the link.