18.2.1. Installing the JDK

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:

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.

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

(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

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

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"

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

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.4. Conf

18.2.5. Writing and Testing a Servlet

<?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