Apache Ant is a powerful way to convert your developmental structures to deployment structures. It is declarative and all the command line tasks used for deploying an application are represented by simple XML elements. Without much details, this tutorial would breeze you through the steps on how to build a web application using a single XML build file and nothing else. If you have not yet understood what is the use of Ant, read my article on Development and Deployment Structures – the perfect way to build web applications.

I would use the same analogy of my development structure as mentioned in the above linked article i.e. my development structure consists of the following directories:

  1. web – place for all my JSP, HTML, JavaScripts and Stylesheets. You can provide subdirectories as required for each of the different set of files
  2. src – place for my java class files consisting of POJO’s or servlets.
  3. etc – place for all config files like the most common web.xml
  4. lib - place for all the necessary jar files to run my application. I even have included servlet-api.jar in this directory since you may have to deploy your web application in a remote server after compiling.
  5. build – a temporary directory for keeping the compiled files
  6. dist – a place to put in the finally packaged war file (distribution)
  7. ant- place for my build.xml file and external properties file

All these directories are present in a parent directory called “WebApp“. The three things you have to keep in mind for making an Ant build file are -

  1. tasks - which correspond to your command line tasks like javac, war etc. A group of tasks can be executed in a sequence by specifying targets.
  2. target – It is like a function where you put reusable tasks so that it can be called later without duplicating them.
  3. property – this element is used to define variables in your build file which is useful when the value like project_name or folder_name keeps on changing.

One of the most awesome features of Ant is that you can keep the properties file externally inside of defining all the variables within the build file. This properties file consists of all the required variables and their values in the form of name-value pairs and is simple text file. In this tutorial I would be using an external properties file.

For the tutorial I have used the following:

  1. Java version 1.5
  2. Apache Tomcat 5.0
  3. Apache Ant 1.6.5

Okay we are now good to go with the great Ant tutorial. For this make a file with the name “build.properties“. This would be our external variables file.

root.dir=..
lib.dir=lib
src.dir=com
conf.dir=etc
web.content=web
project.name=WebApp
build.dir=build

NOTE: you must hit the ENTER key for starting a new line after the last line or Ant will give you an error “BUILD FAILED for some unknown reason”

It is not necessary to put in the name with the dot. You can have a name as “projectName” but there should be no quotes for the value. i.e it should NOT be projectName=”WebApp”

To make a build file we have to remember what is to be done for the deployments. To make things simple just make the modules (targets) necessary for the complete web application deployment which are

  1. clean – remove all prior deployments of the same application if made
  2. init – make the necessary structure for deployment as per the vendor’s
  3. compile – compile your servlets or POJO’s
  4. copy – put the compiled files and web content in the deployment structre as created during init
  5. war – make the war file and open the browser

Start making the build.xml file in the ant folder as follows:

<project name="AppBuilder" default="war" basedir="..">
	<property file="ant/build.properties"/>
</project>

Now we have to set the classpath for the servlet-api.jar to compile our servlets so put the servlet-api.jar in the lib directory of your development structure. Check the property “default” in the <project> element. It states the LAST module (target) inside the build file. In our case it is “war”

All the following XML elements will now go inside the <project></project> element created above. So put the classpath setting element,

<path id="classpath">
 	<fileset dir="${lib.dir}" includes="servlet-api.jar"/>
</path>

Here you need to set all the necessary jars to your classpath for successful compilation of the java source files. ${lib.dir} is used to retrive the value of the “lib.dir” i.e lib

Now we will start with out targets (modules) as mentioned in the list above :

1. clean

<target name="clean">
	<echo>Cleaning the ${build.dir}</echo>
	<delete dir="${build.dir}"/>
</target>

Here I am removing my build dir in case it was present earlier with compiled files
The <echo> element is only for displaying what you are doing in the command line.

2. init

<target name="init" depends="clean">
	<echo>Creating the build directory</echo>
	<mkdir dir="${build.dir}/WEB-INFclasses"/>
	<mkdir dir="${build.dir}/WEB-INFlib"/>
</target>

Here I am creating the normal deployment structure required for tomcat namely WebApp/WEB-INF/classes, etc. It doesn’t matter if the folder WEB-INF existed before making the folder classes. Ant automatically creates all the necessary parent folders if they don’t exist.

3. compile

<target name="compile" depends="init">
	<echo>Compile the source files</echo>
	<javac srcdir="${src.dir}" destdir="${build.dir}/WEB-INF/classes">
		<classpath refid="classpath"/>
	</javac>
</target>

Most important step and the most error giving step. Make sure that all the classpath have been set in the above <path> element. If all are proper then the all files in “src.dir” will be compiled successfully and moved to the build\WebApp\WEB-INF\classes. Just check the property “depends” of the <target> element here. This property is used to chain the modules (targets) in a sequential manner.

4. copy

<target name="copy" depends="compile">
	<copy todir="${build.dir}/WEB-INF">
		<fileset dir="${conf.dir}"/>
	</copy>
	<copy todir="${build.dir}">
		<fileset dir="${web.content}"/>
	</copy>
	<copy todir="${build.dir}/WEB-INF/lib">
		<fileset dir="${lib.dir}"/>
	</copy>
</target>

Here I am just copying my complied classes and web content files inside the corresponding deployment structure.

5. war

<target name="war" depends="copy">
	<echo>Building the war file</echo>
	<war destfile="${dist.dir}/${project.name}.war" webxml="${build.dir}/WEB-INF/web.xml">
		<fileset dir="${build.dir}"/>
	</war>
</target>

This is the final module (target) in my build.xml file which makes the WebApp.war required for the deployment. “war” is an Ant task for which you provide the path of the web.xml file and the directory which contains the deployment structure i.e in our case “build” directory. The destfile is the final location and name of the war file which would become dist\WebApp.war after the script has run.

Running the above script
Keep the build.properties and build.xml files in the ant folder. Make sure that the ANT_HOME environment variable is set to your ant’s installation bin directory. Now, all you have to do is run the ant command on the build file as,

C:\> cd WebAppant\ant
C:\WebAppant\ant> ant

That’s it. If successful your development will finally become a fully packaged WebApp.war.

Final Words
Thus, we have made a complete packaged war file from our source with a single XML file and the wonderful Ant tool which is ready to be deployed in the tomcat manager. We can further dig deeper and make complex build.xml using the complete set of elements that Ant provides. But this tutorial was just to get you started with using Apache Ant. If you have any difficulty in understanding the individual elements please read their detailed explanation in the Apache Ant documentation.

Resources
If you have any problem in making the build.xml or build.properties please download them from here. (Right click and select “Save as ….”)

RSS Feed

Stumble Digg Technorati Subscribe Delicious