| 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Application Developer's Guide - Deployment</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt=" |
|---|
| 2 | The Apache Tomcat Servlet/JSP Container |
|---|
| 3 | " align="right" src="../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Contents</strong></p><ul><li><a href="index.html">Contents</a></li><li><a href="introduction.html">Introduction</a></li><li><a href="installation.html">Installation</a></li><li><a href="deployment.html">Deployment</a></li><li><a href="source.html">Source Code</a></li><li><a href="processes.html">Processes</a></li><li><a href="sample/">Example App</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Application Developer's Guide</h1><h2>Deployment</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/deployment.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version |
|---|
| 4 | </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Background"><strong>Background</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 5 | |
|---|
| 6 | <p>Before describing how to organize your source code directories, |
|---|
| 7 | it is useful to examine the runtime organization of a web application. |
|---|
| 8 | Prior to the Servlet API Specification, version 2.2, there was little |
|---|
| 9 | consistency between server platforms. However, servers that conform |
|---|
| 10 | to the 2.2 (or later) specification are required to accept a |
|---|
| 11 | <em>Web Application Archive</em> in a standard format, which is discussed |
|---|
| 12 | further below.</p> |
|---|
| 13 | |
|---|
| 14 | <p>A web application is defined as a hierarchy of directories and files |
|---|
| 15 | in a standard layout. Such a hierarchy can be accessed in its "unpacked" |
|---|
| 16 | form, where each directory and file exists in the filesystem separately, |
|---|
| 17 | or in a "packed" form known as a Web ARchive, or WAR file. The former format |
|---|
| 18 | is more useful during development, while the latter is used when you |
|---|
| 19 | distribute your application to be installed.</p> |
|---|
| 20 | |
|---|
| 21 | <p>The top-level directory of your web application hierarchy is also the |
|---|
| 22 | <em>document root</em> of your application. Here, you will place the HTML |
|---|
| 23 | files and JSP pages that comprise your application's user interface. When the |
|---|
| 24 | system administrator deploys your application into a particular server, he |
|---|
| 25 | or she assigns a <em>context path</em> to your application (a later section |
|---|
| 26 | of this manual describes deployment on Tomcat). Thus, if the |
|---|
| 27 | system administrator assigns your application to the context path |
|---|
| 28 | <code>/catalog</code>, then a request URI referring to |
|---|
| 29 | <code>/catalog/index.html</code> will retrieve the <code>index.html</code> |
|---|
| 30 | file from your document root.</p> |
|---|
| 31 | |
|---|
| 32 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Directory Layout"><strong>Standard Directory Layout</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 33 | |
|---|
| 34 | <p>To facilitate creation of a Web Application Archive file in the required |
|---|
| 35 | format, it is convenient to arrange the "executable" files of your web |
|---|
| 36 | application (that is, the files that Tomcat actually uses when executing |
|---|
| 37 | your app) in the same organization as required by the WAR format itself. |
|---|
| 38 | To do this, you will end up with the following contents in your |
|---|
| 39 | application's "document root" directory:</p> |
|---|
| 40 | <ul> |
|---|
| 41 | <li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along |
|---|
| 42 | with other files that must be visible to the client browser (such as |
|---|
| 43 | JavaScript, stylesheet files, and images) for your application. |
|---|
| 44 | In larger applications you may choose to divide these files into |
|---|
| 45 | a subdirectory hierarchy, but for smaller apps, it is generally |
|---|
| 46 | much simpler to maintain only a single directory for these files. |
|---|
| 47 | <br><br></li> |
|---|
| 48 | <li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment |
|---|
| 49 | Descriptor</em> for your application. This is an XML file describing |
|---|
| 50 | the servlets and other components that make up your application, |
|---|
| 51 | along with any initialization parameters and container-managed |
|---|
| 52 | security constraints that you want the server to enforce for you. |
|---|
| 53 | This file is discussed in more detail in the following subsection. |
|---|
| 54 | <br><br></li> |
|---|
| 55 | <li><strong>/WEB-INF/classes/</strong> - This directory contains any Java |
|---|
| 56 | class files (and associated resources) required for your application, |
|---|
| 57 | including both servlet and non-servlet classes, that are not combined |
|---|
| 58 | into JAR files. If your classes are organized into Java packages, |
|---|
| 59 | you must reflect this in the directory hierarchy under |
|---|
| 60 | <code>/WEB-INF/classes/</code>. For example, a Java class named |
|---|
| 61 | <code>com.mycompany.mypackage.MyServlet</code> |
|---|
| 62 | would need to be stored in a file named |
|---|
| 63 | <code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>. |
|---|
| 64 | <br><br></li> |
|---|
| 65 | <li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that |
|---|
| 66 | contain Java class files (and associated resources) required for your |
|---|
| 67 | application, such as third party class libraries or JDBC drivers.</li> |
|---|
| 68 | </ul> |
|---|
| 69 | |
|---|
| 70 | <p>When you install an application into Tomcat (or any other |
|---|
| 71 | 2.2/2.3-compatible server), the classes in the <code>WEB-INF/classes/</code> |
|---|
| 72 | directory, as well as all classes in JAR files found in the |
|---|
| 73 | <code>WEB-INF/lib/</code> directory, are made visible to other classes |
|---|
| 74 | within your particular web application. Thus, if |
|---|
| 75 | you include all of the required library classes in one of these places (be |
|---|
| 76 | sure to check licenses for redistribution rights for any third party libraries |
|---|
| 77 | you utilize), you will simplify the installation of your web application -- |
|---|
| 78 | no adjustment to the system class path (or installation of global library |
|---|
| 79 | files in your server) will be necessary.</p> |
|---|
| 80 | |
|---|
| 81 | <p>Much of this information was extracted from Chapter 9 of the Servlet |
|---|
| 82 | API Specification, version 2.3, which you should consult for more details.</p> |
|---|
| 83 | |
|---|
| 84 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Shared Library Files"><strong>Shared Library Files</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 85 | |
|---|
| 86 | <p>Like most servlet containers, Tomcat 6 also supports mechanisms to install |
|---|
| 87 | library JAR files (or unpacked classes) once, and make them visible to all |
|---|
| 88 | installed web applications (without having to be included inside the web |
|---|
| 89 | application itself. The details of how Tomcat locates and shares such |
|---|
| 90 | classes are described in the |
|---|
| 91 | <a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation. |
|---|
| 92 | The location commonly used within a Tomcat 6 installation for shared code is |
|---|
| 93 | <strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to |
|---|
| 94 | web applications and internal Tomcat code. This is a good place to put JDBC |
|---|
| 95 | drivers that are required for both your application or internal Tomcat use |
|---|
| 96 | (such as for a JDBCRealm).</p> |
|---|
| 97 | |
|---|
| 98 | <p>Out of the box, a standard Tomcat 6 installation includes a variety |
|---|
| 99 | of pre-installed shared library files, including:</p> |
|---|
| 100 | <ul> |
|---|
| 101 | <li>The <em>Servlet 2.5</em> and <em>JSP 2.1</em> APIs that are fundamental |
|---|
| 102 | to writing servlets and JavaServer Pages.<br><br></li> |
|---|
| 103 | <li>An <em>XML Parser</em> compliant with the JAXP (version 1.2) APIs, so |
|---|
| 104 | your application can perform DOM-based or SAX-based processing of |
|---|
| 105 | XML documents.<br><br></li> |
|---|
| 106 | </ul> |
|---|
| 107 | |
|---|
| 108 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Web Application Deployment Descriptor"><strong>Web Application Deployment Descriptor</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 109 | |
|---|
| 110 | <p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the |
|---|
| 111 | Web Application Deployment Descriptor for your application. As the filename |
|---|
| 112 | extension implies, this file is an XML document, and defines everything about |
|---|
| 113 | your application that a server needs to know (except the <em>context path</em>, |
|---|
| 114 | which is assigned by the system administrator when the application is |
|---|
| 115 | deployed).</p> |
|---|
| 116 | |
|---|
| 117 | <p>The complete syntax and semantics for the deployment descriptor is defined |
|---|
| 118 | in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it |
|---|
| 119 | is expected that development tools will be provided that create and edit the |
|---|
| 120 | deployment descriptor for you. In the meantime, to provide a starting point, |
|---|
| 121 | a <a href="web.xml.txt">basic web.xml file</a> |
|---|
| 122 | is provided. This file includes comments that describe the purpose of each |
|---|
| 123 | included element.</p> |
|---|
| 124 | |
|---|
| 125 | <p><strong>NOTE</strong> - The Servlet Specification includes a Document |
|---|
| 126 | Type Descriptor (DTD) for the web application deployment descriptor, and |
|---|
| 127 | Tomcat 6 enforces the rules defined here when processing your application's |
|---|
| 128 | <code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong> |
|---|
| 129 | enter your descriptor elements (such as <code><filter></code>, |
|---|
| 130 | <code><servlet></code>, and <code><servlet-mapping></code> in |
|---|
| 131 | the order defined by the DTD (see Section 13.3).</p> |
|---|
| 132 | |
|---|
| 133 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Tomcat Context Descriptor"><strong>Tomcat Context Descriptor</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 134 | |
|---|
| 135 | <p>A /META-INF/context.xml file can be used to define Tomcat specific |
|---|
| 136 | configuration options, such as loggers, data sources, session manager |
|---|
| 137 | configuration and more. This XML file must contain one Context element, which |
|---|
| 138 | will be considered as if it was the child of the Host element corresponding |
|---|
| 139 | to the Host to which the The Tomcat configuration documentation contains |
|---|
| 140 | information on the Context element.</p> |
|---|
| 141 | |
|---|
| 142 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deployment With Tomcat 6"><strong>Deployment With Tomcat 6</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 143 | |
|---|
| 144 | <blockquote><em> |
|---|
| 145 | <p>The description below uses the variable name $CATALINA_BASE to refer the |
|---|
| 146 | base directory against which most relative paths are resolved. If you have |
|---|
| 147 | not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE |
|---|
| 148 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
|---|
| 149 | the directory into which you have installed Tomcat 6.</p> |
|---|
| 150 | </em></blockquote> |
|---|
| 151 | |
|---|
| 152 | <p>In order to be executed, a web application must be deployed on |
|---|
| 153 | a servlet container. This is true even during development. |
|---|
| 154 | We will describe using Tomcat 6 to provide the execution environment. |
|---|
| 155 | A web application can be deployed in Tomcat by one of the following |
|---|
| 156 | approaches:</p> |
|---|
| 157 | <ul> |
|---|
| 158 | <li><em>Copy unpacked directory hierarchy into a subdirectory in directory |
|---|
| 159 | <code>$CATALINA_BASE/webapps/</code></em>. Tomcat will assign a |
|---|
| 160 | context path to your application based on the subdirectory name you |
|---|
| 161 | choose. We will use this technique in the <code>build.xml</code> |
|---|
| 162 | file that we construct, because it is the quickest and easiest approach |
|---|
| 163 | during development. Be sure to restart Tomcat after installing or |
|---|
| 164 | updating your application. |
|---|
| 165 | <br><br></li> |
|---|
| 166 | <li><em>Copy the web application archive file into directory |
|---|
| 167 | <code>$CATALINA_BASE/webapps/</code></em>. When Tomcat is started, it will |
|---|
| 168 | automatically expand the web application archive file into its unpacked |
|---|
| 169 | form, and execute the application that way. This approach would typically |
|---|
| 170 | be used to install an additional application, provided by a third party |
|---|
| 171 | vendor or by your internal development staff, into an existing |
|---|
| 172 | Tomcat installation. <strong>NOTE</strong> - If you use this approach, |
|---|
| 173 | and wish to update your application later, you must both replace the |
|---|
| 174 | web application archive file <strong>AND</strong> delete the expanded |
|---|
| 175 | directory that Tomcat created, and then restart Tomcat, in order to reflect |
|---|
| 176 | your changes. |
|---|
| 177 | <br><br></li> |
|---|
| 178 | <li><em>Use the Tomcat 6 "Manager" web application to deploy and undeploy |
|---|
| 179 | web applications</em>. Tomcat 6 includes a web application, deployed |
|---|
| 180 | by default on context path <code>/manager</code>, that allows you to |
|---|
| 181 | deploy and undeploy applications on a running Tomcat server without |
|---|
| 182 | restarting it. See the administrator documentation (TODO: hyperlink) |
|---|
| 183 | for more information on using the Manager web application.<br><br></li> |
|---|
| 184 | <li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat 6 |
|---|
| 185 | includes a set of custom task definitions for the <code>Ant</code> |
|---|
| 186 | build tool that allow you to automate the execution of commands to the |
|---|
| 187 | "Manager" web application. These tasks are used in the Tomcat deployer. |
|---|
| 188 | <br><br></li> |
|---|
| 189 | <li><em>Use the Tomcat Deployer</em>. Tomcat 6 includes a packaged tool |
|---|
| 190 | bundling the Ant tasks, and can be used to automatically precompile JSPs |
|---|
| 191 | which are part of the web application before deployment to the server. |
|---|
| 192 | <br><br></li> |
|---|
| 193 | </ul> |
|---|
| 194 | |
|---|
| 195 | <p>Deploying your app on other servlet containers will be specific to each |
|---|
| 196 | container, but all containers compatible with the Servlet API Specification |
|---|
| 197 | (version 2.2 or later) are required to accept a web application archive file. |
|---|
| 198 | Note that other containers are <strong>NOT</strong> required to accept an |
|---|
| 199 | unpacked directory structure (as Tomcat does), or to provide mechanisms for |
|---|
| 200 | shared library files, but these features are commonly available.</p> |
|---|
| 201 | |
|---|
| 202 | </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> |
|---|
| 203 | Copyright © 1999-2008, Apache Software Foundation |
|---|
| 204 | </em></font></div></td></tr></table></body></html> |
|---|
