Contents

Introduction

Order now

When the book went to print, only Tomcat 3.0 was available as an official release; Tomcat 3.1 was still in beta. Since then, Tomcat 3.1 and 3.2 have been officially released, and most readers now want to use Tomcat 3.2 or Tomcat 4. This page describes Tomcat 3.2; for Tomcat 4, please see http://www.moreservlets.com/Using-Tomcat-4.html (JRun, ServletExec and Resin continue to be other good free desktop alternatives, but the JSWDK and the Java Web Server are now obsolete).

So, following is a quick summary of how you would install and set up Tomcat 3.2 as a standalone servlet and JSP engine. Integrating Tomcat with the regular Apache server is more complicated. That is valuable for a deployment scenario, but my goal here is to show how to set it up 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. Please don't be intimidated by the length of these instructions; I go into very specific detail that is probably not necessary for most of you.

Installation and Configuration

1. Download Tomcat 3.2.
   Get it from http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/. You can also check http://jakarta.apache.org/site/binindex.html to see if there is a later version than 3.2.1. Windows users will probably want to download the zip file, but there are several other formats there as well (.tar, .hqx, etc.)
2. Unzip it.
   If you unzip into C:\, Tomcat gets installed in C:\jakarta-tomcat-3.2.1. From now on, I'll refer to the base installation directory (e.g., C:\jakarta-tomcat-3.2.1) as install_dir.
3. Change the port from 8080 to 80.
   Edit install_dir\conf\server.xml and change the line that says
     <Parameter name="port" value="8080"/> to
     <Parameter name="port" value="80"/>.
   This is optional, but if you have no other server already running on port 80, it will make it easier to enter URLs. I personally hate typing the port number all the time.
4. Modify the startup and shutdown scripts to specify TOMCAT_HOME.
   First, copy install_dir\bin\startup.bat to install_dir\bin\startup-orig.bat and copy install_dir\bin\shutdown.bat to install_dir\bin\shutdown-orig.bat.
   Next, edit startup.bat. After the line
       if not "%TOMCAT_HOME%" == "" goto start
   add the following two lines:
       set TOMCAT_HOME=C:\jakarta-tomcat-3.2.1
    if exist "%TOMCAT_HOME%\bin\tomcat.bat" goto start
   Note: if you prefer, you can just download my already-edited startup.bat file (R-click on the link and select "Save Link As" or "Save Target As"). If install_dir is someplace different than C:\jakarta-tomcat-3.2.1, you'll still have to edit this file.

   Make the same changes to shutdown.bat or download my already-edited shutdown.bat file.

5. Modify tomcat.bat to set JAVA_HOME and to ignore existing CLASSPATH.
   The server needs to know the location of the main Java install directory, since JSP needs the compiler. But, the compiler is not part of the standard library. Also, most people prefer Tomcat not pick up their development CLASSPATH. Otherwise, something might work in a development test case that fails in deployment. If the server's CLASSPATH is only the standard Tomcat one, the same code will work during development as during deployment. That is, the development code won't run unless you properly place it in the right deployment directories.

   First, replace this:

       if not "%JAVA_HOME%" == "" goto gotJavaHome
       echo You must set JAVA_HOME to point at your Java Development Kit installation
       goto cleanup
       :gotJavaHome
   	

   With this (replace C:\jdk1.3 with your top-level Java install directory):

       if not "%JAVA_HOME%" == "" goto gotJavaHome
       set JAVA_HOME=C:\jdk1.3
       REM echo You must set JAVA_HOME to point at your Java Development Kit installation
       REM goto cleanup
       :gotJavaHome
   	

   Or, if you prefer, you can download my already-edited tomcat.bat file.

   Second, after the line
       set _CLASSPATH=%CLASSPATH%
   add the following line:
       set CLASSPATH=
   Again, you can download my already-edited tomcat.bat file.

6. Make sure your PATH includes the JDK bin directory.
   JSP requires javac, not just java, so your PATH can't just include the JRE. I set my PATH to include C:\jdk1.3\bin. On Windows NT/2000 you set the PATH by going to the Start menu, selecting Settings, choosing System, then choosing Environment. On Windows 95/98/ME you probably put the setting in your autoexec.bat. General directions are in Chapter 1. For example, if you use an autoexec.bat, you would add the line:
       set PATH=C:\jdk1.3\bin;%PATH%
7. Make a development directory.
   Pick any place you want to use as the base location of your servlet and JSP code. You'll probably eventually make subdirectories that correspond to your package names. I use C:\Servlets+JSP. Once you create this directory, I strongly recommend you make shortcuts from that development directory to the following four locations. To make a shortcut, use the R-mouse to grab the file or directory you want to make a shortcut to, drag it to the location (e.g., C:\Servlets+JSP) you want to make a shortcut from, let go, and select "Make Shortcut".
   • install_dir\bin\startup.bat
     With this shortcut, you can just double click to start Tomcat
   • install_dir\bin\shutdown.bat
     With this shortcut, you can just double click to stop Tomcat
   • install_dir\webapps\ROOT\WEB-INF\classes
     You can drag package-less .class files onto this shortcut to deploy them. Even easier, you can copy complete package-specific subdirectories here to deploy servlets that are in classes. Just use the R-mouse to drag the directory onto the shortcut, let go, and select "Copy".
   • install_dir\webapps\ROOT
     You can drag HTML, JSP, GIF, JPEG, and CSS files here to deploy them. You can put them in directories if you want.
8. Update your CLASSPATH.
   Make sure it includes:
   • . (the current directory)
   • install_dir\lib\servlet.jar
   • install_dir\lib\jasper.jar
   • The top of your development directory's package hierarchy. For example, if your development directory is C:\Servlets+JSP, then your package-specific classes will go in C:\Servlets+JSP\packageName, but your CLASSPATH will include just C:\Servlets+JSP. This is no different from how you use packages in general in Java, and this is already described in the book (nothing changed with Tomcat 3.2). However, forgetting this step is one of the single most common problems with using servlets and JSP. For example, if you use an autoexec.bat, you would add the following. Note that this would really all be on one line; I'm just adding line breaks after the semicolons to make it readable in the Web page. There should be no spaces in the line!

               set CLASSPATH=.;
                             C:\jakarta-tomcat-3.2.1\lib\servlet.jar;
                             C:\jakarta-tomcat-3.2.1\lib\jasper.jar;
                             C:\Servlets+JSP
     		  

1. Start the server.
   Double click on startup.bat (or the shortcut to it that is in your development directory). If you get an error message when starting the server regarding "Out of Environment Space", then you should R-click on startup.bat, select Properties, select Memory, and then find the entry (top right) that says "Initial Environment". Change the value to 2816 and hit the "OK" button. Repeat for shutdown.bat. Then try again.
2. Test the server.
   Start a browser and enter http://localhost/ as the URL. You should get a Tomcat home page. Click on a couple of the JSP examples to verify that the server can find the Java compiler.
3. Compile and install your servlet classes.
   The .class files go in install_dir\webapps\ROOT\WEB-INF\classes or install_dir\webapps\ROOT\WEB-INF\classes\yourPackage. I highly recommend making a shortcut to one of these directories within your development directory. Then, every time you compile package-less, Java classes, just drag the .class files onto the shortcut to install them. To install Java classes that are in packages (almost all should be!), just use your R-mouse to drag the entire directory onto the shortcut, let go, and select "Copy". You can also use a script (e.g., ant), the -D option to javac, or your IDE's deployment directory setting. These options will install the .class files automatically, as described in the book. If you know about defining your own Web applications, you can change the install location. But that is not worth bothering with when first starting out, IMHO.

   I recommend starting out with the simple HelloWWW example of Chapter 2 (see the code at http://archive.coreservlets.com).

4. Test your servlet classes.
   Use a URL of http://localhost/servlet/ServletName or http://localhost/servlet/yourPackage.ServletName. This is the same as described in the book.
5. Install your HTML and JSP files.
   These go in install_dir\webapps\ROOT or install-dir\webapps\ROOT\yourDirectory. Again, I recommend making a shortcut to this directory from whatever directory you use for your original HTML and JSP files, and then just drag them over to copy. (Use the right mouse and select "Copy" -- I actually copy entire subdirectories over each time.)
6. Test your HTML and JSP files.
   Use a URL of http://localhost/yourFileName or http://localhost/yourDirectory/yourFileName
7. Use Tomcat for all the book examples.
   All the code from every example in the book is online. Feel free to use it for any purpose you want.
8. Have fun and start programming.
   When you become a CEO of an e-commerce company, will you let me buy stock at your IPO price?

More Information

Servlet and JSP short courses. Both on-site courses (at your company) and open enrollment courses are available. Order from amazon.com. 30% off. Free examination copies for instructors. You can also get a copy of the course materials from my servlet and JSP courses.

Reader reviews. Table of contents. Also available in PDF. Index. Adobe acrobat (PDF) format. API for all code. Javadoc format.