Signal a stopped application to restart, and make itself available again. Stopping and starting is useful, for example, if the database required by your application becomes temporarily unavailable. It is usually better to stop the web application that relies on this database rather than letting users continuously encounter database exceptions.

If this command succeeds, you will see a Message like this:

Otherwise, the Message will start with FAIL and include an error message. Possible causes for problems include:

• Encountered exception

  An exception was encountered trying to start the web application. Check the Tomcat 5 logs for the details.

• Invalid context path was specified

  The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

• No context exists for path /foo

  There is no deployed application on the context path that you specified.

• No context path was specified

  The path parameter is required.

Signal an existing application to make itself unavailable, but leave it deployed. Any request that comes in while an application is stopped will see an HTTP error 404, and this application will show as "stopped" on a list applications command.

If this command succeeds, you will see a Message like this:

Otherwise, the Message will start with FAIL and include an error message. Possible causes for problems include:

• Encountered exception

  An exception was encountered trying to stop the web application. Check the Tomcat 5 logs for the details.

• Invalid context path was specified

  The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

• No context exists for path /foo

  There is no deployed application on the context path that you specified.

• No context path was specified

  The path parameter is required.

Signal an existing application to shut itself down and reload. This can be useful when the web application context is not reloadable and you have updated classes or property files in the /WEB-INF/classes directory or when you have added or updated jar files in the /WEB-INF/lib directory.

NOTE: The /WEB-INF/web.xml web application configuration file is not checked on a reload; the previous web.xml configuration is used. If you have made changes to your web.xml file you must stop then start the web application.

If this command succeeds, you will see a Message like this:

Otherwise, the Message will start with FAIL and include an error message. Possible causes for problems include:

• Encountered exception

  An exception was encountered trying to restart the web application. Check the Tomcat 5 logs for the details.

• Invalid context path was specified

  The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

• No context exists for path /foo

  There is no deployed application on the context path that you specified.

• No context path was specified

  The path parameter is required.

• Reload not supported on WAR deployed at path /foo

  Currently, application reloading (to pick up changes to the classes or web.xml file) is not supported when a web application is installed directly from a WAR file, which happens when the host is configured to not unpack WAR files. As it only works when the web application is installed from an unpacked directory, if you are using a WAR file, you should undeploy and then deploy the application again to pick up your changes.

WARNING - This command will delete the contents of the web application directory and/or ".war" file if it exists within the appBase directory (typically "webapps") for this virtual host . The web application temporary work directory is also deleted. If you simply want to take an application out of service, you should use the /stop command instead.

Signal an existing application to gracefully shut itself down, and then remove it from Tomcat (which also makes this context path available for reuse later). This command is the logical opposite of the /deploy Ant command, and the related deploy features available in the HTML manager.

If this command succeeds, you will see a Message like this:

Otherwise, the Message will start with FAIL and include an error message. Possible causes for problems include:

• Encountered exception

  An exception was encountered trying to undeploy the web application. Check the Tomcat logs for the details.

• Invalid context path was specified

  The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

• No context exists for path /foo

  There is no deployed application on the context path that you specified.

• No context path was specified

  The path parameter is required.

Deploy and start a new web application, attached to the specified Context Path: (which must not be in use by any other web application). This command is the logical opposite of the Undeploy command.

There are a number of different ways the deploy command can be used.

Deploy a Directory or WAR by URL

Install a web application directory or ".war" file located on the Tomcat server. If no Context Path is specified, the directory name or the war file name without the ".war" extension is used as the path. The WAR or Directory URL specifies a URL (including the file: scheme) for either a directory or a web application archive (WAR) file. The supported syntax for a URL referring to a WAR file is described on the Javadocs page for the java.net.JarURLConnection class. Use only URLs that refer to the entire WAR file.

In this example the web application located in the directory C:\path\to\foo on the Tomcat server (running on Windows) is deployed as the web application context named /footoo. Context Path: /footoo WAR or Directory URL: file:C:/path/to/foo

In this example the ".war" file /path/to/bar.war on the Tomcat server (running on Unix) is deployed as the web application context named /bar. Notice that there is no path parameter so the context path defaults to the name of the web application archive file without the ".war" extension. WAR or Directory URL: jar:file:/path/to/bar.war!/

Deploy a Directory or War from the Host appBase

Install a web application directory or ".war" file located in your Host appBase directory. If no Context Path is specified the directory name or the war file name without the ".war" extension is used as the path.

In this example the web application located in a subdirectory named foo in the Host appBase directory of the Tomcat server is deployed as the web application context named /foo. Notice that there is no path parameter so the context path defaults to the name of the web application directory. WAR or Directory URL: foo

In this example the ".war" file bar.war located in your Host appBase directory on the Tomcat server is deployed as the web application context named /bartoo. Context Path: /bartoo WAR or Directory URL: bar.war

Deploy using a Context configuration ".xml" file

If the Host deployXML flag is set to true, you can install a web application using a Context configuration ".xml" file and an optional ".war" file or web application directory. The Context Path is not used when installing a web application using a context ".xml" configuration file.

A Context configuration ".xml" file can contain valid XML for a web application Context just as if it were configured in your Tomcat server.xml configuration file. Here is an example for Tomcat running on Windows: <Context path="/foobar" docBase="C:\path\to\application\foobar" debug="0"> <!-- Link to the user database we will get roles from --> <ResourceLink name="users" global="UserDatabase" type="org.apache.catalina.UserDatabase"/> </Context>

Use of the WAR or Directory URL is optional. When used to select a web application ".war" file or directory it overrides any docBase configured in the context configuration ".xml" file.

Here is an example of installing an application using a Context configuration ".xml" file for Tomcat running on Windows. XML Configuration file URL: file:C:/path/to/context.xml

Here is an example of installing an application using a Context configuration ".xml" file and a web application ".war" file located on the server (Tomcat running on Unix). XML Configuration file URL: file:/path/to/context.xml WAR or Directory URL: jar:file:/path/to/bar.war!/

Upload a WAR file from your local system and install it into the appBase for your Host. The name of the WAR file without the ".war" extension is used as the context path name.

Use the Browse button to select a WAR file to upload to the server from your local desktop system.

The .WAR file may include Tomcat specific deployment configuration, by including a Context configuration XML file in /META-INF/context.xml.

Upload of a WAR file could fail for the following reasons:

• File uploaded must be a .war

  The upload install will only accept files which have the filename extension of ".war".

• War file already exists on server

  If a war file of the same name already exists in your Host's appBase the upload will fail. Either undeploy the existing war file from your Host's appBase or upload the new war file using a different name.

• File upload failed, no file

  The file upload failed, no file was received by the server.

• Install Upload Failed, Exception:

  The war file upload or install failed with a Java Exception. The exception message will be listed.

If the Host is configured with unpackWARs=true and you install a war file, the war will be unpacked into a directory in your Host appBase directory.

If the application war or directory is deployed in your Host appBase directory and either the Host is configured with autoDeploy=true or liveDeploy=true, the Context path must match the directory name or war file name without the ".war" extension.

For security when untrusted users can manage web applications, the Host deployXML flag can be set to false. This prevents untrusted users from installing web applications using a configuration XML file and also prevents them from installing application directories or ".war" files located outside of their Host appBase.

If deployment and startup is successful, you will receive a Message like this:

Otherwise, the Message will start with FAIL and include an error message. Possible causes for problems include:

• Application already exists at path /foo

  The context paths for all currently running web applications must be unique. Therefore, you must either undeploy the existing web application using this context path, or choose a different context path for the new one.

• Document base does not exist or is not a readable directory

  The URL specified by the WAR or Directory URL: field must identify a directory on this server that contains the "unpacked" version of a web application, or the absolute URL of a web application archive (WAR) file that contains this application. Correct the value entered for the WAR or Directory URL: field.

• Encountered exception

  An exception was encountered trying to start the new web application. Check the Tomcat 5 logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.

• Invalid application URL was specified

  The URL for the WAR or Directory URL: field that you specified was not valid. Such URLs must start with file:, and URLs for a WAR file must end in ".war".

• Invalid context path was specified

  The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a "/" string.

• Context path must match the directory or WAR file name:

  If the application war or directory is deployed in your Host appBase directory and either the Host is configured with autoDeploy=true or liveDeploy=true, the Context path must match the directory name or war file name without the ".war" extension.

• Only web applications in the Host web application directory can be deployed

  If the Host deployXML flag is set to false this error will happen if an attempt is made to install a web application directory or ".war" file outside of the Host appBase directory.