Recipe 4.3 Including Tomcat JAR files in the Build File Classpath

Problem

You want to establish an Ant classpath that includes various Tomcat JAR files.

Solution

Use a path -like structure to define the classpath, then refer to this classpath whenever you need it. Specify the directories where the necessary JAR files are located with an external properties file.

Discussion

Before you can compile a servlet using Ant, you must ensure that the servlet API classes are available on the classpath that the Ant build file is using for compilation. For example, the <Tomcat-installation-directory>/common/lib directory contains servlet.jar , which includes the necessary classes for compiling a servlet. In addition, you might want to include the mail.jar component from the same directory to compile a servlet that uses the JavaMail API. A different directory ” <Tomcat-installation-directory>/common/endorsed ” includes the xmlParserAPIs.jar file, which you might specify on the classpath to use the associated SAX and DOM XML programming classes.

Example 4-3 defines a classpath using a path XML element. A compile-servlet target further down in the XML file then uses the defined classpath to compile a servlet.

Example 4-3. Defining a classpath including Tomcat JAR files

 <project name="Cookbook" default="compile-servlet" basedir=".">   <!-- include compiled-servlet and tomcat-dir properties -->   <property file="global.properties" />  <path id="servlet-classpath">     <fileset dir="${tomcat.dir}/common/lib">         <include name="*.jar" />     </fileset>     <fileset dir="${tomcat.dir}/common/endorsed">         <include name="*.jar" />     </fileset> </path>  <target name="compile-servlet">     <echo message="Compiling the servlet...."/>     <javac srcdir="${src}" destdir="${build}">         <include name="${compiled.servlet}.java" />  <classpath refid="servlet-classpath "/>  </javac> </target> </project>

Using the path element, the classpath can be defined similarly to an instance variable of a Java class, and its value can then be used throughout the build file. The advantage of this approach is that the classpath may be very complex, but it has to be defined only once. Whenever there is a need for a classpath in an Ant file, the classpath element and its refid attribute can be used to pull in the defined classpath. In Example 4-3, the path element is given a unique ID, "servlet-classpath." The developer creates this name to uniquely identify the path-like structure.

Another core type of Ant task is a fileset . fileset s are elements that represent groups of files. The two nested fileset s in the example have dir attributes that specify two directories under the Tomcat installation directory: ./common/lib and ./common/endorsed . These are directories that contain many important Java libraries, such as servlet.jar and mail.jar . A fileset element's nested include element creates a pattern (with the name attribute) that specifies the types of files to include in each fileset . The example includes all files in the specified directories ending in ".jar".

If you wanted to further refine the types of JAR files that are included in a fileset, you could use the fileset 's nested exclude element:

 <fileset dir="${tomcat.dir}/common/lib">      <include name="*.jar" />      <exclude name="commons*.jar"/> </fileset>

The pattern "commons*.jar" excludes all the JAR files from the classpath that begin with the word "commons," followed by zero or more characters and a ".jar" suffix.

The compile.servlet target in Example 4-3 echoes a message to the console, then uses the javac task to compile a servlet.

This code from Example 4-3 makes two properties that are defined in another file available to the Ant build file:

 <property file="global.properties" />

Here is what the global.properties file looks like:

 tomcat.dir=k:/jakarta-tomcat-4.1.12 compiled.servlet=MyTask src=.\src build=.\build

The property compiled.servlet evaluates to the name of the Java source file that is being compiled. The tomcat.dir file is the file path to the Tomcat root directory.

In Example 4-3, the classpath element is nested inside the javac task, as in:

 <javac srcdir="${src}" destdir="${build}">         <include name="${compiled.servlet}.java" />         <classpath refid="servlet-classpath"/> </javac>

The classpath element's refid attribute pulls in the classpath that was defined earlier in the build file (including all the Tomcat JARs in ./common/lib and ./common/endorsed ). The value of the refid attribute is the id of the path element ("servlet-classpath"). In other words, the path element in Example 4-3 represents a classpath; the element's id or name is "servlet-classpath."

If it is necessary to add more classes or JARs to the classpath that you are defining in an Ant file, then add another nested fileset to the path element. Example 4-4 adds all of the contents of the build directory to the classpath defined by Example 4-3 (along with the Tomcat- related JARs) by adding a third nested fileset .

Example 4-4. Nesting three filesets in a path structure

 <path id="servlet-classpath">     <fileset dir="${tomcat.dir}/common/lib">       <include name="*.jar" />     </fileset>     <fileset dir="${tomcat.dir}/common/endorsed">       <include name="*.jar" />     </fileset>  <fileset dir="./build"/>  </path>

An idiom that often appears in path-related patterns is ** , which means zero or more directories. For example, the following fileset tag includes all of the files contained in any nested images folders ( src is a property name pointing to the source directory of this fileset ), no matter how deeply they are nested:

 <fileset dir="${src}">     <include name="**/images/*"/> </fileset>