One-way ticket to Java: Using Tomcat Ant tasks

Using Tomcat Ant tasks or using Ant to manage Tomcat, whatever you prefer. In the last post, about the directory structure of a web application, I found a little tricky to update the application every time I made changes on it. To reflect the changes on the browser, I had to stop the server, manually delete the deployed application from the webapps folder, install it again and then restart the server. Very tedious. Fortunately, Tomcat 6 includes a convenient set of tasks definitions for the Ant build tool which will help us with this managing tasks. Tasks such as deploy a new web application or undeploy an existing one without having to restart the server.

Usually, to work with this capabilities, is used a web application that Tomcat 6 includes installed by default on context path /manager. Here, we will not configure this web application, instead of that, we will configure the Ant build tool to have the same advantages than the web application manager offers.

Apache Tomcat defines the following configuration steps:

Download the binary distribution of Ant from the official site. You must use version 1.4 or later.
Install the Ant distribution in a convenient directory.
Add the $ANT_HOME/bin directory to your PATH environment variable.
Copy the file $CATALINA_HOME/lib/catalina-ant.jar from your Tomcat 6 installation into Ant's library directory, $ANT_HOME/lib.
Configure at least one username and password combination in your Tomcat user database that includes the manager role.

Summing up, after installing Apache Ant as show in this post and Apache tomcat as shown in this other post, it only remains to complete the two last points of the previous list to have the manager available to us.

Environment

Required software that has already been installed and configured on the system.

Installation steps

Step 1 - Copy the catalina-ant.jar

Yes, copying a file has the category of "step". Don not forget that the $HOME_ANT represents the root of your Ant installation, ~/lab/tools/ant, and $CATALINA_HOME the root of your Tomcat installation, ~/lab/servers/tomcat. Execute this command and it will be done.

~$ cp $CATALINA_HOME/lib/catalina-ant.jar $ANT_HOME/lib/

Terminal

Step 2 - Configure a manager role in Tomcat.

Later, in the Ant script, it is necessary to define a username and password to execute the managing tasks. So we must have at least one user with the manager role defined inside the Tomcat user database. To set up a new user with the manager role, open the file $CATALINA_HOME/conf/tomcat-users.xml, and add the following lines.

<tomcat-users>
  <role rolename="manager"/>
  <user username="tomcatmanager" password="secret" roles="manager"/>
</tomcat-users>

tomcat-users.xml

We have defined a user called tomcatmanager with the password secret, which have the manager role. When defining new users on Tomcat, remember to define the role tag previous to the user using this role. Tomcat will start correctly anyway, but later you will get an HTTP 403 error, warning you that you do not have permission to access this resource.

Step 3 - Writing the ant script

We will define three new properties at the top of the build.xml file. The manager.url property specifies the URL at which the manager web application is available, Tomcat 6 includes this web application by default on context path /manager.

<property name="manager.url" value="http://localhost:8080/manager" />
<property name="manager.username" value="tomcatmanager" />
<property name="manager.password" value="secret" />

build.xml

The manager.username and manager.password properties will have the same value we have previously defined at the tomcat-users.xml file. You might think that including the manager password in your build.xml file is not a really good idea. If so, there is an alternative, do not declare the manager.password property, and specify it from the command line as follows:

~$ ant -Dmanager.password=secret deploy

Terminal

To use custom Tomcat tasks within Ant, we must declare them with the <taskdef> tag. Therefore, we will add this two lines by declaring the deploy and undeploy custom tasks inside our build.xml.

<taskdef name="deploy"    classname="org.apache.catalina.ant.DeployTask"/>
<taskdef name="undeploy"  classname="org.apache.catalina.ant.UndeployTask"/>

build.xml

We shall now define the new Tomcat Ant tasks. Both of them have very similar attributes, this attributes are send as HTTP GET request parameters to the manager web application. We will set the attribute update to true inside the deploy element, that way, the task will replace any existing application under the same path so that we have the latest version.

<target name="deploy" depends="war" description="Install web application">
  <deploy url="${manager.url}" username="${manager.username}" password="${manager.password}"
    path="/${ant.project.name}" war="${build.dir}/${ant.project.name}.war" update="true"/>
</target>

<target name="undeploy" description="Remove web application">
  <undeploy url="${manager.url}" username="${manager.username}" password="${manager.password}"
    path="/${ant.project.name}"/>
</target>

build.xml

Merging these lines with the Ant script we already had from the SimpleWebApp post, ends with a build.xml file that might look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<project name="SimpleWebApp" basedir="." default="install">
  <property environment="env"/>
  <property name="build.dir" value="build" />
  <property name="dist.dir" value="dist" />
  <property name="src.dir" value="src" />
  <property name="web.dir" value="web" />
  <property name="catalina.dir" value="${env.CATALINA_HOME}"/>
  <property name="manager.url" value="http://localhost:8080/manager" />
  <property name="manager.username" value="tomcatmanager" />
  <property name="manager.password" value="secret" />

  <taskdef name="deploy"    classname="org.apache.catalina.ant.DeployTask"/>
  <taskdef name="undeploy"  classname="org.apache.catalina.ant.UndeployTask"/>

  <path id="classpath.build">
    <pathelement location="${catalina.dir}/lib"/>
    <fileset dir="${catalina.dir}/lib">
      <include name="*.jar"/>
    </fileset>
  </path>

  <target name="compile" description="Compiles the classes">
    <mkdir dir="${build.dir}/WEB-INF/classes" />
    <javac srcdir="${src.dir}"
           destdir="${build.dir}/WEB-INF/classes"
           fork="yes"
           classpathref="classpath.build" />
  </target>

  <target name="clean" description="Delete old build and dist directories">
    <delete dir="${build.dir}"/>
    <delete dir="${dist.dir}"/>
  </target>

  <target name="all" depends="clean,compile" description="Clean build and dist directories, then compile"/>

  <target name="dist" depends="all" description="Create an exact image of the binary distribution">
    <mkdir dir="${dist.dir}" />
    <copy todir="${dist.dir}/WEB-INF">
      <fileset dir="${build.dir}/WEB-INF">
        <include name="**/*" />
      </fileset>
    </copy>
    <copy todir="${dist.dir}">
      <fileset dir="${web.dir}">
          <include name="**/*" />
      </fileset>
    </copy>
  </target>

  <target name="install" depends="dist" description="Copy the Web application to the server webapps directory">
    <copy todir="${catalina.dir}/webapps/${ant.project.name}">
      <fileset dir="${dist.dir}">
          <include name="**/*" />
      </fileset>
    </copy>
  </target>

  <target name="war" depends="dist" description="Creates the WAR file">
    <war destfile="${build.dir}/${ant.project.name}.war" webxml="${dist.dir}/WEB-INF/web.xml">
     <fileset dir="${dist.dir}">
        <include name="**/*" />
      </fileset>
    </war>
  </target>

  <target name="deploy" depends="war" description="Install web application">
    <deploy url="${manager.url}" username="${manager.username}" password="${manager.password}"
      path="/${ant.project.name}" war="${build.dir}/${ant.project.name}.war" update="true"/>
  </target>

  <target name="undeploy" description="Remove web application">
    <undeploy url="${manager.url}" username="${manager.username}" password="${manager.password}"
      path="/${ant.project.name}"/>
  </target>

</project>

build.xml

Test

There is not much to test here. If you want to check how works the deploy task and the undeploy task, go to the folder $CATALINA_HOME/webapps, there you can see how the web application is added and removed. And no, I am not going to upload a video to show you how it happens in live.