Recipe 4.7 Starting a Tomcat Application with Ant

Problem

You want to start a web application on Tomcat using an Ant file.

Solution

Use the Tomcat-supplied StartTask task so that Ant can manage Tomcat.

Discussion

The Tomcat servlet and JSP container includes a built-in web application called "Manager" that you can use to start, stop, deploy, and initiate other administrative tasks with web applications. Tomcat makes this application available from the /manager context path .

Tomcat Version 4 (and later) includes Java classes that allow developers to use the Manager application from their Ant build files. The advantage of using the Manager application from Ant is that you do not have to configure the conf/server.xml file to make the web application dynamically reloadable (see Recipe 2.2). In addition, you can start or stop a single web application without disrupting other Tomcat applications.

The Manager documentation is found online at http://jakarta.apache.org/tomcat/tomcat-4.1-doc/printer/manager-howto.html

Take these steps to start Tomcat from Ant:

1. Make sure you have the necessary JAR file required to use the Ant task for starting 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. Only administrative users should be authorized to start and stop web applications using the Manager tool. The conf/ tomcat-users .xml file maps users and passwords to roles. A user has to be mapped to the manager role to be able to use the Manager tool. Here is an example of one of these user mappings in tomcat-users.xml :

    <user username="doug" password= "_1968dgw" roles="manager,dbadmin"/> 

3. Use the taskdef element in the Ant file to define the custom task and give it a name. Example 4-8 gives the task the name start , which is used by the target that is responsible for starting Tomcat.

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

Example 4-8 shows the taskdef element that defines the start task, followed by the target that starts the specified Tomcat application.

Example 4-8. Starting Tomcat using an Ant file

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

The start task has four attributes that Example 4-8 sets using a global.properties file. This is a text file containing four name/value pairs, which are imported into the Ant file using the property task:

 <property file="global.properties" /> 

The global.properties file is located in the same directory as the Ant build file. Here are the contents of the global.properties file:

 url=http://localhost:8080/manager username=bruce password=bruce1957 context-path=home 

The url property specifies the Tomcat Manager URL, the username and password identify the user who is mapped in the Tomcat user database to the manager role, the context-path property specifies the context path of the web application you are starting, and the Ant file itself specifies the opening slash ( /) character for the context path.

Another way to pass properties to an Ant file is on the command line:

 ant -Dusername=bruce -Dpassword=bruce1957 -Durl=http://localhost:8080/manager  -Dcontext-path=home 

Properties added on the command line override those specified by the property task.

Launch this Ant file by changing to its directory at the command line and typing ant or ant -buildfile buildfile-name . Here is the command-line output:

 H:\book\cookbook\code\chap4>  ant -buildfile start.xml  Buildfile: start.xml start-tomcat:      [echo] Starting the default application home...     [start] OK - Started application at context path /home BUILD SUCCESSFUL Total time: 4 seconds 

If an application is stopped , it is unavailable to web users (see Recipe 4.8). When the application is started again, it can receive requests normally.

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.8 on stopping 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.