Chapter 2
How to install and
use Tomcat
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 1
Objectives
Applied
 Install and configure Tomcat so it runs on your own PC.
 Start Tomcat from a DOS prompt window, and shut it down
from this window.
 Turn on servlet reloading so you don’t have to stop and restart
Tomcat every time you want to change and test a servlet.
 Use your browser to enter a URL that accesses an HTML
document, JSP, or servlet.
 If a port conflict occurs, change the port that’s used by Tomcat.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 2
Objectives (continued)
Knowledge
 Describe two common errors that occur after you enter a URL into
a browser.
 In general terms, describe the directory structure of a Web
application that’s defined by the J2EE specfication.
 In general terms, describe the deployment descriptor of a web
application.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 3
How to install Tomcat
1. Go to the Tomcat web site: http://tomcat.apache.org/.
2. Navigate to the Download page for Tomcat 6.X.
3. Navigate to the Binary Distributions heading for the latest stable
release. To do that, avoid any headings labeled as alpha or beta
releases. Beneath the Core subheading, click on the link for the zip
file.
4. Save the zip file to your hard disk. By default, this file should be
named something like apache-tomcat-6.0.10.zip.
5. Use a zip program to extract the files from the zip file.
6. If necessary, move the apache-tomcat directory to your C drive.
7. Rename the apache-tomcat directory to tomcat.
8. Copy the JAR files shown below from Tomcat’s lib directory to the
JDK’s jre\lib\ext directory.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 4
The JAR files that need to be available to the JRE
servlet-api.jar
jsp-api.jar
el-api.jar
tomcat-dbcp.jar
Description
 The directory that holds the files for Tomcat is known as the
Tomcat home directory. By default, this directory is named
apache-tomcat-6.0.X, but you can rename it to tomcat.
 The Java Archive (JAR) files shown above contain the Java
classes that need to be available to the JDK and JRE when you
develop servlets and JSPs. By copying these JAR files from
Tomcat’s lib subdirectory to the JDK’s jre\lib\ext subdirectory,
you make the classes available to the JDK and JRE.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 5
The file structure of Tomcat
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 6
The subdirectories
Directory
bin
conf
lib
logs
temp
webapps
work
Description
Files for working with Tomcat such as the startup and
shutdown batch files.
Files for configuring Tomcat such as server.xml,
context.xml, and web.xml.
JAR files that contain classes that are available to all web
applications. As a result, you can put any JAR files you
want to make available to all web applications in this
directory.
Log files.
Temporary files used by the JVM.
The directories and files for the web applications.
The source code and class files for the servlets that Tomcat
generates for the JSPs.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 7
The files
File
RELEASE-NOTES
running.txt
Murach’s Java Servlets/JSP (2nd Ed.), C2
Description
General information about the current release
of Tomcat.
Instructions for installing, starting, and
stopping Tomcat.
© 2008, Mike Murach & Associates, Inc.
Slide 8
The catalina batch file opened for editing
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 9
How to set the JAVA_HOME environment variable
1. Use a text editor like NotePad to open the catalina.bat file located in
the c:\tomcat\bin directory. One way to do that is to right-click on
the name of the file in the Windows Explorer and choose Edit.
2. Scroll down past the remarks at the beginning of the file. These lines
begin with “rem”.
3. After the remarks at the beginning of the file, enter a set statement
that sets the JAVA_HOME variable to the directory that contains the
JDK that’s installed on your system. When you enter this statement,
put an equals sign (=) between the variable and the directory path.
4. Save your changes to the catalina.bat file.
5. If necessary, stop and restart Tomcat.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 10
DOS commands for starting Tomcat
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 11
The console that Tomcat displays when it’s
running
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 12
How to use the DOS Prompt window to start and
stop Tomcat
1. Open a DOS Prompt window and use the cd command to change the
current directory to Tomcat’s bin directory.
2. To start Tomcat, type “startup” and press the Enter key. To stop
Tomcat, type “shutdown” and press the Enter key.
How to solve the “out of environment space”
problem
 You may get an “out of environment space” error if you’re using
Windows 95, 98, or ME. To solve this problem, follow the
troubleshooting directions that are at the end of the running.txt file
that’s in Tomcat’s root directory.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 13
The default Tomcat home page
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 14
The components of an HTTP URL
HTTP URLs that you can use to test Tomcat
http://localhost:8080/
http://localhost:8080/examples/servlets/
http://localhost:8080/examples/jsp/
How to view a web page via an HTTP URL
1. Start Tomcat.
2. Start your web browser.
3. Type an HTTP URL into your web browser and press Enter.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 15
How to test Tomcat to make sure it’s running
 You can specify a Uniform Resource Locator (URL).
 When Tomcat is running on your local machine, you can use the
“localhost” keyword to specify the host machine.
 The default port for Tomcat is 8080. If another application is
already using this port, you can change the default port.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 16
The Internet Explorer’s error page
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 17
Tomcat’s default 404 error page
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 18
How to solve common Tomcat problems
 If the browser displays an error page that says “The page cannot be
displayed,” the HTTP request isn’t connecting with a web server.
To solve this problem, make sure that the Tomcat engine is
running, and make sure that you’ve entered a valid host name and
port number.
 If the browser displays a 404 error page, Tomcat is receiving the
HTTP request, but it can’t find the requested resource. To solve
this problem, make sure that you’ve entered the path and filename
of the URL correctly.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 19
The server.xml file
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 20
How to change the port that’s used by Tomcat
1. Use the Windows Explorer to navigate to Tomcat’s conf directory
and open the server.xml file in a text editor.
2. Replace all instances of the current port, which is 8080 by
default, to a four-digit number that’s greater than 1024 or to 80.
To do this, you may want to use the Find and Replace feature of
your text editor.
3. Save the changes to the server.xml file.
4. Stop and restart Tomcat.
Notes
 If you have a port conflict with another application, you can
change the 8080 default to a 4-digit number greater than 1024.
 If you don’t enter a port when you specify a URL, your browser
will use port 80. So if you change Tomcat’s default port to 80,
you don’t need to specify a port when entering a URL.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 21
The home page for the musicStore application
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 22
Two ways to manually deploy a web application
 With Tomcat running, copy the WAR file for the application into
Tomcat’s webapps directory. Then, Tomcat expands the WAR file
into the proper directory structure.
 Copy the files for the application into Tomcat’s webapps directory.
How to run a web application
 Start Tomcat and enter the URL for the application into your
browser.
The WAR file
 A Web Archive (WAR) file is a Java Archive (JAR) file that
contains all of the directories and files for a web application. When
you use an IDE to build a web application, the IDE usually creates
a WAR file for the application automatically.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 23
The directory structure for a web application
named musicStore
c:\tomcat
webapps
musicStore (the root directory for HTML and JSP files)
admin
cart
download
META-INF (the context.xml file)
WEB-INF (the web.xml file)
classes (the root directory for Java classes)
music
admin (the directory for the music.admin package)
business
cart
data
download
lib (JAR files for Java class libraries)
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 24
The directories and files for a web application
Directory
(root)
\WEB-INF
\WEB-INF\classes
Murach’s Java Servlets/JSP (2nd Ed.), C2
Description
This directory and its subdirectories typically
contain the HTML and JSP files for the
application.
This directory must contain a file named
web.xml. This file can be used to configure the
servlets and other components that make up the
application. In addition, this directory is not
directly accessible from the web.
This directory and its subdirectories contain the
servlets and other Java classes for your
application. Each subdirectory must correspond
with the package for the Java class.
© 2008, Mike Murach & Associates, Inc.
Slide 25
The directories and files for a web application
(continued)
Directory
\WEB-INF\lib
\META-INF
Murach’s Java Servlets/JSP (2nd Ed.), C2
Description
This directory contains any JAR files that
contain Java class libraries that are used by the
web application.
This directory contains the context.xml file. This
file can be used to configure the web application
context.
© 2008, Mike Murach & Associates, Inc.
Slide 26
The standard directories and files for a web
application
 The top-level directory for a web application is known as its root
directory.
 A Java web application is a hierarchy of directories and files in a
standard layout defined by the Java EE specification. All Java web
applications must use the root, \WEB-INF, and
\WEB-INF\classes directories.
 To make classes within a JAR file available to more than one web
application, you can put the JAR file in Tomcat’s lib directory.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 27
A web.xml file
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5">
<display-name>Murach's Servlets and JSP:
Music Store site</display-name>
<description>The Music Store web site that's described
in Murach's Java Servlets and JSP (second
edition)</description>
<!-- Enable servlet mapping -->
<servlet>
<servlet-name>AddToEmailListServlet</servlet-name>
<servlet-class>music.email.AddToEmailListServlet
</servlet-class>
</servlet>
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 28
A web.xml file (continued)
<!-- Map servlets to URL patterns -->
<servlet-mapping>
<servlet-name>AddToEmailListServlet</servlet-name>
<url-pattern>/email/addToEmailList</url-pattern>
</servlet-mapping>
<!-- Specify index pages -->
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
</welcome-file-list>
</web-app>
Description
 Every web application requires a web.xml file in the WEB-INF
directory. This file is known as the deployment descriptor for the
web application. The highlighted code is required in the file.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 29
What the web.xml file can do
 Enable servlet mapping so you can call a servlet using any URL or
URL pattern.
 Define initialization parameters for a servlet or the entire
application.
 Define error pages for an entire application.
 Provide security constraints to restrict access to certain web pages
and servlets.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 30
How to add a username and password for the
manager role
 Open the tomcat-users.xml file that’s in Tomcat’s conf directory
in a text editor.
 Add a role element that defines the manager role.
 Add a user element that provides a username and password for the
manager role.
 If Tomcat is running when you add users to the tomcat-users.xml
file, you need to restart Tomcat after you close the file so Tomcat
will recognize the changes.
The tomcat-users.xml file
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="manager"/>
<user username="admin" password="sesame" roles="manager"/>
</tomcat-users>
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 31
How to start Tomcat's Web Application Manager
 To start the Web Application Manager, start a web browser and go
to http://localhost:8080/manager/html.
 Tomcat will prompt you for a username and password. If you
supply a valid username and password for the manager role, you
will be able to view the Web Application Manager.
The Authentication Required dialog box
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 32
The index page for Tomcat’s Web Application
Manager
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 33
How to use Tomcat's Web Application Manager
 To reload all of the classes for an application, click on the Reload
link for the application.
 To stop an application, click on the Stop link for the application.
 To start an application, click on the Start link for the application.
 To undeploy an application, click on the Undeploy link for the
application. This deletes all files for the web application from
Tomcat’s server.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 34
The context.xml file
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 35
How to turn on servlet reloading
1. Use a text editor to open the context.xml file in Tomcat’s conf
directory.
2. Add the reloadable attribute to the Context element and set this
attribute to true like this:
<Context reloadable="true">
3. Save the changes to the context.xml file
4. If necessary, stop and restart Tomcat.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 36
Servlet reloading
 If servlet reloading isn’t on, which is the default setting, you have
to stop and restart Tomcat each time that you change one of the
classes that’s in memory.
 If you turn servlet reloading on, Tomcat checks the modification
dates of the classes in memory and automatically reloads the ones
that have changed. Although this is useful in development, it can
cause performance problems in a production environment.
 The context.xml file is an XML file that controls how the Tomcat
engine is configured. Tomcat reads this file every time it starts to
configure itself. You can use a text editor to edit this file. Then,
you can stop and restart Tomcat to put the changes into effect.
 This is a global setting that affects all web applications running on
this instance of Tomcat.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 37
The web.xml file
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 38
The element that defines the invoker 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 element that maps the invoker servlet
<!-- The mapping for the invoker servlet -->
<servlet-mapping>
<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
</servlet-mapping>
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 39
How to map the invoker servlet
1. Use a text editor to open the context.xml file in Tomcat’s conf
directory.
2. Add the privileged attribute to the Context element and set this
attribute to true like this:
<Context reloadable="true" privileged="true">
3. Save the changes to the context.xml file
4. Use a text editor to open the web.xml file in Tomcat’s conf
directory.
5. Remove the comments from the element that defines the invoker
servlet.
6. Scroll down and remove the comments from the element that
maps the invoker servlet.
Murach’s Java Servlets/JSP (2nd Ed.), C2
© 2008, Mike Murach & Associates, Inc.
Slide 40