You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2013/11/26 00:57:40 UTC
svn commit: r1545463 - in /tomcat/tc7.0.x/trunk: ./
webapps/docs/config/automatic-deployment.xml webapps/docs/config/host.xml
Author: markt
Date: Mon Nov 25 23:57:40 2013
New Revision: 1545463
URL: http://svn.apache.org/r1545463
Log:
Backport automatic deployment changes part 20
Document the expected behaviour
Added:
tomcat/tc7.0.x/trunk/webapps/docs/config/automatic-deployment.xml
- copied, changed from r1491596, tomcat/trunk/webapps/docs/config/automatic-deployment.xml
Modified:
tomcat/tc7.0.x/trunk/ (props changed)
tomcat/tc7.0.x/trunk/webapps/docs/config/host.xml
Propchange: tomcat/tc7.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1491596,1491709
Copied: tomcat/tc7.0.x/trunk/webapps/docs/config/automatic-deployment.xml (from r1491596, tomcat/trunk/webapps/docs/config/automatic-deployment.xml)
URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/config/automatic-deployment.xml?p2=tomcat/tc7.0.x/trunk/webapps/docs/config/automatic-deployment.xml&p1=tomcat/trunk/webapps/docs/config/automatic-deployment.xml&r1=1491596&r2=1545463&rev=1545463&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/automatic-deployment.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/config/automatic-deployment.xml Mon Nov 25 23:57:40 2013
@@ -89,6 +89,25 @@
<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><tr>
+ <td>redeploy</td>
+ <td>The Context object that represents the web application is destroyed
+ and a new Context object created. If present and permitted by the
+ configuration, this new Context object is created by parsing the
+ context.xml file. The web.xml file is parsed during the application
+ start process. Any sessions stored in the standard Manager in the
+ default configuration will not be persisted. Any requests to the web
+ application during the redeploy will be handled as if the web
+ application is not deployed.</td>
+ </tr><tr>
+ <td>reload</td>
+ <td>The Context object that represents the web application is stopped and
+ then started. The web.xml file is parsed during the application start
+ process. Any sessions stored in the standard Manager in the default
+ configuration will not be persisted. Any requests to the web
+ application during the reload will be held until the reload completes
+ at which point they will continue using the reloaded web application.
+ </td>
</tr>
</table>
@@ -351,14 +370,151 @@
<section name="Modified files">
- <p>TODO</p>
+ <p>This section describes Tomcat's behaviour when the automatic
+ deployment process detects that a web application file has been modified.</p>
+
+ <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>'M' means that the artifact has been modified.</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>
+ </ul>
+
+ <table class="detail-table">
+ <tr>
+ <th colspan="3">Artifacts present</th>
+ <th rowspan="2">Artifact modified</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>Action</th>
+ </tr>
+ <tr>
+ <td>N</td><td>N</td><td>Y</td>
+ <td>DIR</td>
+ <td>-</td><td>-</td><td>M</td><td>None</td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>N</td>
+ <td>WAR</td>
+ <td>-</td><td>M</td><td>-</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>Y</td>
+ <td>DIR</td>
+ <td>-</td><td>Y</td><td>M</td><td>None</td>
+ </tr>
+ <tr>
+ <td>N</td><td>Y</td><td>Y</td>
+ <td>WAR</td>
+ <td>-</td><td>M</td><td>R</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>N</td>
+ <td>XML</td>
+ <td>M</td><td>-</td><td>-</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y</td>
+ <td>DIR</td>
+ <td>Y</td><td>-</td><td>M</td><td>None</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y</td>
+ <td>XML</td>
+ <td>M</td><td>-</td><td>Y</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>N</td>
+ <td>WAR</td>
+ <td>Y</td><td>M</td><td>-</td><td>Reload</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>N</td>
+ <td>XML</td>
+ <td>M</td><td>Y</td><td>-</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>DIR</td>
+ <td>Y</td><td>Y</td><td>M</td><td>None</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>WAR</td>
+ <td>Y</td><td>M</td><td>Y</td><td>Reload</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y</td><td>Y</td>
+ <td>XML</td>
+ <td>M</td><td>Y</td><td>Y</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y(external)</td><td>N</td>
+ <td>WAR</td>
+ <td>Y</td><td>M(external)</td><td>-</td><td>Reload</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y(external)</td><td>N</td>
+ <td>XML</td>
+ <td>M</td><td>Y(external)</td><td>-</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y(external)</td>
+ <td>DIR</td>
+ <td>Y</td><td>-</td><td>M(external)</td><td>None</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>N</td><td>Y(external)</td>
+ <td>XML</td>
+ <td>M</td><td>-</td><td>Y(external)</td><td>Redeploy</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y(external)</td><td>Y</td>
+ <td>DIR</td>
+ <td>Y</td><td>Y(external)</td><td>M</td><td>None</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y(external)</td><td>Y</td>
+ <td>WAR</td>
+ <td>Y</td><td>M(external)</td><td>R</td><td>Reload</td>
+ </tr>
+ <tr>
+ <td>Y</td><td>Y(external)</td><td>Y</td>
+ <td>XML</td>
+ <td>M</td><td>Y(external)</td><td>Y</td><td>Redeploy</td>
+ </tr>
+ </table>
</section>
<section name="Added files">
- <p>TODO</p>
+ <p>This is treated as if the added file has been modified with the following
+ additional actions:</p>
+
+ <ul>
+ <li>If a WAR is added, any DIR is removed and may be recreated depending on
+ <em>unpackWARs</em>.</li>
+ <li>If an XML file is added that refers to an external <em>docBase</em> any
+ WAR or DIR in the appBase will be removed. The DIR may be recreated if
+ the external resource is a WAR and <em>unpackWARs</em> is true.</li>
+ <li>If a DIR is added when a WAR already exists and <em>unpackWARs</em> is
+ <code>false</code>, the DIR will be ignored but a warning will be
+ logged when the DIR is first detected. If the WAR is removed, the DIR
+ will be left and may be deployed via automatic deployment.</li>
+ <li>If a WAR is added to the <em>appBase</em> when an external WAR already
+ exists, the WAR in the <em>appBase</em> will be ignored but a warning
+ will be logged when the WAR in the <em>appBase</em> is first detected.
+ If the external WAR is removed, the WAR in the <em>appBaase</em> will be
+ left and may be deployed via automatic deployment.</li>
+ </ul>
</section>
Modified: tomcat/tc7.0.x/trunk/webapps/docs/config/host.xml
URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/config/host.xml?rev=1545463&r1=1545462&r2=1545463&view=diff
==============================================================================
--- tomcat/tc7.0.x/trunk/webapps/docs/config/host.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/config/host.xml Mon Nov 25 23:57:40 2013
@@ -357,115 +357,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
@@ -474,12 +418,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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org