Automatic Deployment

&project; Automatic Deployment - Use cases

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.

Term	Description
XML	An XML configuration file located in the Host's configBase. It must contain a single <Context> element and may contain optional nested elements. It does not define an explicit docBase attribute. It represents a single web application. It is often referred to as a context.xml file.
XML+EW	An XML configuration file located in the Host's configBase. It must contain a single <Context> element and may contain optional nested elements. It includes an explicit docBase attribute that points to an external WAR. It represents a single web application. It is often referred to as a context.xml file.
XML+ED	An XML configuration file located in the Host's configBase. It must contain a single <Context> element and may contain optional nested elements. It includes an explicit docBase attribute that points to an external directory. It represents a single web application. It is often referred to as a context.xml file.
WAR	A WAR file located in the Host's appBase. The WAR does not include an embedded context.xml file.
WAR+XML	A WAR file located in the Host's appBase. The WAR does include an embedded context.xml file.
DIR	A directory located in the Host's appBase. The directory does not include an embedded context.xml file.
DIR+XML	A directory located in the Host's appBase. The directory does include an embedded context.xml file.
redeploy	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.
reload	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.

This section describes Tomcat's behaviour when the automatic deployment process discovers a new web application.

Starting artifact(s)	Configuration Settings			Result
Starting artifact(s)	deployXML	copyXML	unpackWARs	XML	WAR	DIR	Notes
XML	either	either	either	Y	N	N	1, 2, 3
XML+EW	either	either	false	Y	N	N	1
XML+EW	either	either	true	Y	N	Y	1
XML+ED	either	either	either	Y	N	N	1, 2
WAR+XML	false	either	false	N	Y	N	4
WAR+XML	false	either	true	N	Y	Y	4
WAR+XML	true	false	false	N	Y	N
WAR+XML	true	false	true	N	Y	Y
WAR+XML	true	true	false	Y	Y	N
WAR+XML	true	true	true	Y	Y	Y
WAR	either	either	false	N	Y	N
WAR	either	either	true	N	Y	Y
DIR+XML	false	either	either	N	N	Y	4
DIR+XML	true	false	either	N	N	Y
DIR+XML	true	true	either	Y	N	Y
DIR	false	either	either	N	N	Y

This section describes Tomcat's behaviour when the automatic deployment process detects that a web application file has been deleted.

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:

WAR
DIR
XML
global resources

There are some exceptions to the deletion rule above:

global resources are never deleted
external resources are never deleted
if the WAR or DIR has been modified then the XML file is only deleted if copyXML is true and deployXML is true

In the following table:

'-' 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.
'R' means that the directory is re-created by expanding the WAR file. This will only happen if unpackWARs is true.
'XW' means that the if the WAR contains a META-INF/context.xml file it will be extracted and placed in the Host's configBase. This only happens if copyXML is true and deployXML is true.
'XD' means that the if the directory contains a META-INF/context.xml file it will be copied to the Host's configBase. This only happens if copyXML is true and deployXML is true.

Artifacts present			Artifact removed	Artifacts remaining
XML	WAR	DIR	Artifact removed	XML	WAR	DIR	Notes
N	N	Y	DIR	-	-	N
N	Y	N	WAR	-	N	-
N	Y	Y	DIR	-	Y	R
N	Y	Y	WAR	-	N	N
Y	N	N	XML	N	-	-
Y	N	Y	DIR	N	-	N	5
Y	N	Y	XML	XD	-	Y
Y	Y	N	WAR	N	N	-	5
Y	Y	N	XML	XW	Y	-
Y	Y	Y	DIR	XW	Y	R
Y	Y	Y	WAR	N	N	N
Y	Y	Y	XML	XW	Y	Y
Y	Y (external)	N	WAR	Y	N	-	3
Y	Y (external)	N	XML	N	Y (external)	-	6
Y	N	Y (external)	DIR	Y	-	N	3
Y	N	Y (external)	XML	N	-	Y (external)	6
Y	Y (external)	Y	DIR	Y	Y (external)	R
Y	Y (external)	Y	WAR	Y	N	N	3
Y	Y (external)	Y	XML	N	Y (external)	N	6

This section describes Tomcat's behaviour when the automatic deployment process detects that a web application file has been modified.

In the following table:

'-' 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.
'M' means that the artifact has been modified.
'R' means that the directory is deleted and re-created by expanding the WAR file. This will only happen if unpackWARs is true.

Artifacts present			Artifact modified	Artifacts remaining
XML	WAR	DIR	Artifact modified	XML	WAR	DIR	Action
N	N	Y	DIR	-	-	M	None
N	Y	N	WAR	-	M	-	Redeploy
N	Y	Y	DIR	-	Y	M	None
N	Y	Y	WAR	-	M	R	Redeploy
Y	N	N	XML	M	-	-	Redeploy
Y	N	Y	DIR	Y	-	M	None
Y	N	Y	XML	M	-	Y	Redeploy
Y	Y	N	WAR	Y	M	-	Reload
Y	Y	N	XML	M	Y	-	Redeploy
Y	Y	Y	DIR	Y	Y	M	None
Y	Y	Y	WAR	Y	M	R	Reload
Y	Y	Y	XML	M	Y	Y	Redeploy
Y	Y(external)	N	WAR	Y	M(external)	-	Reload
Y	Y(external)	N	XML	M	Y(external)	-	Redeploy
Y	N	Y(external)	DIR	Y	-	M(external)	None
Y	N	Y(external)	XML	M	-	Y(external)	Redeploy
Y	Y(external)	Y	DIR	Y	Y(external)	M	None
Y	Y(external)	Y	WAR	Y	M(external)	R	Reload
Y	Y(external)	Y	XML	M	Y(external)	Y	Redeploy

This is treated as if the added file has been modified with the following additional actions:

If a WAR is added, any DIR is removed and may be recreated depending on unpackWARs.
If an XML file is added that refers to an external docBase any WAR or DIR in the appBase will be removed. The DIR may be recreated if the external resource is a WAR and unpackWARs is true.
If a DIR is added when a WAR already exists and unpackWARs is false, 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.
If a WAR is added to the appBase when an external WAR already exists, the WAR in the appBase will be ignored but a warning will be logged when the WAR in the appBase is first detected. If the external WAR is removed, the WAR in the appBase will be left and may be deployed via automatic deployment.
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.

deployXML and copyXML are ignored since an XML file was discovered in the configBase.
unpackWARs is ignored since there is no WAR file.
The context will fail to start because there is no content in the expected docBase.
The web application fails to deploy because it contains an embedded META-INF/context.xml, deployXML is false and an XML has not been provided in the configBase.
The XML file is only deleted if copyXML is true and deployXML is true.
Although the external resource is still present, the web application is fully undeployed as Tomcat has no knowledge of the external resource.