zz incomplete

JavaServer Pages:  Installing and Using Tomcat

zz insert text description

Published  zz, 2001
By Richard G. Baldwin

Java Programming, Lecture Notes # 768



Viewing tip

You may find it useful to open another copy of this lesson in a separate browser window.  That will make it easier for you to scroll back and forth among the different figures and listings while you are reading about them.





What is Tomcat?

Tomcat is the Reference Implementation for the Java Servlet 2.2 and JavaServer Pages 1.1 Technologies. Tomcat is freely available for download.  As of the date of this writing, you can download Tomcat at http://jakarta.apache.org/site/binindex.html.

Sun has delivered the latest versions of JSP and Servlets source code to Apache to be developed and released under the Apache development process. According to the announced plans, Apache, Sun and other companies and individuals will develop a reference implementation that is freely available to any company or individual. This reference implementation, named Tomcat, will be the official reference implementation for the JSP 1.1 and Servlet 2.2 technologies.

Who controls JavaServer Pages and Java Servlets

JavaServer Pages and Java Servlets Specifications are still owned by Sun.  They will evolve under the Java Community Process.  The reference implementation being developed under license at Apache (Tomcat) will be developed consistent with these specifications.

Therefore, Tomcat is the code name for the combined JSP 1.1 and Servlets 2.2 Reference Implementation being developed under the Apache Jakarta project.

What is Jakarta?

Jakarta is an Apache umbrella project that includes 3 subprojects related to JSP and servlet technology:

Since you are already interested in JavaServer Pages, you may be interested in these projects as well.

Downloading Tomcat

Three different versions of Tomcat are available for download:  Nightly, Milestone, and Release builds.

Only release builds are considered stable, so unless you are adventuresome, you should download, install, and use the latest release build.  As of the date of this writing, the current release build is Tomcat Release 3.2.1.

When you are ready to download, follow the above link and download the file named jakarta-tomcat-xxx.yyy.  Various compression formats are available, so you should download the format that is appropriate for your system.  In my case, since I use Windows NT, I downloaded and installed a file named jakarta-tomcat-3.2.1.zip.


JavaServer Pages and Java Servlets are the web presentation layer in the Java 2 Platform, Enterprise Edition (J2EE) Platform.  In order to ensure compatibility, a verification program is available under the Apache license. This program, called Watchdog, allows a developer to confirm that their JSP/Servlets implementation is consistent with the specifications and will work with any other JSP/Servlets implementation.

Installing Tomcat

Tomcat is remarkedly easy to install.  On my NT machine, all that was required was to Actually, JAVA_HOME had already been set during the previous installation of some other Java tool, so all that was required for my machine was to confirm that it was set to the installation directory of my Sun JDK 1.3 Java environment.

Values of my environment variables

Just so that you will have something tangible to sink your teeth into, the value of the JAVA_HOME environment variable on my NT machine is D:\progfile\jdk1.3.  It will likely be different on your machine, depending on where you installed your JDK, and which version of the JDK you are using.

You must set the TOM_CAT environment variable to the installation directory of Tomcat.  Again, on my machine, that is D:\progfile\jakarta-tomcat-3.2.1, but you can install Tomcat wherever you wish.  (The value of this environment variable will come up again in a few minutes.)

Minimalistic documentation

One of the disappointing things about Sun's alliance with Apache is that Apache seems to be less inclined to provide good online documentation than Sun.  Therefore, you must often do quite a bit of searching to locate information that you need.  The User's Guide that I will refer you to shortly is entitled Tomcat - A Minimalistic User's Guide.  I agree that it is pretty minimal, and incorrect in some cases.

Documentation files

When you have unzipped Tomcat into your installation directory of choice, you should be able to locate the following file and load it into your browser.  Note that the top-level Tomcat directory name will probably change with the release of future versions of the software.


This is a top-level documentation file, which is also available at the Tomcat website.  This file contains links to a variety of other documents.  One of those other documents is the Tomcat User's Guide, which should be available on the Tomcat website and on your disk as well.

Detailed installation instructions

The User's Guide contains a very short section on Tomcat installation, which I have copied below for easy reference.  (Be careful of the manual line breaks that I inserted to force the text to fit in this narrow presentation format.)
Download the zip/tar.gz/whatever file 


Unzip the file into some directory 
(say foo). This should create a new
subdirectory named "tomcat". 

Change directory to "tomcat" and set
a new environment variable
(TOMCAT_HOME) to point to the root 
directory of your Tomcat hierarchy.
1.On Win32 you should type: 
  "set TOMCAT_HOME=foo\tomcat"
2.On UNIX you should type: 
  for bash/sh "TOMCAT_HOME=foo/tomcat 
              ; export TOMCAT_HOME"
  for tcsh "setenv TOMCAT_HOME 
Set the environment variable JAVA_HOME
to point to the root directory of your
JDK hierarchy, then add the Java 
interpreter to your PATH environment 

These instructions are not only minimalistic, they are also a little misleading.

First, unziping the zip file for version 3.2 won't create a new subdirectory named "tomcat".  For version 3.2.1, it will create a new subdirectory named jakarta-tomcat-3.2.1. I am assuming that the name of this directory will continue to change with the release of versions.  This has an impact on the value that you give to the TOMCAT_HOME environment variable.

Second, rather than to set the two environment variables temporarily as indicated in the Win32 instructions, you might prefer to set them permanently either through the autoexec.bat file or the WinNT/2000 environment dialog.

Setting the PATH environment variable

The instruction to add the Java interpreter to your PATH environment variable doesn't have anything to do with Tomcat.  Rather, that is a requirement when you install your Java Development Kit.

However, it is true that Tomcat won't work unless the Java Development Kit is properly installed.  (You may be able to get by with just the JRE instead of the full JDK.  I haven't tried that to see if it works.)

However, despite the fact that the above documentation contains a couple of questionable items, it does reinforce my earlier statement that installation of Tomcat is very easy.

Using Tomcat

Unfortunately, it is easier to figure out how to install Tomcat than it is to figure out how to use it after it is installed.  Figure 1 shows a partially expanded directory tree for my Tomcat installation.

Figure 1.  A partially expanded directory tree for a Tomcat Installation

Figure 1 shows twenty-one separate directories, many of which have hidden subdirectories.  When fully expanded, the directory tree is very large, showing about 2,400 files.  The primary difficulty of using Tomcat is figuring out where to put your JSP, servlet, and JavaBeans component files.

There are many options and many different ways to configure Tomcat.  I don't pretend to know about all of those different options.  However, by studying the documentation, I have figured out two ways to arrange my files that seem to work, and also seem to be consistent with what Sun had in mind.  I will show you the details of one of those ways, and briefly describe the other way.  Once you begin using the product, you may find other better ways to arrange your files.

Early on, you will be primarily concerned with the directory tree consisting of the directory named webapps and its subdirectories.  This directory tree comprises what is often referred to in the Sun literature as the Web Application Container, or Web Container for short.

Here is what the servlet 2.2 specification has to say about a Web Application.
A web application is a collection of 
servlets, html pages, classes, and 
other resources that can be bundled 
and run on multiple containers from 
multiple vendors. A web application 
is rooted at a specific path within a 
web server. For example, a catalog 
application could be located at 
http://www.mycorp.com/catalog. All 
requests that start with this prefix 
will be routed to the ServletContext 
which represents the catalog 

So, given this, what is a servlet context.  Again, here is what the specification has to say.
The ServletContext defines a servletís view of the web application within which the servlet is running. The ServletContext also allows a servlet to access resources available to it. Using such an object, a servlet can log events, obtain URL references to resources, and set and store attributes that other servlets in the context can use. The Container Provider is responsible for providing an implementation of the ServletContext interface in the servlet container.  A ServletContext is rooted at a specific path within a web server. For example a context could be located at http://www.mycorp.com/catalog. All requests that start with the /catalog request path, which is known as the context path, will be routed to this servlet context.  Only one instance of a ServletContext may be available to the servlets in a web application.  In cases where the web application indicates that it is distributable, there must only be one instance  of the ServletContext object in use per application per Java Virtual Machine.

In case it isn't clear just what this means, I will try to clear it up later with specific examples.


A web application is a collection of servlets, html pages, classes, and other resources that can be bundled and run on multiple containers from multiple vendors. A web application is rooted at a specific path within a web server. For example, a catalog application could be located at http://www.mycorp.com/catalog. All requests that start with this prefix will be routed to the ServletContext which represents the catalog application.

If you work with the J2EE reference implementation later, you will find that it has both a Web Container and an Enterprise JavaBeans (EJB) Container.  However, Tomcat doesn't provide the EJB container.  Neither does it provide the fancy deployment tools that are provided by the J2EE reference implementation.  With Tomcat, deployment is a more direct manual process.

According to the Sun Servlet API Specification, servers that conform to the 2.2 specification are required to accept a Web Application Archive in a standard format.  This is a JAR file (actually a WAR file) containing JSP files, servlet class files, and JavaBeans Component files, with a specific organizational structure.  Although this may be a little complicated to get used to, it will be beneficial in the long run.  Prior to the release of version 2.2, there were no such standards, and the manner in which you organized your files for deployment in one server would likely be different from the manner in which you were required to organize them for deployment in another server.

A web application is defined as a hierarchy of directories and files in a standard layout. Such a hierarchy can be accessed in its "unpacked" form, where each directory and file exists in the filesystem separately.  Alternately, the hierarchy can be accessed in a "packed" form known as a Web ARchive, or WAR file. The open format is more useful during development, while the archive format is very useful when you distribute your application to be installed by others.  In effect, when you distribute your application for installation in a conforming server, you are only required to be concerned with one format.

According to Sun, the top-level directory of your web application hierarchy is also the document root of your application. In Figure 1, the directories named baldwin and xyz are the document roots for two of my applications.  The directories named admin, examples, Root, and test are the document roots of applications that were already installed when I unzipped the file that I downloaded.  It is important to note that these document-root directories are all subdirectories of the directory named webapps.

You place the HTML files and JSP pages that comprise your application's user interface in the document-root directory, or some subdirectory of the document-root directory.

Note in particular in Figure 1 that the directory named baldwin has a subdirectory named webpgpub.  Although it isn't apparent in Figure 1, the webpgpub directory contains a JSP file named jsp010.jsp.  The following URI can be used to access that JSP page via a browser running on the same machine as the Tomcat server.  (Don't be concerned about the meaning of localhost:8080 at this point.  That is the host name and port number.  I will have more to say about that later.)


The important thing to note here is that the immediate subdirectories of the directory named webapps are exposed directly to clients of the server.  In other words, insofar as the outside world is concerned, these directories (such as baldwin and examples) constitute the tops of directory trees that are accessible to clients.  Directories that are not subdirectories of webapps are not accessible to clients. (Also, as I will explain later, the contents of the directory named Web-inf, and certain of its subdirectories, are not accessible to clients.)

As I mentioned earlier, this directory structure can either be open as shown in Figure 1, or can be encapsulated into a WAR file for deployment into the lib directories of the Tomcat server (or any other Servlet 2.2 compatible server).

So, now let me discuss the contents of each of these directories in a little more detail.

zz also look at the specs, ch 9

*.html, *.jsp, etc. - The HTML and JSP pages, along with other files that must be visible to the client browser (such as JavaScript and stylesheet files) for your
    application. In larger applications you may choose to divide these files into a subdirectory hierarchy, but for smaller apps, it is generally much simpler to maintain
    only a single directory for these files.

    WEB-INF/web.xml - The Web Application Deployment Descriptor for your application. This is an XML file describing the servlets and other components that
    make up your application, along with any initialization parameters and container-managed security constraints that you want the server to enforce for you. This file
    is discussed in more detail in the following subsection.

    WEB-INF/classes/ - This directory contains any Java class files (and associated resources) required for your application, including both servlet and non-servlet
    classes, that are not combined into JAR files. If your classes are organized into Java packages, you must reflect this in the directory hierarchy under
    WEB-INF/classes/. For example, a Java class named com.mycompany.mypackage.MyServlet would need to be stored in a file named

    WEB-INF/lib/ - This directory contains JAR files that contain Java class files (and associated resources) required for your application, such as third party class
    libraries or JDBC drivers.

When you install an application into Tomcat (or any other 2.2-compatible server), the classes in the WEB-INF/classes/ directory, as well as all classes in JAR files
found in the WEB-INF/lib/ directory, are added to the class path for your particular web application. Thus, if you include all of the required library classes in one of
these places (be sure to check licenses for redistribution rights for any third party libraries you utilize), you will simplify the installation of your web application -- no
adjustment to the system class path will be necessary.

Much of this information was extracted from Chapter 9 of the Servlet API Specification, version 2.2, which you should consult for more details.

zz see http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/appdev/index.html

Listing zz


Sample Program


Interesting Code Fragments

I will break this program down and discuss it in fragments.


zz Listing 1 shows

Listing zz



What's Next?


Complete Program Listing

A complete listing of the program is provided in Listing  zz.

Listing zz

Copyright 2000, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.

About the author

Richard Baldwin is a college professor and private consultant whose primary focus is a combination of Java and XML. In addition to the many platform-independent benefits of Java applications, he believes that a combination of Java and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects involving Java, XML, or a combination of the two.  He frequently provides onsite Java and/or XML training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Java Programming Tutorials, which has gained a worldwide following among experienced and aspiring Java programmers. He has also published articles on Java Programming in Java Pro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.