Executing Manager Commands With Ant

In addition to the ability to execute Manager commands via HTTP requests, as documented above, Tomcat includes a convenient set of Task definitions for the Ant (version 1.4 or later) build tool. In order to use these commands, you must perform the following setup operations:

• Download the binary distribution of Ant from http://ant.apache.org. You must use version 1.4 or later.
• Install the Ant distribution in a convenient directory (called ANT_HOME in the remainder of these instructions).
• Copy the file server/lib/catalina-ant.jar from your Tomcat installation into Ant’s library directory ($ANT_HOME/lib).
• Add the $ANT_HOME/bin directory to your PATH environment variable.
• Configure at least one username/password combination in your Tomcat user database that includes themanager-script role.

To use custom tasks within Ant, you must declare them first with a <taskdef> element. Therefore, your build.xmlfile might look something like this:

<project name=”My Application” default=”compile” basedir=”.”>

<!– Configure the directory into which the web application is built –>

<property name=”build”   value=”${basedir}/build”/>

<!– Configure the context path for this application –>

<property name=”path”     value=”/myapp”/>

 

<!– Configure properties to access the Manager application –>

<property name=”url”     value=”http://localhost:8080/manager/text”/>

<property name=”username” value=”myusername”/>

<property name=”password” value=”mypassword”/>

 

<!– Configure the custom Ant tasks for the Manager application –>

<taskdef name=”deploy”   classname=”org.apache.catalina.ant.DeployTask”/>

<taskdef name=”list”     classname=”org.apache.catalina.ant.ListTask”/>

<taskdef name=”reload”   classname=”org.apache.catalina.ant.ReloadTask”/>

<taskdef name=”findleaks” classname=”org.apache.catalina.ant.FindLeaksTask”/>

<taskdef name=”resources” classname=”org.apache.catalina.ant.ResourcesTask”/>

<taskdef name=”start”     classname=”org.apache.catalina.ant.StartTask”/>

<taskdef name=”stop”     classname=”org.apache.catalina.ant.StopTask”/>

<taskdef name=”undeploy” classname=”org.apache.catalina.ant.UndeployTask”/>

 

<!– Executable Targets –>

<target name=”compile” description=”Compile web application”>

<!– … construct web application in ${build} subdirectory, and

generated a ${path}.war … –>

</target>

 

<target name=”deploy” description=”Install web application”

depends=”compile”>

<deploy url=”${url}” username=”${username}” password=”${password}”

path=”${path}” war=”file:${build}${path}.war”/>

</target>

 

<target name=”reload” description=”Reload web application”

depends=”compile”>

<reload url=”${url}” username=”${username}” password=”${password}”

path=”${path}”/>

</target>

 

<target name=”undeploy” description=”Remove web application”>

<undeploy url=”${url}” username=”${username}” password=”${password}”

path=”${path}”/>

</target>

</project>

 

The definition of the resources task above will override the resources datatype added in Ant 1.7. If you wish to use the resources datatype you will need to use Ant’s namespace support to assign the Tomcat tasks to their own namespace.

Now, you can execute commands like ant deploy to deploy the application to a running instance of Tomcat, or ant reload to tell Tomcat to reload it. Note also that most of the interesting values in this build.xml file are defined as replaceable properties, so you can override their values from the command line. For example, you might consider it a security risk to include the real manager password in your build.xml file’s source code. To avoid this, omit the password property, and specify it from the command line:

ant -Dpassword=secret deploy

Tasks output capture

Using Ant version 1.6.2 or later, the Catalina tasks offer the option to capture their output in properties or external files. They support directly the following subset of the <redirector> type attributes:

Attribute	Description	Required
output	Name of a file to which to write the output. If the error stream is not also redirected to a file or property, it will appear in this output.	No
error	The file to which the standard error of the command should be redirected.	No
logError	This attribute is used when you wish to see error output in Ant’s log and you are redirecting output to a file/property. The error output will not be included in the output file/property. If you redirect error with the error or errorProperty attributes, this will have no effect.	No
append	Whether output and error files should be appended to or overwritten. Defaults to false.	No
createemptyfiles	Whether output and error files should be created even when empty. Defaults to true.	No
outputproperty	The name of a property in which the output of the command should be stored. Unless the error stream is redirected to a separate file or stream, this property will include the error output.	No
errorproperty	The name of a property in which the standard error of the command should be stored.	No

A couple of additional attributes can also be specified:

They also support the embedded <redirector> element in which you can specify its full set of attributes, but input, inputstring and inputencoding that, even if accepted, are not used because they have no meaning in this context. Refer to ant manual for details on <redirector> element attributes.

Here is a sample build file extract that shows how this output redirection support can be used:

<target name=”manager.deploy”

depends=”context.status”

if=”context.notInstalled”>

<deploy url=”${mgr.url}”

username=”${mgr.username}”

password=”${mgr.password}”

path=”${mgr.context.path}”

config=”${mgr.context.descriptor}”/>

</target>

 

<target name=”manager.deploy.war”

depends=”context.status”

if=”context.deployable”>

<deploy url=”${mgr.url}”

username=”${mgr.username}”

password=”${mgr.password}”

update=”${mgr.update}”

path=”${mgr.context.path}”

war=”${mgr.war.file}”/>

</target>

 

<target name=”context.status”>

<property name=”running” value=”${mgr.context.path}:running”/>

<property name=”stopped” value=”${mgr.context.path}:stopped”/>

 

<list url=”${mgr.url}”

outputproperty=”ctx.status”

username=”${mgr.username}”

password=”${mgr.password}”>

</list>

 

<condition property=”context.running”>

<contains string=”${ctx.status}” substring=”${running}”/>

</condition>

<condition property=”context.stopped”>

<contains string=”${ctx.status}” substring=”${stopped}”/>

</condition>

<condition property=”context.notInstalled”>

<and>

<isfalse value=”${context.running}”/>

<isfalse value=”${context.stopped}”/>

</and>

</condition>

<condition property=”context.deployable”>

<or>

<istrue value=”${context.notInstalled}”/>

<and>

<istrue value=”${context.running}”/>

<istrue value=”${mgr.update}”/>

</and>

<and>

<istrue value=”${context.stopped}”/>

<istrue value=”${mgr.update}”/>

</and>

</or>

</condition>

<condition property=”context.undeployable”>

<or>

<istrue value=”${context.running}”/>

<istrue value=”${context.stopped}”/>

</or>

</condition>

</target>

 

Even if it doesn’t make many sense, and is always a bad idea, calling a Catalina task more than once, badly set Ant tasks depends chains may cause that a task be called more than once in the same Ant run, even if not intended to. A bit of caution should be exercised when you are capturing output from that task, because this could lead to something unexpected:

• when capturing in a property you will find in it only the output from the first call, because Ant properties are immutable and once set they cannot be changed,
• when capturing in a file, each run will overwrite it and you will find in it only the last call output, unless you are using the append=”true” attribute, in which case you will see the output of each task call appended to the file.