Figure 1. A partially expanded directory tree for a Tomcat Installation
Published zz, 2001
By Richard G. Baldwin
Java Programming, Lecture Notes # 768
Viewing tip
You may find it useful to open another copy of this lesson in a separate
browser window. That will make it easier for you to scroll back and
forth among the different figures and listings while you are reading about
them.
zz
Tomcat is the Reference Implementation for the Java Servlet 2.2 and JavaServer Pages 1.1 Technologies. Tomcat is freely available for download. As of the date of this writing, you can download Tomcat at http://jakarta.apache.org/site/binindex.html.
Sun has delivered the latest versions of JSP and Servlets source code to Apache to be developed and released under the Apache development process. According to the announced plans, Apache, Sun and other companies and individuals will develop a reference implementation that is freely available to any company or individual. This reference implementation, named Tomcat, will be the official reference implementation for the JSP 1.1 and Servlet 2.2 technologies.
Who controls JavaServer Pages and Java Servlets
JavaServer Pages and Java Servlets Specifications are still owned by Sun. They will evolve under the Java Community Process. The reference implementation being developed under license at Apache (Tomcat) will be developed consistent with these specifications.
Therefore, Tomcat is the code name for the combined JSP 1.1 and Servlets 2.2 Reference Implementation being developed under the Apache Jakarta project.
What is Jakarta?
Jakarta is an Apache umbrella project that includes 3 subprojects related to JSP and servlet technology:
Downloading Tomcat
Three different versions of Tomcat are available for download: Nightly, Milestone, and Release builds.
Only release builds are considered stable, so unless you are adventuresome, you should download, install, and use the latest release build. As of the date of this writing, the current release build is Tomcat Release 3.2.1.
When you are ready to download, follow the above link and download the file named jakarta-tomcat-xxx.yyy. Various compression formats are available, so you should download the format that is appropriate for your system. In my case, since I use Windows NT, I downloaded and installed a file named jakarta-tomcat-3.2.1.zip.
J2EE
JavaServer Pages and Java Servlets are the web presentation layer in the Java 2 Platform, Enterprise Edition (J2EE) Platform. In order to ensure compatibility, a verification program is available under the Apache license. This program, called Watchdog, allows a developer to confirm that their JSP/Servlets implementation is consistent with the specifications and will work with any other JSP/Servlets implementation.
Values of my environment variables
Just so that you will have something tangible to sink your teeth into, the value of the JAVA_HOME environment variable on my NT machine is D:\progfile\jdk1.3. It will likely be different on your machine, depending on where you installed your JDK, and which version of the JDK you are using.
You must set the TOM_CAT environment variable to the installation directory of Tomcat. Again, on my machine, that is D:\progfile\jakarta-tomcat-3.2.1, but you can install Tomcat wherever you wish. (The value of this environment variable will come up again in a few minutes.)
Minimalistic documentation
One of the disappointing things about Sun's alliance with Apache is that Apache seems to be less inclined to provide good online documentation than Sun. Therefore, you must often do quite a bit of searching to locate information that you need. The User's Guide that I will refer you to shortly is entitled Tomcat - A Minimalistic User's Guide. I agree that it is pretty minimal, and incorrect in some cases.
Documentation files
When you have unzipped Tomcat into your installation directory of choice, you should be able to locate the following file and load it into your browser. Note that the top-level Tomcat directory name will probably change with the release of future versions of the software.
.../jakarta-tomcat-3.2.1/doc/index.html.
This is a top-level documentation file, which is also available at the Tomcat website. This file contains links to a variety of other documents. One of those other documents is the Tomcat User's Guide, which should be available on the Tomcat website and on your disk as well.
Detailed installation instructions
The User's Guide contains a very short section on Tomcat installation,
which I have copied below for easy reference. (Be careful of the
manual line breaks that I inserted to force the text to fit in this narrow
presentation format.)
Download the zip/tar.gz/whatever file from: http://jakarta.apache.org /downloads/binindex.html. Unzip the file into some directory (say foo). This should create a new subdirectory named "tomcat". Change directory to "tomcat" and set a new environment variable (TOMCAT_HOME) to point to the root directory of your Tomcat hierarchy. 1.On Win32 you should type: "set TOMCAT_HOME=foo\tomcat" 2.On UNIX you should type: for bash/sh "TOMCAT_HOME=foo/tomcat ; export TOMCAT_HOME" for tcsh "setenv TOMCAT_HOME foo/tomcat" Set the environment variable JAVA_HOME to point to the root directory of your JDK hierarchy, then add the Java interpreter to your PATH environment variable. |
These instructions are not only minimalistic, they are also a little misleading.
First, unziping the zip file for version 3.2 won't create a new subdirectory named "tomcat". For version 3.2.1, it will create a new subdirectory named jakarta-tomcat-3.2.1. I am assuming that the name of this directory will continue to change with the release of versions. This has an impact on the value that you give to the TOMCAT_HOME environment variable.
Second, rather than to set the two environment variables temporarily as indicated in the Win32 instructions, you might prefer to set them permanently either through the autoexec.bat file or the WinNT/2000 environment dialog.
Setting the PATH environment variable
The instruction to add the Java interpreter to your PATH environment variable doesn't have anything to do with Tomcat. Rather, that is a requirement when you install your Java Development Kit.
However, it is true that Tomcat won't work unless the Java Development Kit is properly installed. (You may be able to get by with just the JRE instead of the full JDK. I haven't tried that to see if it works.)
However, despite the fact that the above documentation contains a couple of questionable items, it does reinforce my earlier statement that installation of Tomcat is very easy.
Figure 1. A partially expanded directory tree for a Tomcat Installation
Figure 1 shows twenty-one separate directories, many of which have hidden subdirectories. When fully expanded, the directory tree is very large, showing about 2,400 files. The primary difficulty of using Tomcat is figuring out where to put your JSP, servlet, and JavaBeans component files.
There are many options and many different ways to configure Tomcat. I don't pretend to know about all of those different options. However, by studying the documentation, I have figured out two ways to arrange my files that seem to work, and also seem to be consistent with what Sun had in mind. I will show you the details of one of those ways, and briefly describe the other way. Once you begin using the product, you may find other better ways to arrange your files.
Early on, you will be primarily concerned with the directory tree consisting of the directory named webapps and its subdirectories. This directory tree comprises what is often referred to in the Sun literature as the Web Application Container, or Web Container for short.
Here is what the servlet 2.2 specification has to say about a Web Application.
A web application is a collection of servlets, html pages, classes, and other resources that can be bundled and run on multiple containers from multiple vendors. A web application is rooted at a specific path within a web server. For example, a catalog application could be located at http://www.mycorp.com/catalog. All requests that start with this prefix will be routed to the ServletContext which represents the catalog application. |
So, given this, what is a servlet context. Again, here is what
the specification has to say.
The ServletContext defines a servlet’s view of the web application within which the servlet is running. The ServletContext also allows a servlet to access resources available to it. Using such an object, a servlet can log events, obtain URL references to resources, and set and store attributes that other servlets in the context can use. The Container Provider is responsible for providing an implementation of the ServletContext interface in the servlet container. A ServletContext is rooted at a specific path within a web server. For example a context could be located at http://www.mycorp.com/catalog. All requests that start with the /catalog request path, which is known as the context path, will be routed to this servlet context. Only one instance of a ServletContext may be available to the servlets in a web application. In cases where the web application indicates that it is distributable, there must only be one instance of the ServletContext object in use per application per Java Virtual Machine. |
In case it isn't clear just what this means, I will try to clear it up later with specific examples.
zz
A web application is a collection of servlets, html pages, classes,
and other resources that can be bundled and run on multiple containers
from multiple vendors. A web application is rooted at a specific path within
a web server. For example, a catalog application could be located at http://www.mycorp.com/catalog.
All requests that start with this prefix will be routed to the ServletContext
which represents the catalog application.
If you work with the J2EE reference implementation later, you will find that it has both a Web Container and an Enterprise JavaBeans (EJB) Container. However, Tomcat doesn't provide the EJB container. Neither does it provide the fancy deployment tools that are provided by the J2EE reference implementation. With Tomcat, deployment is a more direct manual process.
According to the Sun Servlet API Specification, servers that conform to the 2.2 specification are required to accept a Web Application Archive in a standard format. This is a JAR file (actually a WAR file) containing JSP files, servlet class files, and JavaBeans Component files, with a specific organizational structure. Although this may be a little complicated to get used to, it will be beneficial in the long run. Prior to the release of version 2.2, there were no such standards, and the manner in which you organized your files for deployment in one server would likely be different from the manner in which you were required to organize them for deployment in another server.
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. Alternately, the hierarchy can be accessed in a "packed" form known as a Web ARchive, or WAR file. The open format is more useful during development, while the archive format is very useful when you distribute your application to be installed by others. In effect, when you distribute your application for installation in a conforming server, you are only required to be concerned with one format.
According to Sun, the top-level directory of your web application hierarchy is also the document root of your application. In Figure 1, the directories named baldwin and xyz are the document roots for two of my applications. The directories named admin, examples, Root, and test are the document roots of applications that were already installed when I unzipped the file that I downloaded. It is important to note that these document-root directories are all subdirectories of the directory named webapps.
You place the HTML files and JSP pages that comprise your application's user interface in the document-root directory, or some subdirectory of the document-root directory.
Note in particular in Figure 1 that the directory named baldwin has a subdirectory named webpgpub. Although it isn't apparent in Figure 1, the webpgpub directory contains a JSP file named jsp010.jsp. The following URI can be used to access that JSP page via a browser running on the same machine as the Tomcat server. (Don't be concerned about the meaning of localhost:8080 at this point. That is the host name and port number. I will have more to say about that later.)
http://localhost:8080/baldwin/webpgpub/jsp010.jsp
The important thing to note here is that the immediate subdirectories of the directory named webapps are exposed directly to clients of the server. In other words, insofar as the outside world is concerned, these directories (such as baldwin and examples) constitute the tops of directory trees that are accessible to clients. Directories that are not subdirectories of webapps are not accessible to clients. (Also, as I will explain later, the contents of the directory named Web-inf, and certain of its subdirectories, are not accessible to clients.)
As I mentioned earlier, this directory structure can either be open as shown in Figure 1, or can be encapsulated into a WAR file for deployment into the lib directories of the Tomcat server (or any other Servlet 2.2 compatible server).
So, now let me discuss the contents of each of these directories in a little more detail.
zz also look at the specs,
ch 9
======
*.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. If
your classes are organized into Java packages, you must reflect this in
the directory hierarchy under
WEB-INF/classes/. For example, a Java class named
com.mycompany.mypackage.MyServlet would need to be stored in a file named
WEB-INF/classes/com/mycompany/mypackage/MyServlet.class.
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.
Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.2, which you should consult for more details.
zz see http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/appdev/index.html
zz
zz Listing zz |
zz
zz
zz Listing 1 shows
zz Listing zz |
zz Listing zz |
Copyright 2000, Richard G. Baldwin. Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.
Richard has participated in numerous consulting projects involving Java, XML, or a combination of the two. He frequently provides onsite Java and/or XML training at the high-tech companies located in and around Austin, Texas. He is the author of Baldwin's Java Programming Tutorials, which has gained a worldwide following among experienced and aspiring Java programmers. He has also published articles on Java Programming in Java Pro magazine.
Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.
-end-