MySQL Cookbook (2007)

Appendix C. JSP and Tomcat Primer

This appendix describes some essential concepts of JavaServer Pages (JSP) programming, which is used earlier in this book beginning with Chapter 17. The necessary background is fairly extensive, which is why the material is presented here in a separate appendix rather than breaking up the flow of that chapter. The topics discussed here are:

§ A brief overview of servlet and JSP technologies

§ Setting up the Tomcat server

§ Tomcat’s directory structure

§ The layout of web applications

§ Elements of JSP pages

For pointers to additional information about JSP pages, servlets, or Tomcat, see Appendix D.

Servlet and JavaServer Pages Overview

Java servlet technology is a means by which to execute Java programs efficiently in a web environment. The Java Servlet Specification defines the conventions of this environment, which may be summarized briefly as follows:

§ Servlets run inside a servlet container, which itself either runs inside a web server or communicates with one. Servlet containers are also known as servlet engines.

§ The servlet container receives requests from the web server and executes the appropriate servlet to process the request. The container then receives the response from the servlet and gives it to the web server, which in turn returns it to the client. A servlet container thus provides the connection between servlets and the web server under which they run. The container acts as the servlet runtime environment, with responsibilities that include determining the mapping between client requests and the servlets that handle them, as well as loading, executing, and unloading servlets as necessary.

§ Servlets communicate with their container according to established conventions. Each servlet is expected to implement methods with well-known names to be called in response to various kinds of requests. For example, GET and POST requests are routed to methods named doGet() anddoPost().

§ Servlets that can be run by a container are arranged into logical groupings called “contexts.” (Contexts might correspond, for example, to subdirectories of the document tree that is managed by the container.) Contexts also can include resources other than servlets, such as HTML pages, images, or configuration files.

§ A context provides the basis for a “web application,” which the Java Servlet Specification defines as follows:

A Web application is a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a Web server.

In other words, an application is a group of related servlets that work together, without interference from other unrelated servlets. Servlets within a given application context can share information with each other, but servlets in different contexts cannot. For example, a gateway or login servlet might establish a user’s credentials, which then are placed into the context environment to be shared with other servlets within the same context as proof that the user has logged in properly. Should those servlets find the proper credentials not to be present in the environment when they execute, they can redirect to the gateway servlet automatically to require the user to log in. Servlets in another context cannot gain access to these credentials. Contexts thus provide a measure of security by preventing one application from invading another. They also can insulate applications from the effects of another application crashing; the container can keep the noncrashed applications running while it restarts the one that failed.

§ Sharing of information between servlets may take place at several scope levels, which enables them to work together within the scope of a single request or across multiple requests.

The following listing shows what a simple servlet looks like. It’s a Java program that implements a SimpleServlet class. The class has a doGet() method to be invoked by the servlet container when it receives a get request for the servlet. It also has a doPost() method to handle the possibility that a post request may be received instead; it’s simply a wrapper that invokes doGet(). SimpleServlet produces a short HTML page that includes some static text that is the same each time the servlet runs, and two dynamic elements (the current date and client IP address) that vary over time and for each client:

import java.io.*;

import java.util.*;

import javax.servlet.*;

import javax.servlet.http.*;

public class SimpleServlet extends HttpServlet

{

public void doGet (HttpServletRequest request,

HttpServletResponse response)

throws IOException, ServletException

{

PrintWriter out = response.getWriter ();

response.setContentType ("text/html");

out.println ("<html>");

out.println ("<head>");

out.println ("<title>Simple Servlet</title>");

out.println ("</head>");

out.println ("<body bgcolor=\"white\">");

out.println ("<p>Hello.</p>");

out.println ("<p>The current date is "

+ new Date ()

+ ".</p>");

out.println ("<p>Your IP address is "

+ request.getRemoteAddr ()

+ ".</p>");

out.println ("</body>");

out.println ("</html>");

}

public void doPost (HttpServletRequest request,

HttpServletResponse response)

throws IOException, ServletException

{

doGet (request, response);

}

}

As you will no doubt observe, this “simple” servlet really isn’t so simple! It requires a fair amount of machinery to import the requisite classes and to establish the doGet() and doPost() methods that provide the standard interface to the servlet container. Compare the servlet to the following PHP script, which does the same thing in a much more concise fashion:

<html>

<head>

<title>Simple PHP Page</title>

</head>

<body bgcolor="white">

<p>Hello.</p>

<p>The current date is <?php print (date ("D M d H:i:s T Y")); ?>.</p>

<p>Your IP address is <?php print ($_SERVER["REMOTE_ADDR"]); ?>.</p>

</body>

</html>

The contrast between the Java servlet and the PHP script illustrates one of the problems with writing servlets—the amount of repetitious overhead:

§ A certain minimal set of classes must be imported into each servlet.

§ The framework for setting up the servlet class and the doGet() or doPost() methods is fairly stereotypical, often varying among servlets only in the servlet class name.

§ Each fragment of HTML is produced with an output statement.

The first two points can be addressed by using a prototype file that you copy when beginning a new servlet. The third point (wrapping each line of HTML within a print statement) is not so easily addressed and is possibly the single most tedious aspect of servlet writing. It also leads to another issue: A servlet’s code may be easy enough to read as Java, but it’s sometimes difficult to discern the structure of the HTML that the code generates. The problem is that you’re really trying to write in two languages at once (that is, you’re writing Java that writes HTML), which isn’t really optimal for either language.

JSP Pages: An Alternative to Servlets

One of the reasons for the invention of JavaServer Pages was to relieve the burden involved in creating web pages with a lot of print statements. JSP uses a notational approach that is similar to PHP: Write the HTML literally and embed the code to be executed within special markers. The following listing shows a JSP page that is equivalent to the SimpleServlet servlet, but looks much more like the corresponding PHP script:

<html>

<head>

<title>Simple JSP Page</title>

</head>

<body bgcolor="white">

<p>Hello.</p>

<p>The current date is <%= new java.util.Date () %>.</p>

<p>Your IP address is <%= request.getRemoteAddr () %>.</p>

</body>

</html>

The JSP page is more concise than the servlet in several ways:

§ The standard set of classes required to run a servlet need not be imported. This is done automatically.

§ The HTML is written more naturally, without using print statements.

§ No class definition is required, nor any doGet() or doPost() methods.

§ The response and out objects need not be declared, because they’re set up for you and ready to use as implicit objects. In fact, the JSP page just shown doesn’t refer to out explicitly at all, because its output-producing constructs write to out automatically.

§ The default content type is text/html; there’s no need to specify it explicitly.

§ The script includes literal Java by placing it within special markers. The page just shown uses <%= and %>, which mean “evaluate the expression and display its result.” There are other markers as well, each of which has a specific purpose. (For a brief summary, see “Elements of JSP Pages” later in this appendix.)

When a servlet container receives a request for a JSP page, it treats the page as a template containing literal text plus executable code embedded within special markers. The container produces an output page from the template to send to the client. Literal text from the template is left unmodified, the executable code is replaced by any output that it generates, and the combined result is returned to the client as the response to the request. That’s the conceptual view of JSP processing, at least. When a container processes a JSP request, this is what really happens:

1. The container translates the JSP page into a servlet—that is, into an equivalent Java program. Instances of template text are converted to print statements that output the text literally. Instances of code are placed into the program so that they execute with the intended effect. This is all placed within a wrapper that provides a unique class name and that includes import statements to pull in the standard set of classes necessary for the servlet to run properly in a web environment.

2. The container compiles the servlet to produce an executable class file.

3. The container executes the class file to generate an output page, which is returned to the client as the response to the request.

4. The container also caches the executable class so that when the next request for the JSP page arrives, the container can execute the class directly and skip the translation and compilation phases. If the container notices that a JSP page has been modified the next time it is requested, it discards the cached class and recompiles the modified page into a new executable class.

Notationally, JSP pages provide a more natural way to write web pages than do servlets. Operationally, the JSP engine provides the benefits of automatic compilation after the page is installed in the document tree or modified thereafter. When you write a servlet, any changes require recompiling the servlet, unloading the old one, and loading the new one. That can lead to an emphasis on messing with the servlet itself rather than a focus on the servlet’s purpose. JSP reverses the emphasis so that you think more about what the page does than about the mechanics of getting it compiled and loaded properly.

The differences between servlets and JSP pages do not imply any necessity of choosing to use only one or the other. Application contexts in a servlet container can include both, and because JSP pages are converted into servlets anyway, they can all intercommunicate.

JSP is similar enough to certain other technologies that it can provide a migration path away from them. For example, the JSP approach is much like that used in Microsoft’s Active Server Pages (ASP). However, JSP is vendor- and platform-neutral, whereas ASP is proprietary. JSP thus provides an attractive alternative technology for anyone looking to move away from ASP.

Custom Actions and Tag Libraries

A servlet looks a lot like a Java program, because that’s what it is. The JSP approach encourages a cleaner separation of HTML (presentation) and code, because you need not generate HTML from within Java print statements. On the other hand, JSP doesn’t require separation of HTML and code, so it’s still possible to end up with lots of embedded Java in a page if you’re not careful.

One way to avoid inclusion of literal Java in JSP pages is to use another JSP feature known as custom actions. These take the form of special tags that look a lot like HTML tags (because they are written as XML elements). Custom actions enable tags to be defined that perform tasks on behalf of the page in which they occur. For example, a <sql:query> tag might communicate with a database server to issue a query. Custom actions typically come in groups, which are known as tag libraries and are designed as follows:

§ The actions performed by the tags are implemented by a set of classes. These are just regular Java classes, except that they are written according to a set of interface conventions that enable the servlet container to communicate with them in a standard way. (The conventions define how tag attributes and body content are passed to tag handler classes, for example.) Typically, the set of classes is packaged into a JAR file.

§ The library includes a tag library descriptor (TLD) file that specifies how each tag maps onto the corresponding class. This enables the JSP processor to determine which class to invoke for each custom tag that appears in a JSP page. The TLD file also indicates how each tag behaves, such as whether it has any required attributes. This information is used at page translation time to determine whether a JSP page uses the tags in the library correctly. For example, if a tag requires a particular attribute and the tag is used in a page without it, the JSP processor can detect that problem and issue an appropriate error message.

Tag libraries make it easier to write entire pages using tag notation rather than switching between tags and Java code. The notation is JSP-like, not Java-like, but the effect of placing a custom tag in a JSP page is like making a method call. This is because a tag reference in a JSP page maps onto a method invocation in the servlet that the page is translated into.

To illustrate the difference between the embedded-Java and tag library approaches, compare two JSP scripts that set up a connection to a MySQL server and display a list of tables in the cookbook database. The first one does so using Java embedded within the page:

<%@ page import="java.sql.*" %>

<html>

<head>

<title>Tables in cookbook Database</title>

</head>

<body bgcolor="white">

<p>Tables in cookbook database:</p>

<%

Connection conn = null;

String url = "jdbc:mysql://localhost/cookbook";

String user = "cbuser";

String password = "cbpass";

Class.forName ("com.mysql.jdbc.Driver").newInstance ();

conn = DriverManager.getConnection (url, user, password);

Statement s = conn.createStatement ();

s.executeQuery ("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES"

+ " WHERE TABLE_SCHEMA = 'cookbook'"

+ " ORDER BY TABLE_NAME");

ResultSet rs = s.getResultSet ();

while (rs.next ())

out.println (rs.getString (1) + "<br />");

rs.close ();

s.close ();

conn.close ();

%>

</body>

</html>

The same thing can be done by using a tag library, such as the JSP Standard Tag Library (JSTL). JSTL consists of several tag sets grouped by function. Using its core and database tags, the preceding JSP page can be converted as follows to avoid entirely the use of literal Java:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>

<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %>

<html>

<head>

<title>Tables in cookbook Database</title>

</head>

<body bgcolor="white">

<p>Tables in cookbook database:</p>

<sql:setDataSource

var="conn"

driver="com.mysql.jdbc.Driver"

url="jdbc:mysql://localhost/cookbook"

user="cbuser"

password="cbpass"

/>

<sql:query dataSource="${conn}" var="rs">

SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES

WHERE TABLE_SCHEMA = 'cookbook'

ORDER BY TABLE_NAME

</sql:query>

<c:forEach items="${rs.rowsByIndex}" var="row">

<c:out value="${row[0]}"/><br />

</c:forEach>

</body>

</html>

The taglib directives identify the TLD files that the page uses and indicate that actions from the corresponding tag sets will be identified by prefixes of c and sql. (In effect, a prefix sets up a namespace for a set of tags.) The <sql:dataSource> tag sets up the parameters for connecting to the MySQL server, <sql:query> issues a query, <c:forEach> loops through the result, and <c:out> adds each table name in the result to the output page. (I’m glossing over details, of course. For more information about the JSTL tags, see Using Tomcat to Run Web Scripts.)

If it’s likely that you’d connect to the database server the same way from most JSP pages in your application context, a further simplification can be achieved by moving the <sql:dataSource> tag to an include file. If you name the file jstl-mcb-setup.inc and place it in the application’sWEB-INF directory, any page within the application context can set up the connection to the MySQL server by accessing the file with an include directive. (By convention, application contexts use their WEB-INF directory for private context-specific information. See the section “Web Application Structure.”) Modifying the preceding page to use the include file results in a script that looks like this:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>

<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %>

<%@ include file="/WEB-INF/jstl-mcb-setup.inc" %>

<html>

<head>

<title>Tables in cookbook Database</title>

</head>

<body bgcolor="white">

<p>Tables in cookbook database:</p>

<sql:query dataSource="${conn}" var="rs">

SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES

WHERE TABLE_SCHEMA = 'cookbook'

ORDER BY TABLE_NAME

</sql:query>

<c:forEach items="${rs.rowsByIndex}" var="row">

<c:out value="${row[0]}"/><br />

</c:forEach>

</body>

</html>

You’re still using Java when you use a tag library, because tag actions map onto Java class invocations. But the notation follows XML conventions, so it’s less like writing program code and more like writing HTML page elements. If your organization produces web content using a“separation of powers” workflow, custom actions enable elements of the page that are produced dynamically to be packaged in a way that is easier for designers and other non-programmers to deal with. They don’t have to develop or work directly with the classes that implement tag actions; that’s left to the programmers who write the classes that correspond to the tags.

Setting Up a Tomcat Server

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:

A Java Software Development Kit (SDK)

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 itself

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.

Some knowledge of XML

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.

Installing a Tomcat Distribution

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:

.tar.gz

A compressed tar file, usually used for Unix installs

.zip

A ZIP archive, applicable to either Unix or Windows

.exe

An executable installer, used on Windows only

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.

Starting and Stopping 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 havePATH 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.)

Tomcat’s Directory Structure

For writing JSP pages, it’s not strictly necessary to be familiar with the hierarchy of Tomcat’s directory layout. But it certainly doesn’t hurt, so change location into the Tomcat root directory and have a look around. You’ll find a number of standard directories, which are described in the following discussion, grouped by function. Note that your installation layout may not be exactly as described here. Some distribution formats omit a few of the directories, and the logs and work directories might not be created until you’ve started Tomcat for the first time.

Application Directories

From the point of view of an application developer, the webapps directory is the most important part of Tomcat’s directory hierarchy. Each application context has its own directory, which is placed within the webapps directory under the Tomcat root.

Tomcat processes client requests by mapping them onto locations under the webapps directory. For a request that begins with the name of a directory located under webapps, Tomcat looks for the appropriate page within that directory. For example, Tomcat serves the following two requests using the index.html and test.jsp pages in the mcb directory:

http://localhost:8080/mcb/index.html

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

For requests that don’t begin with the name of a webapps subdirectory, Tomcat serves them from a special subdirectory named ROOT, which provides the default application context.^[23^]For the following request, Tomcat serves the index.html page from the ROOT directory:

http://localhost:8080/index.html

Applications typically are packaged as web archive (WAR) files and Tomcat by default looks for WAR files that need to be unpacked when it starts up. Thus, to install an application, you generally copy its WAR file to the webapps directory, restart Tomcat, and let Tomcat unpack it. The layout of individual application directories is described later in the section “Web Application Structure.”

A web application is a group of related servlets that work together, without interference from other unrelated servlets. Essentially what this means for Tomcat is that an application is everything under a subdirectory of the webapps directory. Because contexts are kept separate by servlet containers like Tomcat, one practical implication of this structure is that scripts in one application directory can’t mess with anything in another application directory.

Configuration and Control Directories

Two directories contain configuration and control files. The bin directory contains control scripts for Tomcat startup and shutdown, and conf contains Tomcat’s configuration files, which are written as XML documents. Tomcat reads its configuration files only at startup time. If you modify any of them, you must restart Tomcat for your changes to take effect.

The most important configuration file is server.xml, which controls Tomcat’s overall behavior. Another file, web.xml, provides application configuration defaults. This file is used in conjunction with any web.xml file an application may have of its own. The tomcat-users.xml file defines credentials for users that have access to protected server functions, such as the Manager application that enables you to control applications from your browser. (See “Restarting Applications Without Restarting Tomcat,” later) This file can be superseded by other user information storage mechanisms. For example, you can store Tomcat user records in MySQL instead. For instructions, look in the tomcat directory of the recipes distribution.

Class Directories

Several Tomcat directories are used for class files and libraries. They differ in function according to whether you want to make classes visible to applications, to Tomcat, or to both:

shared

This directory has two subdirectories, classes and lib, for class files and libraries that are visible to applications but not to Tomcat.

common

This directory has two subdirectories, classes and lib, for class files and libraries that should be visible both to applications and to Tomcat.

server

This directory has two subdirectories, classes and lib, for class files and libraries that are visible to Tomcat but not to applications.

Operational Directories

If they weren’t set up as part of the Tomcat installation process, Tomcat creates two additional directories that serve operational purposes when you start it for the first time. Tomcat writes log files to the log directory and uses a work directory for temporary files.

The files in the logs directory can be useful for diagnosing problems. For example, if Tomcat has a problem starting properly, the reason usually will have been written into one of the logfiles.

When Tomcat translates a JSP page into a servlet and compiles it into an executable class file, it stores the resulting .java and .class files under the work directory. (When you first begin working with JSP pages, you may find it instructive to have a look under the work directory to compare your original JSP pages with the corresponding servlets that Tomcat produces.)