| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| 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. It 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. It includes an explicit |
| <em>docBase</em> attribute that points to an external directory. 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 directory |
| 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 is 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> |
| |
| </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>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 deleted and 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>R</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>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>appBase</em> will be |
| left and may be deployed via automatic deployment.</li> |
| <li>If an XML file is added to the META-INF directory of an application |
| deployed from that DIR, the application will always be redeployed. The |
| result will be the same as for a new deployment.</li> |
| </ul> |
| |
| </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 web application fails to deploy because it contains an embedded |
| META-INF/context.xml, <em>deployXML</em> is <code>false</code> and an |
| XML has not been provided in the <em>configBase</em>.</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> |
