Tomcat Java Server

Tomcat is Apache's Java Server.  It is designed to run both as a special purpose servlet engine to which an Apache HTTP server passes Servlet requests or as a standalone server that processes both HTTP and servlet requests.  But, it is generally not quite as efficient as Apache for HTTP tasks.  It is the current Java Server of choice for this course, and I recommend that you install a version of it on the system you use for development.  You should debug your servlets there and then move them to your course directory only when they are well-behaved.

The goal of this lesson is to provide a checklist of some of the main tasks required to install and configure Tomcat for servlet development.  In general, you should install the latest version of Tomcat that is available in the course download directory.  If another version is preferred and not available there, you will be informed.  Sometimes, because of compatibility issues, the version preferred for this course may not be the latest version from Apache.

The notes that follow pertain to version 5.5.26.

1. Download Tomcat

You can get a copy of the version of Tomcat (5.5.26) that is currently being used for this course from the following local source: 

2. Install Tomcat

There are two different ways in which Tomcat can be installed.  In some versions, a conventional installation shield is included and you simply follow customary procedures in installing it.  You will also be given an option to make it a service so that it may start automatically when your system is booted or manually through the normal system services panel.  5.5.26 does include a shield version, marked by the .exe suffix on the download file, and is the version recommended for this course.

In other versions, you will not find an installation shield.  For these, you would copy the zip file to your machine, unzip it, and put the resulting directory structure in a convenient location.  You would then start and stop tomcat from the command line, as explained in the internal documentation. 

Note that you may need to download a Java Runtime Environment (jre) and set the JAVA_HOME environment variable to point to it.

I suggest that you set up a directory where you are going to do your Java development work for this course and create a directory structure similar to the one used in class members' subdirectories.  In discussing paths, etc., below, I'll assume that you have such a directory structure.

3. Run Tomcat

To run Tomcat, you may have two options.  If you installed it with an installation shield, you can start and stop it from the start button or from the services panel.

Alternatively,  you can open a Command Prompt window and cd to the tomcat root directory.  Then, type the command:  bin\tomcat5.exe.   To stop Tomcat, type ctrl-c. 

You can run Tomcat as it comes "out of the box," but you are likely to want to set several parameters to tailor it to your environment.  The next item discusses several useful options.

4.  Create Servlet Directory

By default, Tomcat looks for servlets in the webapps/WEB-INF/classes directory.  On your personal development machine, you may place your servlets class files there and then access them with your local browser as: http://localhost:8888/servlet/my_servlet.  However, I suggest you create a directory structure identical to the one you will be deploying to for your course assignments.  It is the following:

your_login 
	index.html
	source
	WEB-INF 
		classes 
		lib

5. Set Parameters: server.xml

You can set a bewildering range of configuration parameters.  Several that I suggest changing are discussed, below.

The files that contain the parameters you are likely to want to change are contained in the conf directory.  Before you change anything in any configuration file, make a copy of it.  Don't be intimidated by the XML if you are not familiar with it.  You are likely to have to change values in only a couple of places or copy and paste a small block of statements in which you will then change a value or two. 

Several of the parameters you are likely to want to change are included in the server.xml file:

port:  it is set, by default, to 8080; I suggest changing it to 8888 to make it compatible with the wwwj:8888 server we are using for this course.  Search for port in the file and change the value there.

course work root:  by default, Tomcat uses the webapps/ROOT directory as the root of its document tree.  In the previous step, you created an analogous root directory for your coursework.  Here, you need to provide a path alias so that the server may reference that directory.  To do that, add a tomcat context, similar to the following, to your server.xml file:

        <Context path="/jbs" 
                 docBase="D:\MyData\Courses\comp426\members\jbs" 
                 crossContext="false"
                 debug="0" 
                 reloadable="true" > 
        </Context>

You may then access it as:  http://localhost:8888/your_login/servlet/my_servlet.  For example, I have a servlet called jbsGetPostEcho that can be accessed from the following url: http://wwwj.cs.unc.edu:8888/jbs/servlet/jbsHelloWorld. You can do the same.

6. Enable the Invoker Servlet: web.xml

In most production environments, a Web administrator would establish convenient names for public servlets and map them to the servlet classes that implement them.  However, in a development environment, which is the type of environment this lesson is discussing, it is more convenient to enable a general mechanism that can be used to run arbitrary servlets that can be added to the server or replaced on the fly.  To do this, you must enable the so-called invoker servlet that is shipped as part of Tomcat.

Whereas the invoker can be enabled for individual directories, it is often most convenient to do so globally for the server so that servlets in any directory can all be run in a similar manner.  To do this, you need to make two blocks of xml code visible in the web.xml file contained in the server's conf directory.  I suggest you open that file for editing in a simple text editor, such as Notepad, Wordpad, or something similar (as opposed to one that may insert formatting marks into your "text").

There, you will find two xml blocks that include references to the invoker.  Make these visible by removing or neutralizing and comment marks that might be hiding them.  The blocks are the following:

    <!-- uncommented by jbs --> 
    <servlet>
        <servlet-name>invoker</servlet-name>
        <servlet-class>
          org.apache.catalina.servlets.InvokerServlet
        </servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

    <!-- uncommented by jbs -->
In the version of Tomcat that I have, these lines are not commented out and, hence, are already visible.

The second, and critical, block is the following:

    <!-- uncommented by jbs --> 

    <servlet-mapping>
        <servlet-name>invoker</servlet-name>
        <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping>

    <!-- uncommented by jbs -->
Rather than remove the comment marks, I simply "neutralized" them by adding closing and opening marks to the the top and bottom marks, respectively.

The first block of xml maps the name, invoker, to the class that implements the invoker servlet.  The second maps the path component /servlet/* to the invoker servlet.  Thus the path, jbs/servlet/jbsHelloWorld, specifies the following:

  1. jbs is a directory mapped in the server.
  2. servlet is a key word indicating that the name that follows is to be interpreted as a servlet and to be run or invoked.
  3. jbsHelloWorld is a servlet class, to be found in the WEB-INF/classes directory below the jbs directory.

You may also wish to "turn on" display of folders/directories so that if no default file, such as index.html, is present, the server will return a list of the files and directories at that URL address.  To do so, you need to set the value of the listings parameter in the default servlet to true, as shown in the example below.  This XML segment is found at the top of the web.xml file within the specification for the default servlet.:

<init-param>
	<param-name>listings</param-name>
        <param-value>true</param-value>
</init-param>

7.  Create a Tomcat UserName: tomcat-users.xml

When you address the general tomcat homepage (http://wwwj.cs.unc.edu:8888/) you will see several links for viewing the status of the server and for administering and managing the server.  In order to perform these functions on your development machines, you need to create a tomcat username and password that you provide, on prompt. 

To do this, you need to edit the tomcat-user.xml configuration file.  There your will see several roles defined and several example usernames, with associated roles.  Add a username similar to the following:

   <user username="jbs" password="xxxxxxxx" roles="tomcat,manager,admin"/>