Tomcat s Directory Structure

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.^[*]For the following request, Tomcat serves the index.html page from the ROOT directory:

^[*] The webapps/ROOT directory is distinct from the Tomcat root directory, which is the top-level directory of the Tomcat tree.

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.)