Configuring & Using Apache Tomcat

A Tutorial on Installing and Using
Tomcat 4 or 5 for Servlet and JSP Development


Note: writeup is very old, and covers now-obsolete Tomcat versions 4.0 and 5.0. For a newer writeup that covers more recent Tomcat versions, please see the Apache Tomcat 6 and 7 tutorials.


Training Courses: JSP, Servlets, JSF 2.0, Ajax, GWT, & Java 6

Programming with
Servlets & JSP

Rich Internet Apps
with Ajax & jQuery

JSF 2.0

Java 6
Programming

Customized Onsite Training
Courses at Your Location


Contents

Introduction

Following is a guide to installing and configuring Apache Tomcat for use as a standalone Web server (for development) that supports servlets 2.3 and JSP 1.2 (Tomcat 4) or servlets 2.4 and JSP 2.0 (Tomcat 5). (Note: Tomcat is sometimes referred to as "Jakarta Tomcat" since the Apache Java effort is known as "The Jakarta Project").

Integrating Tomcat as a plugin within the regular Apache server or a commercial Web server (for deployment) is more complicated that what is described here. Although such integration is valuable for a deployment scenario (see http://jakarta.apache.org/tomcat/tomcat-5.0-doc/), 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 many 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 (e.g., install_dir/webapps/ROOT). Adapt as necessary.

The information here is adapted from the introductory setup and configuration chapter of Core Servlets and JavaServer Pages, 2nd Edition, Volume 1 from Sun Microsystems Press and Prentice Hall. For the book table of contents, index, source code, etc., please see http://volume1.coreservlets.com/. For information on servlets, JSP, Apache Struts, JSF, and Java training courses (either at public venues or on-site at your company) taught by the author of the book and this Tomcat tutorial, please see http://courses.coreservlets.com. To report errors or omissions in this writeup or to inquire about on-site training courses on servlets/JSP/Struts/JSF/Java, please contact Marty Hall at hall@coreservlets.com.

Executive Summary

JSP, Servlet, Struts, & JSF Training
Looking for hands-on training? Tired of inexperienced instructors teaching someone else's course materials? Want a choice of public or onsite courses? Check out courses.coreservlets.com.
Distinctive features:
  • Personally developed and taught by Marty Hall, an experienced developer, award-winning instructor, 4-time JavaOne speaker, and author of Core Servlets and JSP, More Servlets and JSP, and this Tomcat tutorial.
  • Available onsite at your organization or at public venues.
  • Well-tested, having been used by Marty for courses for dozens of clients in the USA, Canada, Australia, Japan, Puerto Rico, India, and the Philippines.
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. You can also download preconfigured Tomcat versions that incorporate all of the modifications of this tutorial and include sample development directories, shortcuts, and autoexec.bat files.

  1. Install the JDK. Make sure JDK 1.3 or 1.4 is installed and your PATH is set so that both "java -version" and "javac -help" give a result.
  2. Configure Tomcat.
    1. Download the software. Go to http://jakarta.apache.org/site/binindex.cgi and download and unpack the zip file for the current release build of Tomcat 4 or 5. Also see the preconfigured Tomcat versions.
    2. Set the JAVA_HOME variable. Set it to refer to the base JDK directory, not the bin subdirectory.
    3. Enable the ROOT context. Edit install_dir/conf/server.xml and uncomment this line: <Context path="" docBase="ROOT" debug="0"/>. Not necessary in Tomcat 4.0.3 and earlier. In most versions of Tomcat 5, the element is missing the trailing slash and you need to add it.
    4. Turn on servlet reloading. Edit install_dir/conf/server.xml and add the following just above the entry for the ROOT context from the previous step:
      <DefaultContext reloadable="true"/>
    5. Change the port to 80. Edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80.
    6. Enable the invoker servlet. Go to install_dir/conf/web.xml (not .../server.xml) and uncomment the servlet and servlet-mapping elements that map the invoker servlet to /servlet/*. In Tomcat 4, you only need to uncomment the servlet-mapping element, and this is not necessary at all prior to Tomcat 4.1.12.
    7. Change the DOS memory settings. If you are on Windows 98/Me and 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. Not necessary on recent version of Windows.
    8. Set the CATALINA_HOME variable. Optionally, set CATALINA_HOME to refer to the top-level Tomcat installation directory. Not necessary unless you copy the startup scripts instead of making shortcuts to them.
  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 ("."), the servlet/JSP JAR file(s) (install_dir/common/lib/servlet.jar for Tomcat 4, install_dir/common/lib/servlet-api.jar and install_dir/common/lib/jsp-api.jar for Tomcat 5) and your main development directory from Step 1.
    4. Bookmark the servlet & JSP javadocs. Add install_dir/webapps/tomcat-docs/servletapi/index.html (Tomcat 4 and 5) and install_dir/webapps/tomcat-docs/jspapi/index.html (Tomcat 5 only) to your bookmarks/favorites list.
  5. Compile and test some simple servlets.
    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.

Install the JDK

Your first step is to download and install Java. The servlet 2.3 specification (JSP 1.2) requires JDK 1.2 or later; the servlet 2.4 spec (JSP 2.0) requires JDK 1.3 or later; J2EE 1.4 (which includes servlets 2.4 and JSP 2.0) requires JDK 1.4 or later. I recommend you simply get the latest Java version: JDK 1.4. See the following sites for download and installation information.

Once you've installed Java, confirm that everything including your PATH is configured properly by opening a DOS window and typing "java -version" and "javac -help". You should see a real result both times, not an error message about an unknown command. Or, if you use an IDE, compile and run a simple program to confirm that the IDE knows where you installed Java.

Configure Tomcat

JSP, Servlet, Struts, & JSF Training
Looking for hands-on training? Tired of inexperienced instructors teaching someone else's course materials? Want a choice of public or onsite courses? Check out courses.coreservlets.com.
Distinctive features:
  • Personally developed and taught by Marty Hall, an experienced developer, award-winning instructor, 4-time JavaOne speaker, and author of Core Servlets and JSP, More Servlets and JSP, and this Tomcat tutorial.
  • Available onsite at your organization or at public venues.
  • Well-tested, having been used by Marty for courses for dozens of clients in the USA, Canada, Australia, Japan, Puerto Rico, India, and the Philippines.
Configuring Tomcat involves nine steps:

  1. Downloading the Jakarta Tomcat software.
  2. Setting the JAVA_HOME variable.
  3. Enabling the ROOT context.
  4. Telling Tomcat to reload servlets when they are modified.
  5. Changing the port from 8080 to 80.
  6. Enabling the invoker servlet
  7. Changing the DOS memory settings. (Win98/Me only)
  8. Setting the CATALINA_HOME variable. (Optional)
  9. Using a preconfigured version of Tomcat with these changes already made. (Optional)
  10. Using the Windows .exe installer instead of the .zip file (Not Recommended)
Details of each step are given below. If Tomcat is already running, restart it after performing these steps.

1. Download the Apache Tomcat Software

Go to http://jakarta.apache.org/site/binindex.cgi and download the zip file for the current release build of Tomcat 4 (JSP 1.2; servlets 2.3) or Tomcat 5 (JSP 2.0; servlets 2.4). Save the zip file on your PC and unzip it into a location of your choice. You specify the top-level directory (e.g., C:\) and the zip file has embedded subdirectories (e.g., jakarta-tomcat-4.1.29 or jakarta-tomcat-5.0.27). Thus, C:\jakarta-tomcat-4.1.29 is a common resultant installation directory for Tomcat 4. Note: from this point forward, I'll refer to that location as install_dir. For Windows, there is also a .exe installer; I prefer the .zip file, but see the .exe installer section for notes on the differences between the two.

Alternatively, you can use my preconfigured Tomcat versions. These versions already have the port changed to 80, servlet reloading enabled, and the invoker servlet turned on. The preconfigured versions also come with a sample development directory and autoexec.bat file.

2. Set the JAVA_HOME Variable

Next, you must set the JAVA_HOME environment variable to tell Tomcat where to find Java. Failing to properly set this variable prevents Tomcat from handling JSP pages. This variable should list the base JDK installation directory, not the bin subdirectory. For example, if you are on Windows 98/Me and installed the JDK in C:\j2sdk1.4.2_05 on your C drive, you might put the following line in your C:\autoexec.bat file.

  set JAVA_HOME=C:\j2sdk1.4.2_05
On Windows XP, you could also go to the Start menu, select Control Panel, choose System, click on the Advanced tab, press the Environment Variables button at the bottom, and enter the JAVA_HOME variable and value directly. On Windows 2000 and NT, you do Start, Settings, Control Panel, System, then Environment. If you prefer, you can use C:\autoexec.bat on those versions of Windows also (unless a system administrator has set your PC to ignore it).

3. Enable the ROOT Context.

The ROOT context is the default Web application in Tomcat, and is convenient to use when you are first learning about servlets and JSP (although you'll use your own Web applications once you're more experienced; see Section 2.11 of the book for details). The default Web application is already enabled in Tomcat 3, Tomcat 4.0.1-4.0.3, some versions of Tomcat 4.1, and Tomcat 5.0.20 and later. Skip this step if you are using the latest version of Tomcat 5, or my preconfigured Tomcat versions. But, in the versions in between (Tomcat 4.1.12 through 5.0.19), it is disabled by default. To enable it in those versions, make a backup copy of the original version of install_dir/conf/server.xml, then uncomment the following line:
  <Context path="" docBase="ROOT" debug="0"/>
Note that in most early versions of Tomcat 5, the commented out entry distributed with Apache Tomcat is in error: it is missing the trailing slash (i.e., <Context ... debug="0" > instead of the proper <Context ... debug="0" />). So, you will need to insert the slash. You can also:

4. Turn on Servlet Reloading

The next step is to tell Tomcat to check the modification dates of the class files of requested servlets and reload ones that have changed since they were loaded into the server's memory. This slightly degrades performance in deployment situations, so is turned off by default. However, if you fail to turn it on for your development server, you'll have to restart the server every time you recompile a servlet that has already been loaded into the server's memory. Since this tutorial discusses the use of Tomcat for development, this change is strongly recommended.

To turn on servlet reloading, edit install_dir/conf/server.xml and add a DefaultContext subelement to the main Host (Tomcat 5.0.20 and later) or Service (Tomcat 5.0.19 and earlier) element and supply true for the reloadable attribute. For example, in Tomcat 5.0.27, search for this entry:

        <Host name="localhost" debug="0" appBase="webapps" 
                                                            ...>
and then insert the following immediately below it:
        <DefaultContext reloadable="true"/> 
Be sure to make a backup copy of server.xml before making the above change. You can also:

5. Change the Port to 80

Assuming you have no other server already running on port 80, you'll find it convenient to configure Tomcat to run on the default HTTP port (80) instead of the out-of-the-box port of 8080. Making this change lets you use URLs of the form http://localhost/blah instead of http://localhost:8080/blah. Note that you need admin privileges to make this change on Unix. Also note that some versions of Windows XP automatically start IIS on port 80. So, if you use XP and want to use port 80 for Tomcat, you may need to disable IIS (see the Administrative Tools section of the Control Panel).

To change the port, edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80, yielding a result similar to that below. Note that the exact form of the Connector element varies in different Tomcat versions. Just search for a non-comment occurrence of "8080".

    <Connector port="80" ...
      maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
      ...
    ... />
You can also:

6. Enable the Invoker Servlet

The invoker servlet lets you run servlets without first making changes to your Web application's deployment descriptor (i.e., the WEB-INF/web.xml file). Instead, you just drop your servlet into WEB-INF/classes and use the URL http://host/servlet/ServletName (or http://host/webAppName/servlet/ServletName once you start using your own Web applications; see Section 2.11 of the book for details on Web apps). The invoker servlet is extremely convenient when you are learning and even when you are doing your initial development. But, as discussed in the book, you do not want it on at deployment time. Up until Apache Tomcat 4.1.12, the invoker was enabled by default. However, a security flaw was uncovered whereby the invoker servlet could be used to see the source code of servlets that were generated from JSP pages. Although this may not matter in most cases, it might reveal proprietary code to outsiders, so, as of Tomcat 4.1.12, the invoker was disabled by default. The Jakarta project has since fixed the problem, but they still disable the invoker servlet by default. You almost certainly want to enable it when learning, but you should disable it again before deploying any real applications.

To enable the invoker servlet, uncomment the following servlet and servlet-mapping elements in install_dir/conf/web.xml. Note that the filename is web.xml, not server.xml as in the previous bullets. Also, do not confuse this Apache Tomcat-specific web.xml file with the standard one that goes in the WEB-INF directory of each Web application. Finally, remember to make a backup copy of the original version of this file before you make the changes.

    <servlet>
        <servlet-name>invoker</servlet-name>
        <servlet-class>
          org.apache.catalina.servlets.InvokerServlet
        </servlet-class>
        ...
    </servlet>

    ...

    <servlet-mapping>
        <servlet-name>invoker</servlet-name>
        <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping>
You can also:

7. Change DOS Memory Settings (Win 98/Me Only)

If you use Windows 98/Me, you may also have to change the DOS memory settings for the startup and shutdown scripts. If you get an "Out of Environment Space" error message when you start the server, you will need to 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. This step is not necessary in more recent versions of Windows.

8. Set the CATALINA_HOME Variable (Optional)

If you are going to make copies of the Tomcat startup or shutdown scripts, it is also helpful to set the CATALINA_HOME environment variable to refer to the top-level directory of the Apache Tomcat installation (e.g., C:\jakarta-tomcat-5.0.27). This variable identifies the Tomcat installation directory to the server. However, if you are careful to avoid copying the server startup scripts and you use only shortcuts (called "symbolic links" on Unix/Linux) instead, you are not required to set this variable. I recommend using shortcuts and not bothering with CATALINA_HOME.

9. Using the Preconfigured Tomcat Versions (Optional)

Please see the separate section on installing Tomcat versions with all changes already made.

10. Using the Windows .exe Installer

If you are using Microsoft Windows, you can download a .exe installer instead of the .zip file discussed in this tutorial. In my opinion, it is not worth the bother to do so, but some people like it. If you use it, note these differences:

Test the Server

JSP, Servlet, Struts, & JSF Training
Looking for hands-on training? Tired of inexperienced instructors teaching someone else's course materials? Want a choice of public or onsite courses? Check out courses.coreservlets.com.
Distinctive features:
  • Personally developed and taught by Marty Hall, an experienced developer, award-winning instructor, 4-time JavaOne speaker, and author of Core Servlets and JSP, More Servlets and JSP, and this Tomcat tutorial.
  • Available onsite at your organization or at public venues.
  • Well-tested, having been used by Marty for courses for dozens of clients in the USA, Canada, Australia, Japan, Puerto Rico, India, and the Philippines.
Testing the server involves two steps:

  1. Verifying that the server can even start.
  2. Checking that you can access your own HTML and JSP pages.

1. Verify That the Server Can Start

Before trying your own servlets or JSP pages, you should make sure that the server is installed and configured properly. For Tomcat, click on install_dir/bin/startup.bat (or execute install_dir/bin/startup.sh on Unix/Linux). Next, enter the URL http://localhost/ in your browser and make sure you get the Tomcat welcome page, not an error message saying that the page could not be displayed or that the server could not be found. If you chose not to change the port number to 80 as described above, you will need to use a URL like http://localhost:8080/ that includes the port number.

If this does not work, there are a couple of things to check:

To halt the server, double click on install_dir/bin/shutdown.bat. I recommend that you make shortcuts to (not copies of) the startup and shutdown scripts and place those shortcuts on the desktop or in your main development directory.

2. Try Some Simple HTML and JSP Pages

After you have verified that the server is running, you should make sure that you can install and access simple HTML and JSP pages. This test, if successful, shows two important things. First, successfully accessing an HTML page shows that you understand which directories should hold HTML and JSP files. Second, successfully accessing a new JSP page shows that the Java compiler (not just the Java virtual machine) is configured properly.

Eventually, you will almost certainly want to create and use your own Web applications (see Section 2.11 of the book), but for initial testing many people prefer to use the default Web application. With Tomcat and the default Web application, you put HTML and JSP pages in install_dir/webapps/ROOT or install_dir/webapps/ROOT/somePath and access them with http://localhost/filename or http://localhost/somePath/filename. Note that some Tomcat versions create install_dir/webapps/ROOT only when the server is first run. So, you must start the server as described above before trying to access the directory.

For your first tests, I suggest you simply take Hello.html and Hello.jsp and drop them into the appropriate locations. Right click on the links to download these two files to your system. If you download the files using Internet Explorer, just be careful that it does not try to change the file extension, yielding Hello.htm instead of Hello.html. The code for these files, as well as all the code from the book, is available online at http://volume1.coreservlets.com. That Web site also contains book updates, additions, information on servlet and JSP short courses, and the full text of the first edition of Core Servlets and JavaServer Pages (in PDF).

If you put the files in the top-level directory of the default Web application (i.e., in install_dir/webapps/ROOT), access them with the URLs http://localhost/Hello.html and http://localhost/Hello.jsp, respectively. If you put them in a subdirectory of install_dir/webapps/ROOT, use the URLs http://localhost/directoryName/Hello.html and http://localhost/directoryName/Hello.jsp, respectively.

If you successfully started the server as described above, but neither the HTML file nor the JSP file works (e.g., you get File Not Found--404--errors), you likely are using the wrong directory for the files or you forgot to enable the ROOT context. If the HTML file works but the JSP file fails, you probably have incorrectly specified the base JDK directory (i.e., with the JAVA_HOME variable).

Set Up Your Development Environment

The server startup script automatically sets the server's CLASSPATH to include the standard servlet and JSP classes and the WEB-INF/classes directory (containing compiled servlets) of each Web application. But you need similar settings, or you will be unable to compile servlets in the first place. Configuring your system for servlet development involves the following four steps:

  1. Creating a development directory
  2. Making shortcuts to the Tomcat startup and shutdown scripts
  3. Setting your CLASSPATH
  4. Bookmarking the servlet & JSP javadocs
Details on each step are given below.

1. Create a Development Directory

The first thing you should do is create a directory in which to place the servlets and JSP pages that you develop. This directory can be in your home directory (e.g., C:\Documents and Settings\Your Name\My Documents\Servlets+JSP on Windows 2000) or in a convenient general location (e.g., C:\Servlets+JSP). It should not, however, be in the Tomcat deployment directory (e.g., anywhere within install_dir/webapps).

Eventually, you will organize this development directory into different Web applications (each with a common structure--see Section 2.11 of the book for details). For initial testing of your environment, however, you can just put servlets either directly in the development directory (for packageless servlets) or in a subdirectory that matches the servlet package name. Many developers simply put all their code in the server's deployment directory (within install_dir/webapps). I strongly discourage this practice and instead recommend one of the approaches described in the deployment section. Although developing in the deployment directory seems simpler at the beginning since it requires no copying of files, it significantly complicates matters in the long run. Mixing locations makes it hard to separate an operational version from a version you are testing, makes it difficult to test on multiple servers, and makes organization much more complicated. Besides, your desktop is almost certainly not the final deployment server, so you'll eventually have to develop a good system for deploying anyhow.

2. Make Shortcuts to Start and Stop the Server

Since I find myself frequently restarting the server, I find it convenient to place shortcuts to the server startup and shutdown scripts inside my main development directory or on my desktop. You will likely find it convenient to do the same.

For example, one way to make these shortcuts is to go to install_dir/bin, right-click on startup.bat, and select Copy. Then go to your development directory, right-click in the window, and select Paste Shortcut (not just Paste). Repeat the process for install_dir/bin/shutdown.bat. If you put the shortcuts on your desktop, you can also assign keyboard shortcuts to invoke them. On Unix, you would use ln -s to make a symbolic link to startup.sh, catalina.sh (needed even though you don't directly invoke this file), and shutdown.sh.

3. Set Your CLASSPATH

Since servlets and JSP are not part of the Java 2 platform, standard edition, you have to identify the servlet classes to the compiler. The server already knows about the servlet classes, but the compiler (i.e., javac) you use for development probably doesn't. So, if you don't set your CLASSPATH, attempts to compile servlets, tag libraries, or other classes that use the servlet and JSP APIs will fail with error messages about unknown classes. Here are the standard Tomcat locations:

Now, in addition to the servlet JAR file, you also need to put your development directory in the CLASSPATH. Although this is not necessary for simple packageless servlets, once you gain experience you will almost certainly use packages. Compiling a file that is in a package and that uses another class in the same package requires the CLASSPATH to include the directory that is at the top of the package hierarchy. In this case, that's the development directory I just discussed. Forgetting this setting is perhaps the most common mistake made by beginning servlet programmers!

Finally, you should include "." (the current directory) in the CLASSPATH. Otherwise, you will only be able to compile packageless classes that are in the top-level development directory.

Here are two representative methods of setting the CLASSPATH. They assume that your development directory is C:\Servlets+JSP. Replace install_dir with the actual base installation location of the server. Also, be sure to use the appropriate case for the filenames, and enclose your pathnames in double quotes if they contain spaces.

4. Bookmark the Servlet and JSP API Documentation

Just as no serious programmer should develop general-purpose Java applications without access to the JDK API documentation (in Javadoc format), no serious programmer should develop servlets or JSP pages without access to the API for classes in the javax.servlet packages.

You can access the documentation from the Tomcat home page, but you probably will want access to the API even when the server is not running. So, I recommend you open the top-level file directly from disk and bookmark that location. Here are the standard locations:

Compile and Test Some Simple Servlets

OK, so your environment is all set. At least you think it is. It would be nice to confirm that hypothesis. Verifying this involves the following three steps:

  1. Testing a packageless servlet
  2. Testing a servlet that uses packages
  3. Testing a servlet that uses packages and utility classes
Details on each step are given below.

Test 1: A Servlet That Does Not Use Packages

The first servlet to try is a basic one: no packages or utility (helper) classes. Rather than writing your own test servlet, you can just download HelloServlet.java into your development directory, compile it, and copy the .class file to install_dir/webapps/ROOT/WEB-INF/classes. Right-click on the link to download the file to your system. Note: in all versions of Apache Tomcat, the location for servlets in the default Web application is install_dir/webapps/ROOT/WEB-INF/classes. However, in recent versions of Tomcat, the system doesn't create the directory for you automatically. No problem: just create it yourself. (Remember that case matters: WEB-INF is upper case, classes is lower case.) Note that my preconfigured Tomcat versions already contain the classes directory and already have the sample servlets installed.

What about install_dir/shared/classes?
"Hey, wait! Shouldn't I use install_dir/shared/classes instead of install_dir/webapps/ROOT/WEB-INF/classes?"

Nope. There are two reasons why it is preferable to use install_dir/webapps/ROOT/WEB-INF/classes:

1. It is standard. The ROOT directory follows the normal structure of a Web application (see Section 2.11 of the book): HTML/JSP files go in the main directory, the web.xml file goes in WEB-INF, unjarred Java classes go in WEB-INF/classes, and JAR files go in WEB-INF/lib. So, if you use WEB-INF/classes, you are using a structure that works on all servers that support servlets 2.2 and later. On the other hand, install_dir/shared/classes is a Tomcat-specific location that is supported on few, if any, other servers.

2. It is specific to a Web application. Once you become comfortable with the basics, you will almost certainly divide your projects up into separate Web applications. By putting your code in WEB-INF/classes, you are ready for this, since your code is already part of a Web application (the default one for Tomcat). So, the code can easily move to another Web application, and it will not interfere with any future applications. On the other hand, install_dir/shared/classes results in code that is shared by all Web applications on your server. This is almost never what you want for servlets.

If you get compilation errors, go back and check your CLASSPATH settings (see the earlier section on this topic)--you most likely erred in listing the location of the JAR file that contains the servlet classes (e.g., install_dir/common/lib/servlet.jar for Tomcat 4). Once you compile HelloServlet.java, put HelloServlet.class in install_dir/webapps/ROOT/WEB-INF/classes. After compiling the code, access the servlet with the URL http://localhost/servlet/HelloServlet (or http://localhost:8080/servlet/HelloServlet if you chose not to change the port number as described earlier). You should get a simple HTML page that says "Hello". If this URL failed but the test of the server itself succeeded, you probably put the class file in the wrong directory or forgot to enable the invoker servlet.

Test 2: A Servlet That Uses Packages

The second servlet to try is one that uses packages but no utility classes. Again, rather than writing your own test, you can download and install HelloServlet2.java. Since this servlet is in the coreservlets package, it should go in the coreservlets directory both during development and when deployed to the server. Once you compile HelloServlet2.java, put HelloServlet2.class in install_dir/webapps/ROOT/WEB-INF/classes/coreservlets. For now, you can simply copy (not move!) the coreservlets subdirectory from the development directory to install_dir/webapps/ROOT/WEB-INF/classes. An upcoming section will provide some other options for the deployment process.

Once you have placed the servlet in the proper directory, access it with the URL http://localhost/servlet/coreservlets.HelloServlet2. You should get a simple HTML page that says "Hello (2)". If the first test succeeded but this test failed, you probably either typed the URL wrong (e.g., used a slash instead of a dot after the package name) or put HelloServlet2.class in the wrong location (e.g., directly in install_dir/webapps/ROOT/WEB-INF/classes directory instead of in the coreservlets subdirectory).

Test 3: A Servlet That Uses Packages and Utilities

The final servlet you should test to verify the configuration of your server and development environment is one that uses both packages and utility classes. HelloServlet3.java is a servlet in the coreservlets package that uses the ServletUtilities class to simplify the generation of the DOCTYPE (specifies the HTML version--useful when using HTML validators) and HEAD (specifies the title) portions of the HTML page. Those two parts of the page are useful (technically required, in fact), but are tedious to generate with servlet println statements. Since both the servlet and the utility class are in the coreservlets package, they should go in the coreservlets directory.

If you get compilation errors such as "Unresolved symbol: ServletUtilities", check the following two things.

Please don't send me email about unresolved symbol errors until you have confirmed that HelloServlet3.java and ServletUtilities.java are in a subdirectory called coreservlets, and that the directory above this is in the CLASSPATH.

Once you compile HelloServlet3.java (which will automatically cause ServletUtilities.java to be compiled), copy (don't move!) the entire coreservlets subdirectory from your development location to install_dir/webapps/ROOT/WEB-INF/classes. Then, access the servlet with the URL http://localhost/servlet/coreservlets.HelloServlet3 (again, note that it is a dot, not a slash, between the package name and the servlet name). You should get a simple HTML page that says "Hello (3)".

Establish a Simplified Deployment Method

OK, so you have a development directory. You can compile servlets with or without packages. You know which directory the servlet classes belong in. You know the URL that should be used to access them. (Actually, http://hostname/servlet/ServletName is just the default URL; you can also use the web.xml file to customize that URL; for details, see Section 2.11 of the book.) But how do you move the class files from the development directory to the deployment directory? Copying each one by hand every time is tedious and error prone. Once you start using Web applications, copying individual files becomes even more cumbersome.

There are several options to simplify the process. Here are a few of the most popular ones. If you are just beginning with servlets and JSP, you probably want to start with the first option and use it until you become comfortable with the development process. Note that I do not list the option of putting your code directly in the server's deployment directory. Although this is one of the most common choices among beginners, it scales so poorly to advanced tasks that I recommend you steer clear of it from the start.

  1. Copy to a shortcut or symbolic link.
  2. Use the -d option of javac.
  3. Let your IDE take care of deployment.
  4. Use ant or a similar tool.
Details on these four options are given below.

1. Copy to a Shortcut or Symbolic Link

Go to install_dir/webapps/ROOT/WEB-INF, right-click on the classes directory, and select Copy. Then go to your development directory, right-click, and select Paste Shortcut (not just Paste). Now, whenever you compile a packageless servlet, just drag the class files onto the shortcut. When you develop in packages, use the right mouse to drag the entire package directory (e.g., the coreservlets directory) onto the shortcut, release the mouse, and select Copy. On Unix/Linux, you can use symbolic links (created with ln -s) in a manner similar to that for Windows shortcuts.

An advantage of this approach is that it is simple. So, it is good for beginners who want to concentrate on learning servlets and JSP, not deployment tools. Another advantage is that a variation applies once you start using your own Web applications. (See Chapters 4-6 of More Servlets and JSP for details on Web applications). For instance, with Tomcat, you can easily make your own Web application by putting a copy of the install_dir/webapps/ROOT directory into your development directory and renaming it (for example, to testApp). Now, to deploy your Web application, just make a shortcut to install_dir/webapps and copy the entire Web application directory (e.g., testApp) each time by using the right mouse to drag the directory that contains your Web application onto this shortcut and selecting Copy (say Yes when asked if you want to replace existing files). Almost everything stays the same as it was without Web applications: just add the name of the directory to the URL after the hostname (e.g., replace http://localhost/blah/blah with http:/localhost/testApp/blah/blah). Just note that you'll have to restart the server the very first time you deploy the directory into install_dir/webapps.

One disadvantage of this approach is that it requires repeated copying if you use multiple servers. For example, I usually have Apache Tomcat, Macromedia JRun, and Caucho Resin on my desktop system and regularly test my code with all three servers. A second disadvantage is that this approach copies both the Java source code files and the class files to the server, whereas only the class files are needed. This does not matter on your desktop development server, but when you get to the "real" deployment server, you won't want to include the source code files.

2. Use the -d Option of javac

By default, the Java compiler (javac) places class files in the same directory as the source code files from which they came. However, javac has an option (-d) that lets you designate a different location for the class files. You need only specify the top-level directory for class files--javac will automatically put packaged classes in subdirectories that match the package names. So, for example, I could compile the HelloServlet2 servlet as follows (line break added only for clarity; omit it in real life).
javac -d install_dir/webapps/ROOT/WEB-INF/classes
         HelloServlet2.java
You could even make a Windows batch file or Unix shell script or alias that makes a command like servletc expand to javac -d install_dir/.../classes. See http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javac.html for more details on -d and other javac options.

An advantage of this approach is that it requires no manual copying of class files. Furthermore, the exact same command can be used for classes in different packages since javac automatically puts the class files in subdirectories matching the package names.

The main disadvantage of this approach is that it applies only to Java class files; it won't work for deploying HTML and JSP pages, much less entire Web applications.

3. Let Your IDE Take Care of Deployment

Most servlet- and JSP-savvy development environments (e.g., IBM WebSphere Studio, Eclipse, Borland JBuilder) have options that let you tell the IDE where to deploy class files for your project. Then, when you tell the IDE to build the project, the class files are automatically deployed to the proper location (package-specific subdirectories and all).

An advantage of this approach, at least in some IDEs, is that it can deploy HTML and JSP pages and even entire Web applications, not just Java class files. A disadvantage is that it is an IDE-specific technique and thus is not portable across systems.

4. Use ant or a Similar Tool

Developed by the Apache foundation's Jakarta project, ant is a tool similar to the Unix make utility. However, ant is written in the Java programming language (and thus is portable) and is touted to be both simpler to use and more powerful than make. Many servlet and JSP developers use ant for compiling and deploying. The use of ant is especially popular among Tomcat users and with those developing Web applications.

For general information on using ant, see http://jakarta.apache.org/ant/manual/. See http://jakarta.apache.org/tomcat/tomcat-5.0-doc/appdev/processes.html for specific guidance on using ant with Tomcat.

The main advantage of this approach is flexibility: ant is powerful enough to handle everything from compiling the Java source code files, to copying class files, to producing WAR files. The disadvantage of ant is the overhead of learning to use it; there is more of a learning curve with ant than with the other techniques in this section.

Using Preconfigured Tomcat Versions

If you prefer not to individually make each of the changes described in this tutorial, you can download a version of Tomcat that has all of these changes already made. In particular, these Tomcat versions:

However, the preconfigured Tomcat versions are not necessarily as up-to-date as the versions on the Apache site, so you should go to the Apache site if you want the very latest version.

More Information