Tomcat Introductory Tutorial
Tomcat Introductory Tutorial
This tutorial gives a brief overview of the servlet engine but for a thorough introduction to the
application it is strongly advised that one reads the documentation that accompanies the
application. This tutorial also serves to demonstrate how one builds a web application with the
Tomcat technology by going through the paces of building a sample application.
Overview
• Installing Tomcat
• Deployment Organization
• Source Organization
• The Actual Development Process
• Integrating a Sample Application with Tomcat
Introduction To Tomcat
Overview
Tomcat is the Reference Implementation for the Java Servlet 2.2 and JavaServer Pages 1.1
Technologies. It is the official reference implementation for these complementary technologies.
Tomcat is a servlet container with a JSP environment. A servlet container is a runtime shell that
manages and invokes servlets on behalf of users.
Developed under the Apache license in an open and participatory environment, Tomcat is intended
to be a collaboration of the best-of-breed developers from around the world. The latest release of
this technology can be downloaded from this page.
This document may be used to understand the web application directory structure and deployment
file (Chapter 9), methods of mapping request URLs to servlets (Chapter 10), container managed
security (Chapter 11), and the syntax of the web.xml, Web Application Deployment Descriptor
(Chapter 13).
Installation
Tomcat will operate under any Java Development Kit (JDK) environment that provides a JDK 1.1
or JDK 1.2 compatible platform. The JDK is required so that your servlets, other classes, and JSP
pages can be compiled.
Once you have downloaded the required file, unzip it to a directory of your choice. (In the
Microsoft Lab 5 at UWI the file is extracted directly to the C drive (C:\) ). A sub-directory named
jakarta-tomcat is created and this is the root directory of the tomcat hierarchy.
This sub-directory should contain the following directories as highlighted in the table
below. A description of the directories is also given.
Directory
Description
name
The following directories may also be present in the root directory of our Tomcat hierarchy
structure:
For a detailed review of the scripts and configuration files provided with Tomcat please take a look
at the uguide\tomcat_ug.html file located in the doc directory.
Deployment Organization
Background
Before describing how to organize your source code directories, it is useful to examine the runtime
organization of a web application. Prior to the Servlet API Specification, version 2.2, there was
little consistency between server platforms. However, servers that conform to the 2.2 specification
are required to accept a Web Application Archive in a standard format, which is discussed further
below.
A web application is defined as a hierarchy of directories and files in a standard layout. Such a
hierarchy can be accessed in its "unpacked" form, where each directory and file exists in the
filesystem separately, or in a "packed" form known as a Web ARchive, or WAR file. The former
format is more useful during development, while the latter is used when you distribute your
application to be installed.
The top-level directory of your web application hierarchy is also the document root of your
application. Here, you will place the HTML files and JSP pages that comprise your application's
user interface. When the system administrator deploys your application into a particular server, he
or she assigns a context path to your application. Thus, if the system administrator assigns your
application to the context path /catalog, then a request URI referring to /catalog/index.html will
retrieve the index.html file from your document root.
To facilitate creation of a Web Application Archive file in the required format, it is convenient to
arrange the files that Tomcat actually uses when executing your application in the same
organization as required by the WAR format itself. To do this, you will have the following contents
in your application's "document root" directory:
• *.html, *.jsp, etc. - The HTML and JSP pages, along with other files that must
be visible to the client browser (such as JavaScript and stylesheet files) for your
application. In larger applications you may choose to divide these files into a
subdirectory hierarchy, but for smaller apps, it is generally much simpler to
maintain only a single directory for these files.
• WEB-INF/web.xml - The Web Application Deployment Descriptor for your
application. This is an XML file describing the servlets and other components
that make up your application, along with any initialization parameters and
container-managed security constraints that you want the server to enforce for
you. This file is discussed in more detail in the following subsection.
• WEB-INF/classes/ - This directory contains any Java class files (and associated
resources) required for your application, including both servlet and non-servlet
classes, that are not combined into JAR files.
• WEB-INF/lib/ - This directory contains JAR files that contain Java class files (and
associated resources) required for your application, such as third party class
libraries or JDBC drivers.
When you install an application into Tomcat (or any other 2.2-compatible server), the classes in the
WEB-INF/classes/ directory, as well as all classes in JAR files found in the WEB-INF/lib/
directory, are added to the class path for your particular web application. Thus, if you include all of
the required library classes in one of these places (be sure to check licenses for redistribution rights
for any third party libraries you utilize), you will simplify the installation of your web application --
no adjustment to the system class path will be necessary.
As mentioned above, the WEB-INF/web.xml file contains the Web Application Deployment
Descriptor for your application. As the filename extension implies, this file is an XML document,
and defines everything about your application that a server needs to know (except the context path,
which is assigned by t he system administrator when the application is deployed).
The complete syntax and semantics for the deployment descriptor is defined in Chapter 13 of the
Servlet API Specification, version 2.2. Over time, it is expected that development tools will be
provided that create and edit the deployment descriptor for you. In the meantime, to provide a
starting point, a basic web.xml (text file) is provided in the doc/appdev. This file includes comments
that describe the purpose of each included element.
Integration With Tomcat
In order to be executed, a web application must be integrated with, or installed in, a servlet
container. This is true even during development. We will describe using Tomcat to provide the
execution environment. A web application can be deployed in Tomcat by one of three different
approaches:
Integrating your app with other servlet containers will be specific to each container, but all
containers compatible with the Servlet API Specification (version 2.2) are required to accept a web
application archive file.
Source Organisation
Directory Structure
A key recommendation is to separate the directory hierarchy containing your source code from the
directory hierarchy containing your deployable application (described in the preceding section).
Maintaining this separation has the following advantages:
• The contents of the source directories can be more easily administered, moved,
and backed up if the "executable" version of the application is not intermixed.
• Source code control is easier to manage on directories that contain only source
files.
• The files that make up an installable distribution of your application are much
easier to select when the deployment hierarchy is separate.
As we will see, the ant development tool makes the creation and processing of such directory
hierarchies nearly painless.
The actual directory and file hierarchy used to contain the source code of an application can be
pretty much anything you like. However, the following organization has proven to be quite
generally applicable, and is expected by the example build.xml configuration file that is discussed
below. All of these components exist under a top level project source directory for your application:
• etc/ - Directory containing special files related to your application that will be
copied to the WEB-INF directory. In all cases, this will include the application
deployment descriptor file (web.xml), but may include others as well.
• lib/ - Directory containing JAR files that will be copied to the WEB-INF/lib
deployment directory.
• src/ - Java source files that generate the servlets, beans, and other Java classes
required by your application. If your source code is organized into packages
(highly recommended for large projects), the package hierarchy should be
reflected as a directory structure underneath this directory.
• web/ - Directory containing the HTML files, JSP pages, and other resource files
(such as JavaScript and stylesheet files) that will be accessible to browser
clients. The entire hierarchy underneath this directory will be copied to the
document root directory of your deployment home.
We will be using the ant tool to manage the compilation of our Java source code files, and creation
of the deployment hierarchy. Ant operates under the control of a build file, normally called
build.xml, that defines the processing steps required. Like a Makefile, the build.xml file provides
several "targets" that support optional development activities, such as creating the associated
Javadoc documentation, erasing the deployment home directory so you can build your project from
scratch, or creating the web application archive file so you can distribute your application.
To give you a head start, a basic build.xml file is provided (in the doc/appdev folder) that you can
customize and install in the project source directory for your application. This file includes
comments that describe the various targets that can be executed. The following targets are generally
provided:
Batch Scripts
The primary script we will utilize is generically called the build script. It executes Ant, which reads
and processes the build.xml file discussed above. Each time you execute the build script, you will
specify the build "target" that you wish to execute. Users of a command line MAKE tool (which
processes a makefile) will recognize this approach.
On Windows-based systems, the following script should be saved as file build.bat in the project
source directory, and customzed as required:
echo off
rem Build Script for "My Application"
rem $Id: source.html,v 1.2 2000/03/28 00:44:11 craigmcc Exp $
NB. The batch files found in %TOMCAT_HOME%\bin have been written and
tested under Windows NT. Some modifications may be necessary for
operation on a Windows 98 platform.
The following sections highlight the commands and tasks that you, as the developer of the code,
will perform. The same basic approach works when you have multiple programmers involved, as
long as you have an appropriate source code control system and internal team rules about who is
working on what parts of the application at any given time.
The first step is to create a new project source directory, and customize the build.xml and build
script you will be using. The directory structure is described in the section labeled Source
Organization, or you can use the sample application located in doc/appdev as a starting point.
In order for Tomcat to recognize your application, you must integrate it as described in the section
labeled Integration with Tomcat. Any of the proposed techniques can be used. For our purposes, we
will assume that you are using the first approach (unpacked hierarchy), because we set the
deployment home to be an appropriate directory under the %TOMCAT_HOME%/webapps
directory.
One may make changes to any of the source files (java, html, scripts, etc) and once saved we are
ready to build our web application. We compile the application by issuing the build command from
the project source root directory. The Ant tool will be utilized to compile any new or updated Java
code.
We do this once we have ensured that the following variables have been set:
• The JAVA_HOME points at the base directory where you have installed the JDK
(for example, c:\jdk1.2.2).
• The TOMCAT_HOME points at the base directory where you have installed
Tomcat (for example, c:\jakarta-tomcat).
To test your application, you will want to execute it under Tomcat. Assuming you have integrated
your application as described earlier, this is very simple. Under Windows, execute:
%TOMCAT_HOME%\bin\startup
This command starts Tomcat as a background process. Now, point your web browser
at the home page for your application, by opening the following URL (where "/myapp"
is the context path you have assigned to it):
http://localhost:8080/myapp
Now, you can test your application to verify that it operates correctly. When you
discover something that needs to change, fix it as follows:
• To change a JSP page, modify it in the source directory and then re-execute the
build script. The updated page will be recopied, and Tomcat will recognize this
the next time that page is accessed -- the page will then be recompiled
automatically.
• Changing a servlet or other Java class is similar, but the effort required depends
on whether you selected the "autoreload" attribute for this context when you
integrated with Tomcat. First, edit the file in its source directory, and re-execute
the build script. The updated Java class will be recompiled. If autoreloading is
selected, Tomcat will notice this change the next time this class is referenced,
and will automatically unload and reload your application. Otherwise, you will
need to manually stop and restart Tomcat before continuing.
Do not forget to commit your changes to the source code repository when you have
completed your testing!
Deploy Your Web Application
When you are through adding new functionality, and you've tested everything, it is
time to create the distributable version of your web application that can be deployed
on the production server. The following general steps are required:
• Issue the command build all from the project source directory, to rebuild
everything from scratch one last time.
• Issue the command build dist to create a distributable web application archive
(WAR) file, as well as a JAR file containing the corresponding source code.
• Give the WAR file to the system administrator of your production server
environment, so that he or she can install it.
NB. The batch files found in %TOMCAT_HOME%\bin have been written and
tested under Windows NT. Some modifications may be necessary for
operation on a Windows 98 platform.
NB. The batch files found in %TOMCAT_HOME%\bin have been written and
tested under Windows NT. Some modifications may be necessary for
operation on a Windows 98 platform.
If you surf to the following site and scroll to the bottom of the page you will see a hyperlink labeled
Download Sample DataAccess Servlet. Click on the link and save the respected zip file to a
directory on your drive. Now unzip the file to the same directory and you see the following files:
• shod\register\Student.java
• StudentDBServlet.java
• students.mdb
• index.html
• compile.bat
• StudentRegistration.html
• README_SETUP.html
1. Open the build.xml file in a text editor and change the following line
to read
2. Open the build.bat file in a text editor also and add the following lines in the
respective area:
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jaxp.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\parser.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar
To
htmlBody += "<center><a href=../student>Return to Course
Home Page</a>";
To
6. Open the web.xml file and change to file to resemble the following:
7. <web-app>
8. <display-name>Stduent Database Demo</display-name>
9. <description>
10. This is a simple web application with a source code organization
11. based on the recommendations of the Application Developer's Guide.
12. </description>
13. <servlet>
14. <servlet-name>StudentServlet</servlet-name>
15. <servlet-class>StudentDBServlet</servlet-class>
16. </servlet>
17. <servlet-mapping>
18. <servlet-name>StudentServlet</servlet-name>
19. <url-pattern>/student</url-pattern>
20. </servlet-mapping>
21.</web-app>
22.
23.Please note that the url-pattern value DOES NOT have to
24.be the same as the value for the app.name property in the build.xml file.
As a result of the build command our application is now built (once there are no
errors) and you should see the following new folders, files in your application root
directory: javadoc and Web-inf directories and index.html and
StudentRegistration.html are now in the root directory of the sample application.
Now that our data source is set up we can test our application.
http://localhost:8080/student
NB. The batch files found in %TOMCAT_HOME%\bin have been written and
tested under Windows NT. Some modifications may be necessary for
operation on a Windows 98 platform.
Earlier in the tutorial you would have probably seen this message appear several
times and muttered an "Oh no" to yourself. However the modifications that are to be
made are indeed quite simple and in no time you can have Tomcat up and running on
your Window 98 platform.
Modification Overview
As mentioned earlier, some modification of the files that were distributed with the Tomcat
application has to be done. Before we go any further there is a requirement that must be satisfied
first for any modifications to be done. This is:
There are several files that are located in the %TOMCAT_HOME%\bin directory that have been
saved with a UNIX file format. These are primarily the files we need to start and stop the Tomcat
server and are as follow:-
• cpappend.bat
• jspc.bat
• shutdown.bat
• startup.bat
• tomcat.bat
• tomcatEnv.bat
The other file which must change its format is the build.bat file which is found in the root directory
of our application (webapps/application). NB This file is used to build our web application.
This UNIX format needs to be changed for the Windows 9x platform and without
making this change if we try to run the files we get a Bad Command or Filename error
being displayed.
Modification Process
TextPad
To modify these files using TextPad, open each respective file in the TextPad editor. Select File
from the Menu bar and choose Save As. A pop-up window is displayed with the name of the file
shown in a textbox labeled File name. This is to remain unaltered, however the only change we
will make is to the File Format option. Select PC from the List box instead of UNIX. Click the
Save button to save this change...and that is it. We are finished modifying the file format. Repeat
the procedure for each file.
Use the respective conversion tool of your choice to change the files listed above from having a
File Format value of UNIX to PC.
Modification Review
That is all that is required to get your batch scripts working on a Windows 9x platform. Once these
changes have been made you can build your web application and then start and stop your Tomcat
server when testing the application.
There is one other important concern when running the Tomcat application on the
Windows 98 platform. This concern is that of Environment Space. If enough
environment space has not been specified when running the batch scripts you may
get an error stating "Not enough environment space" or something similar.
To solve this problem we must enlarge the environment space to enlarge the
environment space we must set the following command in the CONFIG.SYS file. The
CONFIG.SYS is found in your C directory (C:\). (This file is usually hidden so one must
change the view properties in order to see it, or simply use the command window to
edit the file)
SHELL=C:\Windows\COMMAND.COM /P /E:4096