Tomcat Setup for Windows

Background

Tomcat is a Java servlet container.  It can serve both servlets and JSP pages.  Sun had a product that did this but apparently have dropped it in favor of supporting tomcat, which is considered the reference implementation of the servlet API.

Tomcat is maintained by the Jakarta project of the apache organization.  Jakarta is a series of Java related projects maintained by the Apache organization.  Apache is the world's most popular web server platform.  Tomcat and Apache are designed to work together, in that Apache will hand off any JSP or servlet URLs to tomcat to handle.  Note tomcat can respond directly to such URLs without Apache.

Downloading tomcat

Download the latest tomcat for Windows from here.  This directory shows the latest stable versions of tomcat and other tools in the section marked Release Builds.  To obtain the latest stable tomcat for Windows, click on the tomcat link in this section with the highest version number.  (At the time of writting this document, that is version 3.2.1.)

In the directory listing that now appears you will see the latest versions of tomcat for all supported platforms.  The Windows platform version is a zip file.  Download the zip file (file extention .zip) with the highest version number.  In this same directory you will find another zip file.  This file contains the Java servlet API JavaDocs (the official documentation for the servlet classes) with a similar version number.  It is recommended you download this file as well.

Installing tomcat

The installed location of tomcat must be in a directory with legal DOS 8.3 directory names for all directories in the path.  Unfortunately the zipped file names do not do this, so you will have to rename some of the directories when un-zipping the downloaded archive.  (WindowsNT doesn't have this limitation, and tomcat was designed to be installed on that platform, not Windows9x.) 

If you wish to keep you java development tools in one directory, you can install to the directory C:\jdk\jakarta.  However if you installed the JDK with the default name (which contains periods) then you need to install tomcat elsewhere, such as C:\jakarta\.  For the rest of this document we will assume you installed in the first location.  So after you unzip (using winzip) the archive you will have the following:

Next, rename jakarta-tomcat-3.2.1 to just tomcat.

If you downloaded the jakarta-servletapi zip as well, you should also unzip this to the diretory C:\jdk\jakarta.

Next, bookmark (add to favorites) the C:\jdk\jakarta\tomcat\doc\index.html and the C:\jdk\jakarta\servletapi-3.2\docs\api\index.html URLs.  The tomcat documentation includes a user's guide, an application devleoper's guide, a FAQ, and other resources. 

In order to run tomcat, you must make some changes to the JDK setup so the classes and executables can be located.  This involves defining the environment variable TOMCAT_HOME and adding the tomcat bin directory to PATH.  If you followed the recommended JDK setup this means a modification to the SetUpJav.bat file.  The new file should look like this if you used the recommended directories:

@ECHO OFF

SET JAVA_HOME=C:\jdk
SET CLASSPATH=.

SET TOMCAT_HOME=C:\jdk\jakarta\tomcat
SET PATH=%JAVA_HOME%\BIN;%TOMCAT_HOME%\bin;%PATH%

(Note you may have to modify the value of TOMCAT_HOME if you installed tomcat in another directory such as C:\jakarta\tomcat.)

In order to compile servlets, the servlet.jar file included with tomcat must be found on your CLASSPATH, or installed as a standard extention to the JRE (Java Runtime Environment).  I prefer this latter approach, however it means that when you upgrade the JDK and/or install a new version of the JRE (for example, when installing a new version of the Java plug-in) you must remember to copy the servlet.jar file to the correct directories.

Copy the file C:\jdk\jakarta\tomcat\lib\servlet.jar to the ...\lib\ext directories of each installed JRE.  In my case (a 1.3.0 installation) these places are:

Running tomcat

After installing tomcat as described above, launch the JDK window (this the the MS-DOS Prompt window with the custom environment).  Type "SET" and verify the settings for PATH and TOMCAT_HOME.  To start tomcat type:

This should display some stuff and pop up another Java window.  At the bottom of that window should appear some messages that tomcat is listening on ports 8080 and 8007.  If you see this, it worked!  If you see error messages, or the second window pops up and closes before you seen any error messages, try using the command:

which tells tomcat to not create a separate window.  This should give you a chance to see any error messages.

To try out tomcat, point your web browser to http://localhost:8080/.  If you see the tomcat welcome page, you did it!  Bookmark (add to favorites) this URL.

To stop tomcat, enter (in the first window, the second won't have a prompt):

This should briefly start another (third) window, then it and the tomcat (second) window will close.  You can start and stop tomcat at any time.  You will need to stop and restart tomcat if you add any servlets or JSPs.

Shortcuts

You can create a pair of shortcuts to start and stop tomcat.  These can be places on the desktop or under the Start menu (or both).  Copy the JDK shortcut (or the MS-DOS Prompt shortcut if you didn't make a JDK one).  Call the copy "tomcat - start".  right-click on the shortcut and select "Properties".  Now select the "Program" tab.  At the top enter the new window name, such as "Tomcat 3.2.1".

Change the "Cmd line" to: C:\jdk\jakarta\tomcat\bin\TOMCAT.BAT run

Change the "Working" (directory) to: C:\jdk\jakarta\tomcat

Change the "Batch file" to: C:\jdk\SetUpJav.bat

Select "Minimized" for the Run property, and select the "Close on exit" checkbox.

Feel free to select a new icon by clicking on "Change Icon...".

Now click on the "Memory" tab.  You will probably have to increase the Initial Environment value from "auto" to something like "3072".

Save your changes to this shortcut.  Now copy the new shortcut and rename the copy to "tomcat - stop".  Edit the command line property (under the "program" tab) to:

Change the window name at the top to something like: "Stopping tomcat ...".

Put these shortcuts where ever you wish.  To have tomcat start everytime you reboot, you can place the "tomcat - start" shortcut in the "Programs-->Startup" folder under the "Start" menu.

Deploying JSPs and Servlets (and Web Applications)

Tomcat must be configured to load the classes (and JavaBeans) used in your JSPs and and servlets (web applications).  The configuration file is an XML file that can be edited with notepad or MS XML Notepad.  Tomcat serves web applications, which contain JSPs and servlets plus other resources such as HTML pages, style sheets, graphics, etc.  To add your own JSPs or servlets you can either create (and configure) a new web application, or add your HTML, classes, graphics, etc., to an existing web application.  Tomcat comes with a few applications, including examples.  You can add your stuff to examples.

You can also create and deploy a new web application.

Web applications can either be setup as a series of directories containing your stuff, or (more commonly) as a Web application ARchive ("WAR") file.  The self-contained WAR file (similar to a JAR file) can be easily added to any server, not just tomcat.  This makes deployment much easier.  However for development it is probably simpler to create the proper directory heirarchy in the proper place (%TOMCAT_HOME%\webapps, which is also where WAR files go).

If you look in that directory you will see a subdirectory ROOT, which containts the top level tomcat HTML page index.html.  You can edit this page to add additional links.

For more details see the tomcat documentation, which will walk you through creating the correct directories, modifying and creating the required XML files, and building a HelloWorld servlet from scratch.  Note the steps about using source code control (CVS) only apply to development on a Unix or Linux system.  You can ignore all Unix instructions.