TOMCAT TUTOR

Introduction

Following is a summary of how you would install and configure Tomcat 4 for use as a standalone Web server that supports servlets 2.3 and JSP 1.2. Integrating Tomcat as a plugin within the regular Apache server or a commercial Web server is more complicated (for details, see http://jakarta.apache.org/tomcat/tomcat-4.0-doc/).

Integrating Tomcat with a regular Web server is valuable for a deployment scenario, but my goal here is to show how to use Tomcat as a development server on your desktop. Regardless of what deployment server you use, you'll want a standalone server on your desktop to use for development.

The examples here assume you are using Windows, but they can be easily adapted for Solaris, Linux, and other versions of Unix. I've gotten reports of successful use on MacOS X, but don't know the setup details. Except when I refer to specific Windows paths (e.g., C:\blah\blah), I use URL-style forward slashes for path separators (install_dir/webapps/ROOT). Adapt as necessary.

The information here is adapted from More Servlets and JavaServer Pages from Sun Microsystems Press. For the book table of contents, index, source code, and information on basic and advanced servlet and JSP short courses, please see http://www.moreservlets.com/. To report errors or omissions in this writeup, please contact Marty at hall@coreservlets.com.

Executive Summary

I give extremely detailed instructions in the following sections. If you're pretty experienced and just want a short summary, this section will probably be enough for you.

1. Install the JDK. Make sure you have JDK 1.3 or 1.4 installed.
2. Configure Tomcat.
   1. Download the software. Go to http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/ and download and unpack the zip file for the latest version.
   2. Change the port to 80. Edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80.
   3. Turn on servlet reloading. Edit install_dir/conf/server.xml and add a DefaultContext subelement to the main Service element and supply true for the reloadable attribute.
   4. Set the JAVA_HOME variable. Set it to refer to the base JDK directory, not the bin subdirectory.
   5. Change the DOS memory settings. If you get an "Out of Environment Space" error message when you start the server, right-click on install_dir/bin/startup.bat, select Properties, select Memory, and change the Initial Environment entry from Auto to at least 2816. Repeat the process for install_dir/bin/shutdown.bat.
   6. Set the CATALINA_HOME variable. Optionally, set CATALINA_HOME to refer to the top-level Tomcat installation directory.
3. Test the server.
   1. Verify that you can start the server. Double-click install_dir/bin/startup.bat and try accessing http://localhost/.
   2. Check that you can access your own HTML & JSP pages. Drop some simple HTML and JSP pages into install_dir/webapps/ROOT and access them with http://localhost/filename.
4. Set up your development environment.
   1. Create a development directory. Put it anywhere except within the Tomcat installation hierarchy.
   2. Make shortcuts to the Tomcat startup & shutdown Scripts. Put shortcuts to install_dir/bin/startup.bat and install_dir/bin/shutdown.bat in your development directory and/or on your desktop.
   3. Set your CLASSPATH. Include the current directory ("."), install_dir/common/lib/servlet.jar, and the main development directory.
   4. Bookmark the servlet & JSP javadocs. Add install_dir/webapps/tomcat-docs/servletapi/index.html to your bookmarks/favorites list.
5. Compile and test some simple Sservlets.
   1. Test a packageless servlet. Compile a simple servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes, and access it with http://localhost/servlet/ServletName.
   2. Test a servlet that uses packages. Compile the servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes/packageName, and access it with http://localhost/servlet/packageName.ServletName.
   3. Test a servlet that uses packages and utility classes. Follow the same procedure as the second step above. This third step verifies that the CLASSPATH includes the top level of your development directory.
6. Establish a simplified deployment method.
   1. Copy to a shortcut. Make a shortcut to install_dir/webapps/ROOT. Copy packageless .class files directly there. With packages, copy the entire directory there.
   2. Use the -d option of javac. Use -d to tell Java where the deployment directory is.
   3. Let your IDE take care of deployment. Tell your IDE where the deployment directory is and let it copy the necessary files.
   4. Use ant or a similar tool. Use the Apache make-like tool to automate copying of files.