Section 15.5. Building WAR Files with Ant

15.5. Building WAR Files with Ant

Thus far in this book, we have not become too preoccupied with special tools to help you construct Java applications. Partly, this is because it's outside the scope of this text, and partly it reflects a small bias of the authors against getting too entangled with particular development environments. There is, however, one universal tool that should be in the arsenal of every Java developer: the Jakarta Project's Ant. Ant is a project builder for Java, a pure Java application that fills the role that make does for C applications. Ant has many advantages over make when building Java code, not the least of which is that it comes with a wealth of special "targets" (declarative commands) to perform common Java-related operations such as building WAR files. Ant is fast, portable, and easy to install and use. Make it your friend.

We won't cover the usage of Ant in detail here. You can learn more and download it from its home page, http://jakarta.apache.org/ant/ or grab it from the CD-ROM accompanying this book (view CD content online at http://examples.oreilly.com/learnjava3/CD-ROM/). To get you started we give you a sample build file here. The Ant build file supplied with the examples for this chapter will compile the source and build the completed WAR file for you. You can find it with the example source.

15.5.1. A Development-Oriented Directory Layout

At the beginning of this chapter, we described the layout of a WAR, including the standard files and directories that must appear inside the archive. While this file organization is necessary for deployment inside the archive, it may not be the best way to organize your project during development. Maintaining web.xml and libraries inside a directory named WEB-INF under all of your content may be convenient for running the jar command, but it doesn't line up well with how those areas are created or maintained from a development perspective. Fortunately, with a simple Ant build file, we can create our WAR from an arbitrary project layout.

Let's choose a directory structure that is a little more oriented toward project development. For example:

     myapplication     |     |-- src     |-- lib     |-- docs     |-- web.xml 

We place our source-code tree under src, required library JAR files under lib, and our content under docs. We leave web.xml at the top where it's easy to tweak parameters, etc.

Here is a simple Ant build.xml file for constructing a WAR from the new directory structure:

     <project name="myapplication" default="compile" basedir=".">         <property name="war-file" value="${ant.project.name}.war"/>         <property name="src-dir" value="src" />         <property name="build-dir" value="classes" />         <property name="docs-dir" value="docs" />         <property name="webxml-file" value="web.xml" />         <property name="lib-dir" value="lib" />         <target name="compile" depends="">             <mkdir dir="${build-dir}"/>             <javac srcdir="${src-dir}" destdir="${build-dir}"/>         </target>         <target name="war" depends="compile">             <war warfile="${war-file}" webxml="${webxml-file}">                 <classes dir="${build-dir}"/>                 <fileset dir="${docs-dir}"/>                 <lib dir="${lib-dir}"/>             </war>         </target>         <target name="clean">             <delete dir="${build-dir}"/>             <delete file="${war-file}"/>         </target>     </project> 

A build.xml file such as this comes with the source code for the examples from this chapter. You can find it with the examples on the CD accompanying this book. You can use it to compile your code (the default target) simply by running ant, or you can compile and build the WAR by specifying the war target like this:

     % ant war 

Our build.xml file tells Ant to find all the Java files under the src tree that need building and compile them into a "build" directory named classes. Running ant war creates the file myapplication.war, placing all of the docs and the web.xml file in the correct locations. You can clean up everything and remove the generated classes directory and WAR by typing ant clean on the command line.

There is nothing really project-specific in this sample build file except the project name attribute in the first line, which you replace with your application's name. And we reference that name only to specify the name of the WAR to generate. You can customize the names of any of the files or directories for your own layout by changing the Ant <property> declarations. The learningjava.war file example for this chapter comes with a version of this Ant build.xml file. There are also Ant build files supplied with other chapters, to build some of the more complex examples. For example, Chapter 1 includes an Ant build file that automates the use of JAXB to generate Java classes from XML.

15.5.2. Deploying and Redeploying WARs with Ant

With Tomcat Version 5.x you can download a client-side "deployer" package, which provides Ant targets for deploying, redeploying, starting, stopping, and undeploying a web app on a running Tomcat server. The deployer package utilizes the Tomcat manager. Similar Ant tasks exist for other servers, such as WebLogic. Making these tasks part of your Ant build script can save a great deal of time and effort. The deployer package can be found along with the main Tomcat download at http://jakarta.apache.org/tomcat/.