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
5. Notes on 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 provide a simple example of how to embed Theseus in a servlet, but it will not elaborate on the details of how a servlet works or the optimal way to embed Theseus.

• a tutorial on "J2EE development and deployment elegance". That's something we leave for you.

The general steps involved are:

1. Download and install the Java SDK (not the same as JRE)
2. Downlaod and install Apache Tomcat.
3. Write a new web application that uses the Theseus API to run plans. A simple example of this is provided below.
4. Fire up Tomcat and test everything out.

The requirements are:

• Windows XP (other versions will probably also work, but this has not been verified).
• Enough disk space to install Java, Tomcat and all of the necessary dependencies (about 100-150MB, the new web application itself requires less than 10MB including libraries).
• Administrative access to the machine.
• Internet access.

The specific installation steps are:

1. Download and install the Java SDK 1.4.2 (we tested on 1.4.2_06) from the Sun website. Do not install Java 1.5. Theseus has not been tested with Java 1.5. Be very careful to download the SDK, not JRE.

2. Download and install Apache Tomcat 5.0.x (we tested on 5.0.28) from the Apache web site. Note that you only need Tomcat, not anything else (not even Ant). Do not install Tomcat 5.5. Theseus has not been tested with Tomcat 5.5.

3. Edit the $CATALINA_HOME/conf/server.xml file. (NOTE: CATALINA is the name of the Tomcat servlet container and the name used in most Tomcat configuration files, so we use it here). 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 port="8080" maxThreads="150" minSpareThreads="25"
           maxSpareThreads="75" enableLookups="false" redirectPort="8443"
           acceptCount="100" debug="0" connectionTimeout="20000"
           disableUploadTimeout="true" />
     

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

4. Download the sample Theseus web application, theseus-blank, and unzip it so that its root folder is located under the $CATALINA_HOME/webapps folder. Let's call the folder $CATALINA_HOME/webapps/theseus-blank "$THESEUS_BLANK" going forward.

5. Copy all of the JAR files in their normal theseus350/lib to $THESEUS_BLANK/WEB-INF/lib (replace the "350" with whatever version of Theseus you're using).

   IMPORTANT: make sure that, after you copy the files, you remove the "Archive" bit on them. To do that, you should (a) select all of the JAR files (in Windows Explorer), (b) right click and choose "Properties". Then, (c) near the "Attributes:" part, click on the "Advanced" button and turn off the "File is ready for archiving" option.

6. Look at the $THESEUS_BLANK/WEB-INF/classes/compile.bat file to double check that all of the JAR file names are correct (this should normally be the case, but in case you're working with a different version of Theseus or some of the dependent libs have changed, it's good to ensure that compile.bat is correct).

7. Edit the $THESEUS_BLANK/WEB-INF/classes/TheseusServlet.java file and change THESEUS_PROPERTIES_FILE to the correct location of Theseus.properties on your machine.

8. Compile the servlet by running the compile.bat script from a DOS prompt.

1. Start up Tomcat. There are a number of ways to do this, but one is to start the "Monitor Tomcat" application (included with Tomcat, look under Start/Programs/Apache Tomcat 5.0/Monitor Tomcat). You will see a new icon in the system tray. Double click on it, to load the application to the foreground, and then click on "Start" to start everything up.

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

After testing deployment, you should feel ready to create your own application(s). When doing that, the suggsted strategy is to NOT create your project in $THESEUS_BLANK. Leave that folder alone as a reference. Instead, simply copy webapps/theseus-blank to webapps/myproject (or whatever), and edit the WEB-INF/web.xml and WEB-INF/classes/compile.bat as necessary. These are the only two files you should have to change.

Following the deployment strategy outlined above should be fine for most cases. However, here is a list of additional notes that may help you address any additional problems that you might encounter:

• Running out of memory:It is possible for you to exhaust memory if you have a large, data-intensive plan. The main problem is that servlets run as child threads of the main engine (Tomcat) and thus inherit any settings given to it as far as the way that Java uses available memory. For example, if you specify that the Java options to starting up Tomcat should include one specifying how garbage collection is to be done, your servlet will also be subject to that setting. So, if you want to increase the max memory allowed for Tomcat (and thus your plan), you need to specify the Java -Xmx setting in the setclasspath.bat or catalina.bat file. For example, to set the maximum memory to 200MB, you would set the JAVA_OPT (or CATALINA_OPT) value to include -Xmx200M.

• Cannot find your URL: If you deploy Tomcat on a different port than the default for HTTP traffic (80), most browsers will require you to have an "http://" prefix to your request. So, if you're having trouble locating your servlet/html page from Tomcat, make sure that you've prefixed your request properly and added the proper suffix (8080 or 9090, as suggested here).