COSC 2206: Internet Tools
Installing the Tomcat Web Server

These Notes Are For Tomcat Version 5.0.25

Getting and Installing Tomcat for Windows

In these notes we show you how to install the Tomcat server on Windows XP and configure it for testing servlets and JSP's. Since Tomcat is written in Java you will need to have Java installed before beginning the tomcat installation process. For example, you should have the Java SDK version 1.4.2 installed in a directory such as c:\j2sdk1.4.2.

You can find the Tomcat installation file on the CD as \software\tomcat-5.0.25\jakarta-tomcat-5.0.25.exe, or you can obtain it online from the Jakarta Project home page at http://jakarta.apache.org/tomcat/, locating the binary section of downloads, and finding the file jakarta-tomcat-5.0.25.exe in the bin directory to download (do not download the zip version).

If you have a previous version of Tomcat installed you should uninstall it. When you have the exe file double click on it to begin the automated installation process. After accepting the license agreement you will see the screen

The next screen asks for the Tomcat installation directory. Change the "Destination Folder" value to the shorter one c:\tomcat (directories and files containing spaces can cause problems) which will be assumed in these installation instuctions:

The next screen asks for an administrator password for user admin.

Choose a password (you can just use admin for your local PC) and leave the http port at 8080 (Note: If Tomcat is the only web server you will be running concurrently then you can change this to the default value 80 so that the port doesn't need to be specified in URL's. For our course leave it at 8080 because we are using the Apache Web Server at port 80).

The next screen asks for the path to the JVM (Java Virtual Machine) and shows a default path.

WARNING: This screen has an error in it: the screen refers to the "Java Virtual Machine" and it should refer to the "Java Software Development Kit". You must change the path on this screen to the directory in which you installed the Java SDK (software development kit).

This should be c:\j2sdk1.4.2 if you followed the Java install instructions. This directory will be assumed in these notes as shown:

When the installation process is completed you will see the final screen

The "Run Apache Tomcat" checkbox is misleading: it doesn't actually run Tomcat. Instead it runs the Tomcat monitor which allows us to start and stop the Tomcat server. Leave it checked. Uncheck the "Show Readme" box and click finish.

Tomcat 5 is now installed and we need to learn how to start, stop and configure it.

The installation process places various items on the start menu:

If you select menu item "Tomcat 5.0 Program Directory" you should see the installation directory

Later we will explain some of the subdirectories shown here.

Backing up important configuration files

Starting and Stopping the Tomcat Server

It's the first one on the left [If you don't have this icon then choose the "Montor Tomcat" entry from the start menu].

Double-click this icon to see the following preferences window:

On the "General" tab you will notice that the server status is "Stoppped" indicating that Tomcat is not yet running. Click the "Start" button to start the server (to stop a running server you would click the "Stop" button):

You can now close this window (click OK). The status of the server can always be determined by clicking the Apache-Tomcat icon in the system tray. If the icon is not there then as mentioned above choose "Monitor Tomcat" from the start menu.

Testing the Server

http://localhost:8080/

This home page contains complete documentation of the Tomcat server. If you don't see it maybe your server is stopped and you need to start it.

Compiling a Simple Java Servlet

javax.servlet
javax.servlet.http

c:\tomcat\common\lib\servlet-api.jar

javac -classpath .;c:\tomcat\common\lib\servlet-api.jar HelloWorld.java

To test your compiler setup create the following file, save it as HelloWorld.java, and compile it. For now you can put this file in any directory. Later we will learn how to install it as a servlet in a web application.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class HelloWorld extends HttpServlet {

   public void doGet(HttpServletRequest request, 
      HttpServletResponse response)
      throws IOException, ServletException
   {
      response.setContentType("text/html");

      PrintWriter out = response.getWriter();

      out.println(
          
          "<html>\n" +
             "<head>\n" +
	          "<title>Hello World</title>\n" +
             "</head>\n" +
          "<body>\n" +
          "<h1>Hello World</h1>\n" +
          "This html document was produced by a servlet.\n" +
          "</body>\n" +
          "</html>\n"
      );
      out.close();
   }
}

Documentation for Tomcat, Servlets and JSP

http://localhost:8080/tomcat-docs/index.html

Alternatively you can find the Tomcat documentation at c:\tomcat\webapps\tomcat-docs\index.html and "Servlet/JSP Javadocs" at c:\tomcat\webapps\tomcat-docs\servletapi\index.html You can make shortcuts to these links on the desktop.

Web Applications and the Context Path

A web application is a collection of Java servlet class files and other Java classes, html pages, Java Server Pages, and related resources such as image files that make up an application such as an online store that can be deployed by the web server.

Each web application is rooted in a context path which, by default, is a subdirectory of the Tomcat web application directory webapps:

Here the directory c:\tomcat\webapps is the default directory for installing web applications. Here we see six web application directories. Each is called a context path. These applications come with the Tomcat distribution and we will show how to add our own.

• The servlet-examples context path contains some sample Java servlets that can be accessed from the Tomcat home page (http://localhost:8080/) or using the URL http://localhost:8080/servlet-examples/.
• The jsp-examples context path contains some sample Java Server Pages that can be accessed from the Tomcat home page (http://localhost:8080/) or using the URL http://localhost:8080/jsp-examples/.
• ROOT is the default context path. It contains the home page that appears when you use the URL

  http://localhost:8080/
  

• The tomcat-docs context path contains the complete documentation for the Tomcat server, Java servlets, and Java Server Pages. It can be started using the URL

  http://localhost:8080/tomcat-docs/
  

• The webdav context path defines an application that can be used for remote web site authoring. We will not use it. Also I have no idea what the balancer application does so don't touch it.

Creating Your Own Web Application

• Stop the Tomcat server if it is running
• Create a directory called test.
• Create a standard subdirectory structure for it.
• Copy or move this directory into the webapps directory.
• Restart the server.

The web application directory structure

• HTML files, if any, can go in the test directory itself or in any subdirectory.
• The images directory can be used to hold any images required by the application.
• JSP files (Java Server Pages) can go in the test directory itself or in any subdirectory. It is common to put them in a jsp directory as shown in the directory tree.
• The WEB-INF directory holds the Java classes, jar files and configuration files used by the web application.
• The classes directory, inside the WEB-INF directory, holds the Java class files. The web server looks for any class files and packages in this directory so the package structure, if any, is created below the classes directory. Packageless classes go directly in the classes directory. We will also put our Java source files here although in real applications it is best to keep them separate and outside the application directories.
• The lib directory is optional and is needed only to contain jar files used by your application, such as a JDBC database driver.
• The jsp directory inside WEB-INF is used for Java server page tag libraries.
• A file called web.xml must be placed in the WEB-INF directory. It can be used to specify mappings of Java servlet class names to the names that appear in URL's, as well as application and servlet initialization parameters.

Make this directory structure and for the web.xml file just copy the one in the tomcat-docs application, c:\tomcat\webbapps\tomcat-docs\WEB-INF\web.xml, and edit it so that it looks like

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <display-name>Test Application</display-name>
  <description>
     An application for testing servlets and JSP
  </description>
</web-app>

The directory structure for test application should now look like

   test (dir)
     |
     +--- images (dir)
     |
     +--- jsp (dir)
     |
     +--- WEB-INF (dir)
             |
             +--- classes (dir)
             |
             +--- lib (dir)
             |
             +--- web.xml

Using a custom prompt for compiling classes

A simple approach to compiling servlets in our web application called test is to create a batch file called c:\batfiles\testservlets.bat containing the statements

@echo off
echo Setting path for Java 1.4.2
echo Setting classpath for test servlets and JSP
SET PATH=c:\j2sdk1.4.2\bin;%PATH%
SET CLASSPATH=.;c:\tomcat\webapps\test\WEB-INF\classes;
SET CLASSPATH=%CLASSPATH%;c:\tomcat\common\lib\servlet-api.jar

Then you can make a custom command prompt shortcut called testservlets on the desktop or in the c:\batfiles directory (find your command prompt on the start menu and drag a shortcut to the desktop) whose program properties look like

Here the "Target" directory is

%SystemRoot%\system32\cmd.exe  /k  c:\batfiles\testservlets.bat

 
%HOMEDRIVE%\tomcat\webapps\test\WEB-INF\classes

You can customize the working and batch file directories yourself and add other classpaths if needed.

Now you can compile Java classes for servlets: When you double-click this prompt the testservlets.bat file will execute and set the path and the classpath.

To test your custom prompt copy the HelloWorld.java file created earlier to the classes directory of the test application:

   c:\tomcat\webapps\test\WEB-INF\classes\HelloWorld.java

If you want to use a separate development directory then, after compiling, you will have to copy your class files to the test application deployment classes directory.

Running the HelloWorld servlet in a browser

There are two ways to run a servlet in our test application:

• Use the default servlet invoker.
• Use servlet-URL mappings in the test context's web.xml file.

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

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

    <!-- The mapping for the invoker servlet -->
<!--
    <servlet-mapping>
        <servlet-name>invoker</servlet-name>
        <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping>
-->

    <!-- The mapping for the invoker servlet -->
    <servlet-mapping>
        <servlet-name>invoker</servlet-name>
        <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping>

Restart the server (stop it if it is running then start it )then run the HelloWorld servlet, that you compiled in the test application classes directory, using the following URL in a browser

http://localhost:8080/test/servlet/HelloWorld

The URL contains the name of the context path test and the full name of the Java class file. The word servlet indicates that we are using the default method for referring to a servlet. The word servlet here does not refer to any directory. It simply indicates that the full class name of the servlet follows. Later we will discuss a better way to refer to servlets by placing mapping entries into the web.xml file in the WEB-INF subdirectory.

Using servlets in packages

package mypackage;

This html document was produced by a servlet in a package.

javac HelloWorld.java

http://localhost:8080/test/servlet/mypackage.HelloWorld

Registering (deploying) a web application

This is recommended on a production server but not on a development server such as ours, where we may compile classes many times during development. We don't want to continually stop and restart the server. This can be avoided by providing a "context configuration file" that overrides the default configuration of a web application. This context file has the same name as the context so in our test application it is called test.xml and contains the following lines.

<?xml version='1.0' encoding='utf-8'?>
<!-- Make the test application reloadable -->
<Context path="/test" reloadable="true">
</Context>

This file must be placed in directory

C:\tomcat\conf\Catalina\localhost

c:\tomcat\conf\Catalina\localhost\test.xml

NOTE :When you have made this modification stop the Tomcat server and start it again so that the new configuration will be read. Now as you make changes to the test application you will not need to stop and start the server all the time.

Using web.xml to define servlet mappings

In fact it is recommended that the servlet invoker not be used on a production server since it is unsupported. Therefore after developing a servlet on our PC we will always provide servlet mappings and use them always.

For the test application edit the file c:\tomcat\webapps\test\WEB-INF\web.xml so that it looks like

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

  <display-name>Test Application</display-name>
  <description>
     An application for testing servlets and JSP
  </description>

<servlet>
   <servlet-name>Example1</servlet-name>
   <servlet-class>HelloWorld</servlet-class>
</servlet>

<servlet>
   <servlet-name>Example2</servlet-name>
   <servlet-class>mypackage.HelloWorld</servlet-class>
</servlet>

<servlet-mapping>
   <servlet-name>Example1</servlet-name>
   <url-pattern>/helloa</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>Example2</servlet-name>
   <url-pattern>/hellob</url-pattern>
</servlet-mapping>

</web-app>

If you don't want to type it in download it: web.xml. It is also available on the CD in directory \install-notes\tomcat\web.xml It is very important to keep the tags in web.xml in the correct order. For example, the <servlet> tags must all be together, the <servlet-mapping> must all be together and they must follow the <servlet> tags.

The <servlet> tags define the logical names Example1 and Example2 for our two HelloWorld servlets. They map the class names into servlet names. Then the <servlet-mapping> tags associate these servlet names with the URL patterns helloa and hellob.

Before these mappings become active we need to get the Tomcat server to re-read the web.xml file. Do this now by stopping the server and then starting it again (the Tomcat manager web application can do this without stopping the server).

Now we can refer to the original HelloWorld servlet using the much simpler URL

http://localhost:8080/test/helloa

http://localhost:8080/test/hellob

Here is a small HTML file index.html that shows how to refer to servlets in links in html pages using the servlet mappings that we have defined. Put it in your test directory:

<html>
<head><title>Testing Servlets</title></head>
<body>
<h1>Testing servlets in the test application</h1>
These servlets are developed in the Tomcat install notes.
<p>HelloWorld servlet using the servlet mapping
<code>helloa</code>
<p><a href="helloa">helloa</a>
<p>HelloWorld servlet in package using the servlet mapping
<code>hellob</code>
<p><a href="hellob">hellob</a>
</body>
</html>

http://localhost:8080/test/

Testing JSP pages

<html>
<head><title>JSP Test</title></head>
<body>
<h1>JSP Test</h1>
Time: <%= new java.util.Date() %>
</body>
</html>

To run this file use the URL

http://localhost:8080/test/jsp/hello.jsp

Using JDBC and MySQL in Servlets

JDBC and MySQL can be used in standalone Java command-line applications and also in web applications. To use the MySQL driver in our test application for Servlets and JSP it is only necessary to put the driver file in directory C:\tomcat\webapps\test\WEB-INF\lib (See Installing JDBC drivers for MySQL).

If you want the driver to be available to all web applications put it in c:\tomcat\common\lib.

The test Web Application

However, you will learn more if you create it step by step yourself by following these notes and the JDBC notes.

When you have finished creating your test application you can replace it by the one in test.zip which has an expanded index.html file and also includes the servlets from the JDBC install notes (they won't work until you have read the JDBC install notes and installed the JDBC driver).

To try it use the link

http://localhost:8080/test

Creating a web application for Cosc 2206

Also you will need to create a new context configuration file as was done above for the test application.

Use your last name as the name of this context. For example, if your last name is jones then create the file jones.xml containing the lines.

<?xml version='1.0' encoding='utf-8'?>
<!-- Make the jones application reloadable -->
<Context path="/jones" reloadable="true">
</Context>

C:\tomcat\conf\Catalina\localhost

c:\tomcat\conf\Catalina\localhost\jones.xml

Installing JDBC drivers for MySQL and Windows