Apache The Definitive Guide, 3rd EditionApache: The Definitive GuideSearch this book

18.2. Tomcat

Tomcat, part of the Jakarta Project, is the modern version of JServ and is able to act as a server in its own right. But we feel that it will be a long time catching up with Apache and that it would not be a sensible choice as the standalone server for a serious web site.

The home URL for the Jakarta project is http://jakarta.apache.org/, where we are told:

The goal of the Jakarta Project is to provide commercial-quality server solutions based on the Java Platform that are developed in an open and cooperative fashion.

At the time of writing, Tomcat 4.0 was incompatible with Apache's mod-cgi, and in any case requires Java 1.2, which is less widely available than Java 1.1, so we decided to concentrate on Tomcat 3.2.

In the authors' experience, installing anything to do with Java is a very tiresome process, and this was no exception. The assumption seems to be that Java is so fascinating that proper explanations are unnecessary — devotees will immerse themselves in the holy stream and all will become clear after many days beneath the surface. This is probably because explanations are expensive and large commercial interests are involved. It contrasts strongly with the Apache site or the Perl CPAN network, both of which are maintained by unpaid enthusiasts and usually, in our experience, are easy to understand and work immaculately.

18.2.1. Installing the JDK

First, you need a Java Development Kit (JDK). We downloaded jdk1.1.8 for FreeBSD[66] from http://java.sun.com and installed it. Another source is ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/local-distfiles/nate/JDK1.1/jdk1.1.8_ELF.V1999-11-9.tar.gz. Installation is simple: you just unzip the tarball and then extract the files. If you read the README without paying close attention, you may get the impression that you need to unzip the src.zip file — you do not, unless you want to read the source code of the Java components. And, of course, you absolutely must not unzip classes.zip.

[66]This is the version of Unix we use — you would download the version appropriate to your OS.

An essential step that may not be very clear from the documentation is to include the JDK, at ..../usr/src/java/jdk1.1.8/bin on your path, to set the environment variable CLASSPATH to /usr/src/java/jdk1.1.8/lib/classes.zip and to add the current directory to the path if it isn't already there.

Make sure that the directory names correspond with the situation on your machine and log in again to get it to work. A simple test to see whether you've got it all together is to write yourself a "hullo world" program:

public class hw
    {
    public static void main(String[] args)
        {
        System.out.println("Hello World");
        }
    }

Save it with the same name as the public class and the .java extension: hw.java. Compile it with:

javac hw.java

and run it with:

java hw

If Hello World appears on the screen, all is well.

18.2.2. Installation of Tomcat

Tomcat can work in three different ways:

  1. As a standalone servlet container. This is useful for debugging and testing, since it also acts a (rather crude) web server. We would not suggest you use it instead of Apache.

  2. As an in-process servlet container running inside Apache's address space. This gives good performance but is poor on scalability when your site's traffic grows.

  3. As an out-of-process servlet container, running in its own address space and communicating with Apache through TCP/IP sockets.

If you decide on 2 or 3, as you probably will, you have to choose which method to use and implement it accordingly.

Consequently, the installation of Tomcat involves two distinct processes: installing Tomcat and adapting Apache to link to it.

Normally we advocate building from source, but in the case of Java it can get tedious, so we decided to install Tomcat from the binary distribution, jakarta.-tomcat-3.3a.tar.gz in our case.

Figure

Installation of Tomcat is pretty simple. Having unpacked it, all you have to do is to set the environment variables:

JAVA_HOME  to: /usr/src/java/jdk1.1.8
TOMCAT_HOME  to /usr/src/tomcat/jakarta-tomcat-3.3a

Figure

(or the paths on your machine if they are different) and re-log in. Test that everything works by using the command:

ls $TOMCAT_HOME

Figure

If it doesn't produce the contents of this directory, something is amiss.

Figure

Installation on Win32 systems is very similar. Set the path to the Tomcat directory by typing:

set TOMCAT_HOME =\usr\src\tomcat\jakarta-tomcat-3.3a"

Figure

The .../jakarta-tomcat-3.3a/bin directory contains two scripts: startup.sh, which sets Tomcat running, and shutdown.sh, which stops it. To test that everything is installed properly, go there and run the first. A good deal of screen chat ensues (after rather long pause). Note that the script detaches from the shell early on, so its hard to tell when its finished.

By default, Tomcat logs to the screen, which is not a good idea, so it is wise to modify conf/server.xml from:

...
<LogSetter name ="tc_log"
        verbosityLevel="INFORMATION"
/>
...

to:

...
<LogSetter name ="tc_log"
        path="logs/tomcat.log"
        verbosityLevel="INFORMATION"
/>
...

The result is to transfer the screen messages to the log file.

If you now surf to port 8080 on your machine — we went to http://www.butterthlies.com:8080 — Tomcat will show you its home page, which lives at $TOMCAT_HOME/webapps/ROOT/index.html. Note that the page itself erroneously claims to be at $TOMCAT_HOME/webapps/index.html.

When you have had enough of this excitement, you can stop Tomcat with $TOMCAT_HOME/bin/shutdown.sh. If you try to start Tomcat without shutting it down first, you will get a fatal Java error.

18.2.3. Tomcat's Directory Structure

In the .../jakarta-tomcat -- 3.3a directory you will find:

bin
Startup, shutdown scripts, tomcat.sh, and others

conf
Configuration files

doc
Various documents, including uguide — the file to print out and keep by you — and FAQ

lib
Jar files

logs
Log files

webapps
Sample web applications

work
Tomcat's own private stuff

We will look through the contents of these subdirectories that need comment.

18.2.3.1. Bin

The startup and shutdown scripts merely call the important one: tomcat.sh. This script does two things:

  • Guesses a CLASSPATH

  • Passes command-line arguments to org.apache.tomcat.startup.Tomcat. These include start and stop, plus the location of the appropriate server.xml file (see later), which configures Tomcat. For instance, if you want to use /etc/server_1.xml with Tomcat and Apache, you would start Tomcat with:

    bin/tomcat.sh start -f/etc/server_1.xml

18.2.4. Conf

This subdirectory contains two important and useful files:

Server.xml
The first is server.xml. This file covers several issues, in most of which you will not have to interfere. For syntax, see the documentation on the default server we ran earlier (in http:/.../doc/serverxml.html).

apps-*.xml
Each file of the form apps-<somename>.xml is also parsed — this is enabled by the directive:

	<ContextXmlReader config="conf/apps.xml" />

which causes both conf/apps.xml and conf/apps-*.xml to be read and contexts to be loaded from them (see the example servlet later for how contexts are used).

18.2.5. Writing and Testing a Servlet

We use the Simple.java test servlet described earlier to demonstrate how to install a servlet. First of all we create a directory, .../site.tomcat, and in it a subdirectory called servlets — this is where we will end up pointing Tomcat. In .../site.tomcat/servlets, we create a directory WEB-INF (this is where Tomcat expects to find stuff). In WEB-INF we create another subdirectory called classes. Then we copy Simple.class to .../site.tomcat/servlets/WEB-INF/classes. We then associate the Simple class with a servlet unimaginatively called "test", by creating .../site.tomcat/servlets/WEB-INF/web.xml, containing:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
    <servlet>
        <servlet-name>
            test
        </servlet-name>
        <servlet-class>
            Simple
        </servlet-class>
    </servlet>
</web-app>

Finally, we make Tomcat aware of all this by associating the .../site.tomcat/servlets directory with a context by creating conf/apps-simple.xml (remember, this file will automatically be read by the default configuration) containing:

<?xml version="1.0" encoding="ISO-8859-1"?>
<webapps>
   <Context path="/simple" 
            docBase=".../site.tomcat/servlets" 
            debug="0" 
            reloadable="true" > 
              <LogSetter name="simple_tc.log" path="logs/simple.log" />
              <LogSetter name="simple_servlet_log" 
                         path="logs/simple_servlet.log" 
                         servletLogger="true"/>
  </Context>
</webapps>

Obviously, docBase must be set to the actual path of our directory. The path parameter specifies the first part of the URL that will access this context. The context can contain plain HTML, as well as servlets and JSPs. Servlets appear in the servlet subdirectory of the path, so to access the Simple servlet with the previous configuration, we would use the URL http://.../simple/servlet/test. Surfing to http://.../simple/servlet/test?a=b&c=d&c=e produces the following output:

Simple Servlet

c[0]=d
c[1]=e
a[0]=b


Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.