Running a Servlet under Tomcat

Download and install Tomcat

  1. Download jakarta-tomcat-3.2.4.zip from http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.4/bin/. I downloaded it to the top level of the C:drive. (The actual location doesn't matter.)
  2. Unzip it. It creates a subdirectory called jakarta-tomcat-3.2.4.

Set the JAVA_HOME environment variable

Set the environment variable JAVA_HOME to C:\JBuilder5\jdk1.3.1, or wherever jdk1.3.1 is located on your machine. You can set environment variables either in Settings->ControlPanel->System->Environment or in a Command Prompt window. When a environment variable is set in a Command Prompt window, that setting applies only to that window.

When setting environment variables, do not use quotatation marks and do not put spaces around the equal sign when using the set command in a Command Prompt window. For example, to set JAVA_HOME, write

set JAVA_HOME=C:\JBuilder5\jdk1.3.1

Start Tomcat and access a file

Tomcat is now ready to run. To run it and have it serve a file, do the following.
  1. Start a Command Prompt window.
  2. Change directory to the bin subdirectory of the Tomcat directory and run the startup command. In my case,
    cd C:\jakarta-tomcat-3.2.4\bin
    startup
  3. A new Command Prompt window will be opened with Tomcat running. Note that when Tomcat starts, it sets two additional environment variables.
    1. It sets TOMCAT_HOME to the Tomcat home directory, in my case to C:\jakarta-tomcat-3.2.4. (Note that in Windows, %TOMCAT_HOME% refers to the contents of the TOMCAT_HOME environment variable.)
    2. It sets CLASSPATH to include %TOMCAT_HOME%\lib\servlet.jar.
To ask Tomcat to serve a file, enter http://localhost:8080/examples/servlets/index.html into a browser. This (pure html) page lists some example servlets that come with Tomcat. There is nothing special about this file itself.

Two things worth noting about this URL.

  1. The host is localhost:8080. (By default Tomcat listens on port 8080.)
  2. The address (i.e., path) is examples/servlets/index.html. When Tomcat sees a URL, it consults its server.xml file (which is in %TOMCAT_HOME%/conf) to see if the path in the URL has been defined as a web application. In this case it has been. The file %TOMCAT_HOME%/conf/server.xml contains the following near the bottom.
    
            <Context path="/examples"
                     docBase="webapps/examples"
                     crossContext="false"
                     debug="0"
                     reloadable="true" >
            </Context>
    

    This is a mapping from a URL address path to an internal location.

    1. The path attribute defines /examples as a URL address which should be mapped to a special place on the disk and which may be associated with a Servlet.
    2. The docBase attribute defines webapps/examples as the place on the disk to associate with the path /examples.
    3. In other words, the above <Context> tag tells Tomcat to map
      http://localhost:8080/examples/
      to
      %TOMCAT_HOME%/webapps/examples/
      So when the user asks for
      http://localhost:8080/examples/servlets/index.html
      Tomcat actually access the file
      %TOMCAT_HOME%/webapps/examples/servets/index.html
    4. There is such a file, which comes with the Tomcat download. When Tomcat is unzipped, it creates an examples directory as a subdirectory of %TOMCAT_HOME%/webapps. That examples directory has a servlets subdirectly, which has an index.html file in it.

Run a Servlet

  1. One of the links in the file http://localhost:8080/examples/servlets/index.html is to ../servlet/HelloWorldExample. On first glance, this looks like it should be referring to a file at %TOMCAT_HOME%/webapps/examples/servlet/HelloWorldExample. But there is no such file. In fact, there is no such directory as %TOMCAT_HOME%/webapps/examples/servlet/.
  2. Instead, by convention, a reference to what appears to be a servlet directory at the top level of a mapped webapp address means: execute the indicated servlet. In this case, execute the servlet called HelloWorldExample.
  3. Servlets are simply .class files, i.e., compiled .java files.
  4. Servlet files are stored in the WEB-INF/classes subdirectory of the main web application directory. In this case the .class files for the examples web app is stored in %TOMCAT_HOME%/webapps/examples/WEB-INF/classes.
  5. So when the user requests
    http://localhost:8080/examples/servlet/HelloWorldExample
    Tomcat runs
    %TOMCAT_HOME%/webapps/examples/WEB-INF/classes/HelloWorldExample.class

Create and run your own Servlet

  • Download HelloWorld.java from http://archive.corewebprogramming.com/Chapter19.html to anywhere.
  • Change directory to the location where you stored HelloWorld.java and compile it with javac HelloWorld.java
  • Move the resulting .class file to %TOMCAT_HOME%/webapps/examples/WEB-INF/classes.
  • (Instead of using the %TOMCAT_HOME%/webapps/examples/WEB-INF/classes directory, we could have created an entirely new web app. That would have required adding another Context entry to the server.xml file. Had we done that, we would have had to restart Tomcat. To restart Tomcat, call shutdown and then startup again in the Command Prompt window in which we had originally started Tomcat.)
  • In a brower, access, http://localhost:8080/examples/servlet/HelloWorld. Your servlet will run.