Deployment

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 (or later) 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 (a later section of this manual describes deployment on Tomcat). 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 index.html file from your document root.

*.html, *.jsp, etc. - The HTML and JSP pages, along with other files that must be visible to the client browser (such as JavaScript, stylesheet files, and images) for your application. In larger applications you may choose to divide these files into a subdirectory hierarchy, but for smaller apps, it is generally much simpler to maintain only a single directory for these files.

The Servlet 3.0 and JSP 2.2 APIs that are fundamental to writing servlets and JavaServer Pages.

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

The complete syntax and semantics for the deployment descriptor is defined in Chapter 13 of the Servlet API Specification, version 2.3. 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.

NOTE - The Servlet Specification includes a Document Type Descriptor (DTD) for the web application deployment descriptor, and Tomcat enforces the rules defined here when processing your application's /WEB-INF/web.xml file. In particular, you must enter your descriptor elements (such as , , and in the order defined by the DTD (see Section 13.3).

A /META-INF/context.xml file can be used to define Tomcat specific configuration options, such as an access log, data sources, session manager configuration and more. This XML file must contain one Context element, which will be considered as if it was the child of the Host element corresponding to the Host to which the web application is being deployed. The Tomcat configuration documentation contains information on the Context element.

Copy unpacked directory hierarchy into a subdirectory in directory $CATALINA_BASE/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.xml file that we construct, because it is the quickest and easiest approach during development. Be sure to restart Tomcat after installing or updating your application.