Recipe 4.8 Stopping a Tomcat Application with Ant

Problem

You want to use Ant to stop a specific Tomcat web application.

Solution

Define a task in the Ant file using a taskdef element and the Java class org.apache.catalina.ant.StopTask .

Discussion

During development, you might need to stop a Tomcat web application so that you can add new servlets or deployment-descriptor entries, and then restart the application, allowing the changes to take effect. In the absence of a conf/server.xml configuration to make the application dynamically reloadable (see Recipe 2.2), you can use an Ant target to stop a particular web application without disrupting the other running web applications. This is the opposite of starting an application (Recipe 4.7); the application is taken out of service until you start it again.

The org.apache.catalina.ant.StopTask class provides a connection between Ant and the Tomcat Manager application. Manager is a built-in web application (at context path /manager ) that you can use to administer other Tomcat web applications.

Implement the same four steps discussed in Recipe 4.7 to use this stop task:

1. Make sure you have the necessary JAR file required to use the Ant task for stopping Tomcat: <Ant-installation-directory>/lib/catalina-ant.jar . Copy this JAR from the <Tomcat-installation-directory>/server/lib directory to your <Ant-installation-directory>/lib directory ( otherwise known as ANT_HOME/lib ).

2. Make sure the Tomcat user database includes a username that is linked to the manager role (see step 2 of Recipe 4.7 if you need more details).

3. Example 4-9 uses a taskdef element to give the task the name stop , which is used by the target that is responsible for stopping Tomcat.

4. Run the Ant file at the command line by changing to its directory and typing ant or ant -buildfile buildfile-name .

Example 4-9. Using Ant to stop a web application

 <project name="My Project" default="stop-tomcat" basedir=".">  <taskdef name="stop" classname="org.apache.catalina.ant.StopTask" /> <!-- import properties specifying username, password, url, and context-path --> <property file="global.properties" /> <target name="stop-tomcat"       description="Stops the Web application">      <echo message="Stopping the application ${context-path}..."/>      <stop         url="${url}"          username="${username}"          password="${password}"          path="/${context-path}" /> </target>  </project> 

The taskdef defines a task for this build file called stop . The defined task is then used in the build file:

 <stop url="${url}" username="${username}" password="${password}"        path="/${context-path}" /> 

Example 4-9 gets its property values from a property task that imports global.properties (the property file is located in the same directory as the Ant build file). The properties represent:

• The username and password of a user who is mapped to the manager role in conf/ tomcat-users .xml

• The URL to the Manager application, as in http://localhost:8080/manager

• The context path for the web application that you are stopping

The Tomcat manager application can initiate many other common administrative tasks such as deploying applications (see Recipe 2.6).

See Also

The Tomcat Manager application description: http://jakarta.apache.org/tomcat/tomcat-4.1-doc/manager-howto.html; Recipe 4.1 on downloading and setting up Ant; Recipe 4.2 on writing Ant targets; Recipe 4.3 on creating a classpath for an Ant file; Recipe 4.4 on compiling a servlet with Ant; Recipe 4.5 and Recipe 4.6 on creating WAR and JAR files; Recipe 4.7 on starting Tomcat with Ant; Recipe 2.1 and Recipe 2.6 on deploying web applications using Ant; the Ant manual section on the property task: http://ant.apache.org/manual/CoreTasks/property.html; the Ant manual segment on targets : http://ant.apache.org/manual/using.html#targets; the Apache Ant manual index page: http://ant.apache.org/manual/index.html; the Apache Ant Project: http://ant.apache.org.