source: nutchez-0.1/tomcat/webapps/docs/appdev/printer/deployment.html @ 139

Last change on this file since 139 was 66, checked in by waue, 16 years ago

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