Author: markt
Date: Mon Jun 10 20:52:33 2013
New Revision: 1491596
URL: http://svn.apache.org/r1491596
Log:
Try and simplify description of automatic deployment. Remove duplicate
information and add new space that more clearly defines the expected behaviour
(the new page is not yet complete)
Added:
tomcat/trunk/webapps/docs/config/automatic-deployment.xml (with props)
Modified:
tomcat/trunk/webapps/docs/config/host.xml
Added: tomcat/trunk/webapps/docs/config/automatic-deployment.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/automatic-deployment.xml?rev=1491596&view=auto
==============================================================================
--- tomcat/trunk/webapps/docs/config/automatic-deployment.xml (added)
+++ tomcat/trunk/webapps/docs/config/automatic-deployment.xml Mon Jun 10
20:52:33 2013
@@ -0,0 +1,387 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="automatic-deployment.html">
+
+ &project;
+
+ <properties>
+ <title>Automatic Deployment - Use cases</title>
+ </properties>
+
+<body>
+
+<section name="Table of Contents">
+<toc/>
+</section>
+
+
+<section name="Introduction">
+
+ <p>This page defines the expected behaviour of the automatic deployer in many
+ typical use cases. This is a complex area of Tomcat's functionality.
+ While any difference between this document and Tomcat's behaviour is a
+ bug, the fix may be to change this document, Tomcat's behaviour or
+ both.</p>
+
+</section>
+
+
+<section name="Key">
+
+ <table class="detail-table">
+ <tr>
+ <th>Term</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>XML</td>
+ <td>An XML configuration file located in the Host's
+ <em>configBase</em>. It must contain a single <Context> element
+ and may contain optional nested elements. It does not define an
+ explicit <em>docBase</em> attribute. It represents a single web
+ application. It is often referred to as a context.xml file.</td>
+ </tr><tr>
+ <td>XML+EW</td>
+ <td>An XML configuration file located in the Host's
+ <em>configBase</em>. It must contain a single <Context> element
+ and may contain optional nested elements. If includes an explicit
+ <em>docBase</em> attribute that points to an external WAR. It
+ represents a single web application. It is often referred to as a
+ context.xml file.</td>
+ </tr><tr>
+ <td>XML+ED</td>
+ <td>An XML configuration file located in the Host's
+ <em>configBase</em>. It must contain a single <Context> element
+ and may contain optional nested elements. If includes an explicit
+ <em>docBase</em> attribute that points to an external WAR. It
+ represents a single web application. It is often referred to as a
+ context.xml file.</td>
+ </tr><tr>
+ <td>WAR</td>
+ <td>A WAR file located in the Host's <em>appBase</em>. The WAR does
+ not include an embedded context.xml file.</td>
+ </tr><tr>
+ <td>WAR+XML</td>
+ <td>A WAR file located in the Host's <em>appBase</em>. The WAR does
+ include an embedded context.xml file.</td>
+ </tr><tr>
+ <td>DIR</td>
+ <td>A directory located in the Host's <em>appBase</em>. The
directory
+ does not include an embedded context.xml file.</td>
+ </tr><tr>
+ <td>DIR+XML</td>
+ <td>A directory located in the Host's <em>appBase</em>. The director
+ does include an embedded context.xml file.</td>
+ </tr>
+ </table>
+
+</section>
+
+
+<section name="New files">
+
+ <p>This section describes Tomcat's behaviour when the automatic
+ deployment process discovers a new web application.</p>
+
+ <table class="detail-table">
+ <tr>
+ <th rowspan="2">Starting artifact(s)</th>
+ <th colspan="3">Configuration Settings</th>
+ <th colspan="4">Result</th>
+ </tr>
+ <tr>
+ <th>deployXML</th><th>copyXML</th><th>unpackWARs</th>
+ <th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
+ </tr>
+ <tr>
+ <td>XML</td>
+ <td>either</td><td>either</td><td>either</td>
+ <td>Y</td><td>N</td><td>N</td><td>1, 2, 3</td>
+ </tr>
+ <tr>
+ <td>XML+EW</td>
+ <td>either</td><td>either</td><td>false</td>
+ <td>Y</td><td>N</td><td>N</td><td>1</td>
+ </tr>
+ <tr>
+ <td>XML+EW</td>
+ <td>either</td><td>either</td><td>true</td>
+ <td>Y</td><td>N</td><td>Y</td><td>1</td>
+ </tr>
+ <tr>
+ <td>XML+ED</td>
+ <td>either</td><td>either</td><td>either</td>
+ <td>Y</td><td>N</td><td>N</td><td>1, 2</td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>false</td><td>either</td><td>false</td>
+ <td>N</td><td>Y</td><td>N</td><td>4</td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>false</td><td>either</td><td>true</td>
+ <td>N</td><td>Y</td><td>Y</td><td>4</td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>true</td><td>false</td><td>false</td>
+ <td>N</td><td>Y</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>true</td><td>false</td><td>true</td>
+ <td>N</td><td>Y</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>true</td><td>true</td><td>false</td>
+ <td>Y</td><td>Y</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>WAR+XML</td>
+ <td>true</td><td>true</td><td>true</td>
+ <td>Y</td><td>Y</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>WAR</td>
+ <td>either</td><td>either</td><td>false</td>
+ <td>N</td><td>Y</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>WAR</td>
+ <td>either</td><td>either</td><td>true</td>
+ <td>N</td><td>Y</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>DIR+XML</td>
+ <td>false</td><td>either</td><td>either</td>
+ <td>N</td><td>N</td><td>Y</td><td>4</td>
+ </tr>
+ <tr>
+ <td>DIR+XML</td>
+ <td>true</td><td>false</td><td>either</td>
+ <td>N</td><td>N</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>DIR+XML</td>
+ <td>true</td><td>true</td><td>either</td>
+ <td>Y</td><td>N</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>DIR</td>
+ <td>false</td><td>either</td><td>either</td>
+ <td>N</td><td>N</td><td>Y</td><td></td>
+ </tr>
+ </table>
+
+</section>
+
+
+<section name="Deleted files">
+
+ <p>This section describes Tomcat's behaviour when the automatic
+ deployment process detects that a web application file has been deleted.</p>
+
+ <p>When a file is deleted or modified any redeploy resources that are listed
+ after the modified/deleted resource are themselves deleted (and possibly
+ re-created). The order of redeploy resources is:</p>
+
+ <ol>
+ <li>WAR</li>
+ <li>DIR</li>
+ <li>XML</li>
+ <li>global resources</li>
+ </ol>
+
+ <p>There are some exceptions to the deletion rule above:</p>
+
+ <ul>
+ <li>global resources are never deleted</li>
+ <li>external resources are never deleted</li>
+ <li>if the WAR or DIR has been modified then the XML file is only deleted
if
+ <em>copyXML</em> is <code>true</code> and <em>deployXML</em> is
+ <code>true</code></li>
+ </ul>
+
+ <p>In the following table:</p>
+
+ <ul>
+ <li>'-' means "unchanged from not present". i.e. the artifact wasn't
present
+ before the change and isn't present after it either. '-' rather than
'N'
+ is used to focus attention on what changes.</li>
+ <li>'R' means that the directory is re-created by expanding the WAR file.
+ This will only happen if <em>unpackWARs</em> is <code>true</code>.</li>
+ <li>'XW' means that the if the WAR contains a META-INF/context.xml file it
+ will be extracted and placed in the Host's <em>configBase</em>.
+ This only happens if <em>copyXML</em> is <code>true</code> and
+ <em>deployXML</em> is <code>true</code>.</li>
+ <li>'XD' means that the if the directory contains a META-INF/context.xml
+ file it will be copied to the Host's <em>configBase</em>. This
only
+ happens if <em>copyXML</em> is <code>true</code> and <em>deployXML</em>
+ is <code>true</code>.</li>
+ </ul>
+
+ <table class="detail-table">
+ <tr>
+ <th colspan="3">Artifacts present</th>
+ <th rowspan="2">Artifact removed</th>
+ <th colspan="4">Artifacts remaining</th>
+ </tr>
+ <tr>
+ <th>XML</th><th>WAR</th><th>DIR</th>
+ <th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
+ </tr>
+ <tr>
+ <td>N</td><td>N</td><td>Y</td>
+ <td>DIR</td>
+ <td>-</td><td>-</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>N</td>
+ <td>WAR</td>
+ <td>-</td><td>N</td><td>-</td><td></td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>Y</td>
+ <td>DIR</td>
+ <td>-</td><td>Y</td><td>R</td><td></td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>Y</td>
+ <td>WAR</td>
+ <td>-</td><td>N</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>N</td>
+ <td>XML</td>
+ <td>N</td><td>-</td><td>-</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y</td>
+ <td>DIR</td>
+ <td>N</td><td>-</td><td>N</td><td>5</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y</td>
+ <td>XML</td>
+ <td>XD</td><td>-</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>N</td>
+ <td>WAR</td>
+ <td>N</td><td>N</td><td>-</td><td>5</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>N</td>
+ <td>XML</td>
+ <td>XW</td><td>Y</td><td>-</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>DIR</td>
+ <td>XW</td><td>Y</td><td>R</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>WAR</td>
+ <td>N</td><td>N</td><td>N</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>XML</td>
+ <td>XW</td><td>Y</td><td>Y</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y (external)</td><td>N</td>
+ <td>WAR</td>
+ <td>Y</td><td>N</td><td>-</td><td>3</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y (external)</td><td>N</td>
+ <td>XML</td>
+ <td>N</td><td>Y (external)</td><td>-</td><td>6</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y (external)</td>
+ <td>DIR</td>
+ <td>Y</td><td>-</td><td>N</td><td>3</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y (external)</td>
+ <td>XML</td>
+ <td>N</td><td>-</td><td>Y (external)</td><td>6</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y (external)</td><td>Y</td>
+ <td>DIR</td>
+ <td>Y</td><td>Y (external)</td><td>R</td><td></td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y (external)</td><td>Y</td>
+ <td>WAR</td>
+ <td>Y</td><td>N</td><td>N</td><td>3</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y (external)</td><td>Y</td>
+ <td>XML</td>
+ <td>N</td><td>Y (external)</td><td>N</td><td>6</td>
+ </tr>
+ </table>
+
+</section>
+
+
+<section name="Modified files">
+
+ <p>TODO</p>
+
+</section>
+
+
+<section name="Added files">
+
+ <p>TODO</p>
+
+</section>
+
+
+<section name="Notes">
+
+ <ol>
+ <li><em>deployXML</em> and <em>copyXML</em> are ignored since an XML file
+ was discovered in the <em>configBase</em>.</li>
+ <li><em>unpackWARs</em> is ignored since there is no WAR file.</li>
+ <li>The context will fail to start because there is no content in the
+ expected <em>docBase</em>.</li>
+ <li>The embedded META-INF/context.xml is ignored because <em>deployXML</em>
+ is <code>false</code>.</li>
+ <li>The XML file is only deleted if <em>copyXML</em> is <code>true</code>
+ and <em>deployXML</em> is <code>true</code>.</li>
+ <li>Although the external resource is still present, the web application is
+ fully undeployed as Tomcat has no knowledge of the external resource.
+ </li>
+ </ol>
+
+</section>
+
+</body>
+
+</document>
Propchange: tomcat/trunk/webapps/docs/config/automatic-deployment.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: tomcat/trunk/webapps/docs/config/host.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/host.xml?rev=1491596&r1=1491595&r2=1491596&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/host.xml (original)
+++ tomcat/trunk/webapps/docs/config/host.xml Mon Jun 10 20:52:33 2013
@@ -356,115 +356,59 @@
<subsection name="Automatic Application Deployment">
- <p>If you are using the standard <strong>Host</strong> implementation,
- the following actions take place automatically when Catalina is first
- started, if the <code>deployOnStartup</code> property is set to
- <code>true</code> (which is the default value):</p>
- <ul>
- <li>Any XML file in the Host's <code>xmlBase</code> directory (by
- default <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code>) is
- assumed to be a context XML descriptor containing a
- <a href="context.html">Context</a> element (and its associated
- sub-elements) for a single web application. The web applications
- associated with each of these context XML descriptor files will be
- deployed first.<br/>
- The <code>docBase</code> attribute of this <code><Context></code>
- element must only be set if the docBase is outside the Host's
- <code>appBase</code>. For web applications located inside the Host's
- <code>appBase</code>, the <code>docBase</code> will be the name of the
- XML file with ".xml" replaced with ".war" for a web application archive
- or the name of the XML file with ".xml" removed for a directory.<br/>
- The <code>path</code> attribute must not be set. The context path used
- will be a slash character ("/") followed by the name of the XML file
- (less the .xml extension). Multi-level context paths may be defined
- using #, e.g. <code>foo#bar.xml</code> for a context path of
- <code>/foo/bar</code>. The default web application that has a context
- path of <code>/</code> may be defined by using a file called
- <code>ROOT.xml</code>.</li>
- <li>Any web application archive file within the Host's <code>appBase</code>
- directory that has not already been deployed as a result of a context
- XML descriptor, does not have a corresponding directory of the same
- name (without the ".war" extension), and is not excluded by
- <code>deployIgnore</code> will be deployed next. The context path
- used will be a slash character ("/") followed by the web application
- archive name less the ".war" extension. The one exception to this rule
- is that a web application archive named "ROOT.war" will be deployed
with
- a context path of <code>/</code>. Multi-level contexts may be defined
by
- using #, e.g. use a WAR named <code>foo#bar.war</code> for a context
- path of <code>/foo/bar</code>.<br/>
- If the <code>unpackWARs</code> attribute is <code>true</code>, the web
- application archive file will be expanded to a directory of the same
- name (without the ".war" extension".<br/>
- Note: If you re-deploy an updated WAR file while Tomcat is stopped, be
- sure to delete the associated expanded directory before restarting
- Tomcat, so that the updated WAR file will be re-expanded when Tomcat
- restarts.<br/>
- If <code>copyXML</code> is <code>true</code> (it is <code>false</code>
- by default), any web application archive file within the Hosts's
- <code>appBase</code> directory that does not have a corresponding
- context XML descriptor (with a ".xml" extension rather than a ".war"
- extension) in the Host's <code>xmlBase</code> will be scanned to see
- if it contains a context XML descriptor (located at
- <code>/META-INF/context.xml</code>) and if one is found the descriptor
- will be copied to the <code>xmlBase</code> directory and renamed.
- </li>
- <li>Finally, any sub-directory within the Host's <code>appBase</code> that
- has not already been deployed as a result of a context XML descriptor
- and is not excluded by <code>deployIgnore</code> will be deployed.
- The context path used will be a slash character ("/") followed by the
- directory name, unless the directory name is ROOT, in which case the
- context path will <code>/</code>. Multi-level contexts may be defined
by
- using #, e.g. use a directory named <code>foo#bar</code> for a context
- path of <code>/foo/bar</code>.<br/>
- If <code>copyXML</code> is <code>true</code> (it is <code>false</code>
- by default), any directory within the Hosts's <code>appBase</code>
- directory that does not have a corresponding context XML descriptor in
- the Host's <code>xmlBase</code> will be scanned to see if it contains
- a context XML descriptor (located at
<code>/META-INF/context.xml</code>)
- and if one is found the descriptor will be copied to the
- <code>xmlBase</code> directory and renamed.
- </li>
- </ul>
-
- <p>In addition to the automatic deployment that occurs at startup time,
- you can also request that new XML configuration files, WAR files, or
- sub-directories that are dropped in to the <code>appBase</code> (or
- <code>xmlBase</code> in the case of an XML configuration file) directory
- while Tomcat is running will be automatically deployed, according to the
- rules described above. The auto deployer will also track web applications
- for the following changes:
- <ul>
- <li>An update to the WEB-INF/web.xml file will trigger a reload of the
- web application</li>
- <li>Deleting a WAR file will trigger an undeploy of the application
with
- the removal of any associated expanded directory, context file and
- work directory. Any current user sessions will not be persisted.</li>
- <li>Deleting a directory will trigger an undeploy of the application
- with the removal of any associated context file and work directory.
- Any current user sessions will not be persisted. If there is an
- associated WAR file, it will not be deleted and the application will
- be redeployed from the WAR file the next time the auto deployer
checks
- for changes.</li>
- <li>Deleting a context file will trigger an undeploy of the application
- with the removal of any associated work directory. Any current user
- sessions will not be persisted. If there is an associated WAR file
- and/or directory, they will not be deleted and the application will
be
- redeployed from the WAR file (or from directory if there is no WAR
- file) the next time the auto deployer checks for changes.</li>
- <li>Updating a WAR file will trigger an undeploy of the application
with
- the removal of any associated expanded directory, context file and
- work directory. Any current user sessions will not be persisted.</li>
- <li>Updating a directory (not the directory contents) will trigger an
- undeploy of the application with the removal of any associated
context
- file and work directory. Any current user sessions will not be
- persisted. The application will be redeployed the next time the auto
- deployer checks for changes.</li>
- <li>Updating a context file will trigger an undeploy of the application
- with the removal of any associated work directory. Any current user
- sessions will not be persisted. The application will be redeployed
the
- next time the auto deployer checks for changes.</li>
- </ul>
- </p>
+ <p>If you are using the standard <strong>Host</strong> implementation with
+ default settings then applications in the <em>appBase</em> or with context
+ files in the <em>configBase</em> are automatically deployed when Tomcat
+ starts (the <code>deployOnStartup</code> property defaults to
+ <code>true</code>) and reloaded or redeployed (as appropriate) when a
change
+ is detected while Tomcat is running (the \ attribute
+ also defaults to <code>true</code>).</p>
+
+ <p><code>deployOnStartup</code> and <code>autoDeploy</code> trigger
+ execution of exactly the same code so the behaviour is very similar.
+ However, there is one key difference. When Tomcat starts it has no
knowledge
+ of which files are the same, which have been changed and which are new. It
+ therefore treats all files as new. While Tomcat is running, it can
+ differentiate between unchanged, modified and new files. This leads to some
+ differences in behaviour between files being modified while Tomcat is
+ running and files being modified while Tomcat is stopped.</p>
+
+ <p>When you use automatic deployment, related files (a web application may
+ have a context.xml file, a WAR and a directory) that exist in the
+ <strong>Host</strong>'s <em>appBase</em> and/or <em>configBase</em>
+ must conform to the expected <a href="context.html#Naming">naming
+ convention</a>. In short, this means files for the same web application
must
+ share the same <em>base name</em>.</p>
+
+ <p>The automatic deployment process identifies new and/or modified web
+ applications using the following search order:</p>
+
+ <ol>
+ <li>Web applications with a context.xml file located in the Host's
+ <em>configBase</em>.</li>
+ <li>Web applications with a WAR file located in the Host's
+ <em>appBase</em> that have not already been identified during the scan
for
+ context.xml files.</li>
+ <li>Web applications with a directory located in the Host's
+ <em>appBase</em> that have not already been identified during the scans
+ for context.xml and/or WAR files.</li>
+ </ol>
+
+ <p>When <code>autoDeploy</code> is <true>true</true>, the automatic
+ deployment process will monitor the deployed web applications for changes.
+ Depending on exactly what changes, the web application will either be
+ re-deployed or reloaded. Re-deployment involves the creation of a new web
+ application and, if using the standard session manager, user sessions will
+ not be retained. Reloading uses the existing web application but re-parses
+ the web.xml and reloads any classes. If using the standard session manager,
+ user sessions will be persisted.</p>
+
+ <p>Users may add to the files that the automatic deployment process
monitors
+ for reloading (i.e. any change to one of these files triggers a reload of
+ the web application) by adding a <em>WatchedResources</em> element to the
+ context.xml file. See the
+ <a href="context.html#Nested_Components">Context</a> documentation for
+ further details.</p>
<p>When using automatic deployment, the <code>docBase</code> defined by
an XML <a href="context.html">Context</a> file should be outside of the
@@ -473,12 +417,17 @@
be deployed twice. The <code>deployIgnore</code> attribute can be used
to avoid this situation.</p>
- <p>Finally, note that if you are defining contexts explicitly in
server.xml,
- you should probably turn off automatic application deployment or specify
+ <p>Note that if you are defining contexts explicitly in server.xml, you
+ should probably turn off automatic application deployment or specify
<code>deployIgnore</code> carefully. Otherwise, the web applications
will each be deployed twice, and that may cause problems for the
applications.</p>
+ <p>There are many possible combinations of settings, new files, changed
+ files and deleted files. A separate page describes the
+ <a href="automatic-deployment.html">expected behaviour of the automatic
+ deployment process</a> in many of these scenarios.</p>
+
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
