|Background Layout Descriptor Integration|
Before describing how to organize your source code directories, it is useful to examine the runtime organization of a web application. Prior to the Servlet API Specification, version 2.2, there was little consistency between server platforms. However, servers that conform to the 2.2 specification are required to accept a Web Application Archive in a standard format, which is discussed further below.
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, or in a "packed" form known as a Web ARchive, or WAR file. The former format is more useful during development, while the latter is used when you distribute your application to be installed.
The top-level directory of your web application hierarchy is also the
document root of your application. Here, you will place the HTML files
and JSP pages that comprise your application's user interface. When the
system administrator deploys your application into a particular server, he
or she assigns a context path to your application. Thus, if the
system administrator assigns your application to the context path
/catalog, then a request URI referring to
/catalog/index.html will retrieve the
file from your document root.
To facilitate creation of a Web Application Archive file in the required format, it is convenient to arrange the "executable" version of your web application (that is, the files that Tomcat actually uses when executing your app) in the same organization as required by the WAR format itself. To do this, you will end up with the following contents in your application's "document root" directory:
WEB-INF/classes/. For example, a Java class named
com.mycompany.mypackage.MyServletwould need to be stored in a file named
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
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.
As mentioned above, the
WEB-INF/web.xml file contains the
Web Application Deployment Descriptor for your application. As the filename
extension implies, this file is an XML document, and defines everything about
your application that a server needs to know (except the context path,
which is assigned by the system administrator when the application is
The complete syntax and semantics for the deployment descriptor is defined in Chapter 13 of the Servlet API Specification, version 2.2. Over time, it is expected that development tools will be provided that create and edit the deployment descriptor for you. In the meantime, to provide a starting point, a basic web.xml file is provided. This file includes comments that describe the purpose of each included element.
In order to be executed, a web application must be integrated with, or installed in, a servlet container. This is true even during development. We will describe using Tomcat to provide the execution environment. A web application can be deployed in Tomcat by one of three different approaches:
$TOMCAT_HOME/webapps/. Tomcat will assign a context path to your application based on the subdirectory name you choose. We will use this technique in the
build.xmlfile that we construct, because it is the quickest and easiest approach during development.
$TOMCAT_HOME/webapps/. When Tomcat is started, it will automatically expand the web application archive file into its unpacked form, and execute the application that way. This approach would typically be used to install an additional application, provided by a third party vendor or by your internal development staff, into an existing Tomcat installation. NOTE - If you use this approach, and wish to update your application later, you must both replace the web application archive file AND delete the expanded directory that Tomcat created, and then restart Tomcat, in order to reflect your changes. (For Tomcat 3.3, this assumes the default installation where auto-redeployment of WAR files is turned off.)
<Context>entry in the Tomcat
apps.xmlconfiguration file. This approach is described briefly below, and allows you to position the document root of your web application at some point other than the
$TOMCAT_HOME/webapps/directory. Doing this requires the following steps (for Tomcat 3.3):
Adding a new
<Context> entry in Tomcat's
apps.xml file involves the following steps (for Tomcat 3.3):
$TOMCAT_HOME/conf/apps.xmldoesn't exist, create one with the following initial content:
<?xml version="1.0" encoding="ISO-8859-1"?> <webapps> </webapps>
$TOMCAT_HOME/conf/apps.xmlin an editor.
<Context>element for your application, using the existing examples in other
apps-*.xmlfiles as a guide. The following attributes are supported:
Integrating your app with other servlet containers will be specific to each container, but all containers compatible with the Servlet API Specification (version 2.2) are required to accept a web application archive file.