Application Developer's Guide (8.5.100) - Deployment (2024)

• Background
• Standard Directory Layout
• Shared Library Files
• Web Application Deployment Descriptor
• Tomcat Context Descriptor
• Deployment With Tomcat

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 littleconsistency between server platforms. However, servers that conformto the 2.2 (or later) specification are required to accept aWeb Application Archive in a standard format, which is discussedfurther below.

A web application is defined as a hierarchy of directories and filesin 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 formatis more useful during development, while the latter is used when youdistribute your application to be installed.

The top-level directory of your web application hierarchy is also thedocument root of your application. Here, you will place the HTMLfiles and JSP pages that comprise your application's user interface. When thesystem administrator deploys your application into a particular server, theyassign a context path to your application (a later sectionof this manual describes deployment on Tomcat). Thus, if thesystem administrator assigns your application to the context path/catalog, then a request URI referring to/catalog/index.html will retrieve the index.htmlfile from your document root.

To facilitate creation of a Web Application Archive file in the requiredformat, it is convenient to arrange the "executable" files of your webapplication (that is, the files that Tomcat actually uses when executingyour app) in the same organization as required by the WAR format itself.To do this, you will end up with the following contents in yourapplication's "document root" directory:

• *.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.
• /WEB-INF/web.xml - The Web Application Deployment Descriptor for your application. This is an XML file describing the servlets and other components that make up your application, along with any initialization parameters and container-managed security constraints that you want the server to enforce for you. This file is discussed in more detail in the following subsection.
• /WEB-INF/classes/ - This directory contains any Java class files (and associated resources) required for your application, including both servlet and non-servlet classes, that are not combined into JAR files. If your classes are organized into Java packages, you must reflect this in the directory hierarchy under /WEB-INF/classes/. For example, a Java class named com.mycompany.mypackage.MyServlet would need to be stored in a file named /WEB-INF/classes/com/mycompany/mypackage/MyServlet.class.
• /WEB-INF/lib/ - This directory contains JAR files that contain Java class files (and associated resources) required for your application, such as third party class libraries or JDBC drivers.

When you install an application into Tomcat (or any other 2.2 or laterServlet container), the classes in the WEB-INF/classes/directory, as well as all classes in JAR files found in theWEB-INF/lib/ directory, are made visible to other classeswithin your particular web application. Thus, ifyou include all of the required library classes in one of these places (besure to check licenses for redistribution rights for any third party librariesyou utilize), you will simplify the installation of your web application --no adjustment to the system class path (or installation of global libraryfiles in your server) will be necessary.

Much of this information was extracted from Chapter 9 of the ServletAPI Specification, version 2.3, which you should consult for more details.

Like most servlet containers, Tomcat also supports mechanisms to installlibrary JAR files (or unpacked classes) once, and make them visible to allinstalled web applications (without having to be included inside the webapplication itself). The details of how Tomcat locates and shares suchclasses are described in theClass Loader How-To documentation.The location commonly used within a Tomcat installation for shared code is$CATALINA_HOME/lib. JAR files placed here are visible both toweb applications and internal Tomcat code. This is a good place to put JDBCdrivers that are required for both your application or internal Tomcat use(such as for a DataSourceRealm).

Out of the box, a standard Tomcat installation includes a varietyof pre-installed shared library files, including:

• The Servlet 3.1 and JSP 2.3 APIs that are fundamental to writing servlets and JavaServer Pages.

As mentioned above, the /WEB-INF/web.xml file contains theWeb Application Deployment Descriptor for your application. As the filenameextension implies, this file is an XML document, and defines everything aboutyour application that a server needs to know (except the context path,which is assigned by the system administrator when the application isdeployed).

The complete syntax and semantics for the deployment descriptor is definedin Chapter 13 of the Servlet API Specification, version 2.3. Over time, itis expected that development tools will be provided that create and edit thedeployment descriptor for you. In the meantime, to provide a starting point,a basic web.xml fileis provided. This file includes comments that describe the purpose of eachincluded element.

NOTE - The Servlet Specification includes a DocumentType Descriptor (DTD) for the web application deployment descriptor, andTomcat enforces the rules defined here when processing your application's/WEB-INF/web.xml file. In particular, you mustenter your descriptor elements (such as <filter>,<servlet>, and <servlet-mapping> inthe order defined by the DTD (see Section 13.3).

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

In order to be executed, a web application must be deployed ona 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 the followingapproaches:

• 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.
• Copy the web application archive file into directory $CATALINA_BASE/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.
• Use the Tomcat "Manager" web application to deploy and undeploy web applications. Tomcat includes a web application, deployed by default on context path /manager, that allows you to deploy and undeploy applications on a running Tomcat server without restarting it. See Manager App How-To for more information on using the Manager web application.
• Use "Manager" Ant Tasks In Your Build Script. Tomcat includes a set of custom task definitions for the Ant build tool that allow you to automate the execution of commands to the "Manager" web application. These tasks are used in the Tomcat deployer.
• Use the Tomcat Deployer. Tomcat includes a packaged tool bundling the Ant tasks, and can be used to automatically precompile JSPs which are part of the web application before deployment to the server.

Deploying your app on other servlet containers will be specific to eachcontainer, but all containers compatible with the Servlet API Specification(version 2.2 or later) are required to accept a web application archive file.Note that other containers are NOT required to accept anunpacked directory structure (as Tomcat does), or to provide mechanisms forshared library files, but these features are commonly available.