The preceding discussion provides a brief introduction to servlets and JSP pages, but says nothing about how you actually use a server to run them. This section describes how to install Tomcat, a JSP-aware web server. Tomcat, like Apache, is a development effort of the Apache Software Foundation.
As described earlier, servlets execute inside a container, which is an engine that communicates with or plugs into a web server to handle requests for pages that are produced by executing servlets. Some servlet containers can operate in standalone fashion, such that they function both as container and web server. That is how Tomcat works. By installing it, you get a fully functioning server with servlet-processing capabilities. In fact, Tomcat is a reference implementation for both the servlet and JSP specifications, so it also acts as a JSP engine, providing JSP-to-servlet translation services. The servlet container part is named Catalina, and the JSP processor is named Jasper.
It’s possible to use the container part of Tomcat in conjunction with other web servers. For example, you can set up a cooperative arrangement between Apache and Tomcat under which Apache acts as a front end that passes servlet and JSP requests through to Tomcat and handles other requests itself. You can find information about setting up Apache and Tomcat to work together this way on the Tomcat web site.
To run a Tomcat server, you need three things:
This is required because Tomcat needs to compile Java servlets as part of its operation. You most likely already have an SDK installed if you’ve been compiling Java programs while reading earlier chapters. If you don’t have an SDK, see Appendix B for information on obtaining and installing one.
Tomcat is available from http://tomcat.apache.org. A fair amount of Tomcat documentation is available there, too. In particular, if you’re a newcomer to Tomcat, I recommend that you read the Introduction and the Application Developer’s Guide.
Tomcat configuration files are written as XML documents, and many scripting elements within JSP pages follow XML syntax rules. If you’re new to XML, the “XML and XHTML in a Nutshell” sidebar in Introduction describes some of its characteristics in comparison to HTML.
Currently, Tomcat is available in several versions (such as 4.1, 5.0, and 5.5). This section describes Tomcat 5.0. The instructions should also work for Tomcat 5.5, although you might need to upgrade your version of Java (Tomcat 5.5 requires JS2E 5.0).
To install Tomcat, get a binary distribution from tomcat.apache.org. (I assume that you don’t intend to build it from source, which is more difficult.) Tomcat distributions are available in several file formats, distinguished by filename extensions that have the following meanings:
If you’re using Linux, the vendor of your Linux distribution might make Tomcat available on the distribution media or via an online APT or RPM repository. This method is not covered here in any depth. See your Linux distribution documentation or contact your vendor for details.
For a distribution packaged as a tar or ZIP file, you should place it in the directory under which you want to install Tomcat, and then run the installation command in that directory to unpack the distribution there. The Windows .exe installer prompts you to indicate where to install Tomcat, so it too can be run from any directory. The following commands are representative of those needed to install each distribution type. (Change the version numbers in the filenames to reflect the actual Tomcat distribution that you’re using.)
To install Tomcat from a compressed tar files, unpack it like this:
%tar zxf jakarta-tomcat-5.0.28.tar.gz
If you have trouble unpacking a Tomcat tar file distribution under Mac OS X, use gnutar rather than tar. On older versions of Mac OS X, tar has some problems with long filenames that gnutar does not. (In current versions, both programs are the same.) It may also be necessary to use a GNU-compatible version of tar under Solaris.
If your version of tar
doesn’t understand the z
option, do
this instead:
%gunzip -c jakarta-tomcat-5.0.28.tar.gz | tar xf -
If you use a ZIP archive, you can unpack it with the jar utility or any other program that understands ZIP format (such as the Windows WinZip application). For example, to use jar, do this:
%jar xf jakarta-tomcat-5.0.28.zip
The Windows .exe distribution is directly executable. Launch it, and then indicate where you want to place Tomcat when the installer prompts for a location. If you use this installer, be sure that you already have a Java SDK installed first; the installer puts some files into the SDK hierarchy, an operation that fails if the SDK isn’t present. For versions of Windows that have service management (such as Windows NT, 2000, or XP), the .exe installer gives you the option of installing Tomcat as a service so that it starts automatically at system boot time.
Most of the installation methods create a directory and unpack Tomcat under it. The top-level directory of the resulting hierarchy is the Tomcat root directory. I’ll assume here that the Tomcat root is /usr/local/jakarta-tomcat under Unix. Under Windows, I’ll assume C:jakarta-tomcat. (The actual directory name likely will have a version number at the end.) The Tomcat root contains various text files containing information that is useful in the event that you have general or platform-specific problems. It also contains a number of directories. If you want to explore these now, see the section “Tomcat’s Directory Structure.” Otherwise, proceed to the next section, “Starting and Stopping Tomcat,” to find out how to run Tomcat.
Tomcat can be controlled manually, and also set to run automatically when your system starts up. It’s good to become familiar with the Tomcat startup and shutdown commands that apply to your platform, because you’ll probably find yourself needing to stop and restart Tomcat fairly often—at least while you’re setting it up initially. For example, if you modify Tomcat’s configuration files or install a new application, you must restart Tomcat to get it to notice the changes.
Before running Tomcat, you’ll need to set a couple of
environment variables. Make sure JAVA_HOME
is set to the pathname of your SDK
so that Tomcat can find it. You might also need to set CATALINA_HOME
to the pathname of the Tomcat
root directory.
To start and stop Tomcat manually under Unix, change location into the bin directory under the Tomcat root. I find that it’s useful to make the shell scripts in that directory executable (this is a one-time operation):
% chmod +x *.sh
You can control Tomcat with the following two shell scripts:
%./startup.sh
%./shutdown.sh
To run Tomcat automatically at system boot time, look for a startup script such as /etc/rc.local or /etc/rc.d/rc.local (the pathname depends on your operating system) and add a few lines to it:
export JAVA_HOME=/usr/local/java/jdk export CATALINA_HOME=/usr/local/jakarta-tomcat $CATALINA_HOME/bin/startup.sh &
These commands will run Tomcat as root
, however. To run it under a different
user account, change the last command to invoke Tomcat with su instead and specify the username:
su -c $CATALINA_HOME/bin/startup.shuser_name
&
If you use su to specify a
username, make sure that Tomcat’s directory tree is accessible to that
user or you will have file permission problems when Tomcat tries to
access files. One way to do this is to run the following command as
root
in the Tomcat root directory:
#chown -R
user_name
.
Linux users who install Tomcat from vendor-supplied package files may find that the installation creates a script named tomcat (or perhaps something like tomcat4 or tomcat5) in the /etc/rc.d/init.d directory that can be used manually or for automatic startup. To use the script manually, change location into that directory and use these commands:
%./tomcat start
%./tomcat stop
For automatic startup, you must activate the script by running
the following command as root
:
#chkconfig --add tomcat
Linux package installation also might create a user account with
a login name such as tomcat
or
tomcat5
that is intended to be used
for running Tomcat.
For Windows users, the distribution includes a pair of batch files in the bin directory for controlling Tomcat manually:
C:>startup.bat
C:>shutdown.bat
If you elected to install Tomcat as a service for versions of
Windows that have service management, such as Windows NT, 2000, or XP,
you should control Tomcat using the services console. You can use this
to start or stop Tomcat, or to set Tomcat to run automatically when
Windows starts. (The service name is Apache
Tomcat
.)
To try Tomcat, start it using whatever instructions are applicable to your platform. Then request the default page using your browser. The URL will look something like this:
http://localhost:8080/
Adjust your hostname and port number appropriately. For example, Tomcat normally runs on port 8080 by default, but if you install from package files under Linux, Tomcat may use a port number of 8180. If your browser receives the page correctly, you should see the Tomcat logo and links to examples and documentation. It’s useful at this point to follow the examples link and try a few of the JSP pages there, to see whether they compile and execute properly.
If you find that, despite setting the JAVA_HOME
variable, Tomcat can’t find your
Java compiler, try setting your PATH
environment variable to explicitly
include the directory containing the compiler. Normally, this is the
bin directory under your SDK
installation. You probably already have PATH
set to something already. If so, you’ll
want to add the bin directory to
the current PATH
setting. (See
Appendix B for information about setting your
PATH
value.)
3.21.106.7