Apache Ant - SPLessons

ANT Elements

Chapter 6

SPLessons 5 Steps, 3 Clicks
5 Steps - 3 Clicks

ANT Elements

ANT Elements

shape Introduction

ANT Elements are not similar to the ANT Tasks. These ANT Elements are also called as datatypes. But, they differ from the data types in programming languages.

The following topics will be covered in Apache ANT Elements chapter:

shape Description

PatternSets brings the directories or files together. It has three different wild card characters.

Character Description
? Matching single character.
* Matching zero or more characters
** Matching zero or more characters in directory structure.

The above characters can be grouped together in various ways.

shape Examples

<patterset id=”classes”>
	<include name=”**/*.class”/>
	<exclude name=”**/*Test*.class”/>
</patternet>

The above patternset element is nested. This can be written as below by changing the name to includes or excludes:

<patternset id=”classes” includes=”**/*.class” excludes=”**/*Test*.class”/>

DIRSet

shape Description

DIRSet is the Directory set. It applies various patterns to the directory structure by taking in some directories and removing other directories.

shape Examples

The below example uses the patternset.


<dirset dir="build">
	<patternset id="classes">
		<include name="**/classes"/>
		<exclude name="**/*Test*"/>
	<patternset>
</dirset>

The below example uses include and exclude elements.

<dirset dir="build">
		<include name="**/classes"/>
		<exclude name="**/*Test*"/>
</dirset>

The following example has include and exclude parameters within the element.

<dirset dir="build">
		<includes="**/classes"
		<excludes="**/*Test*"/>
</dirset>

FileSet

shape Description

FileSet is similar to the DIRSet. However, fileset will not select the directories instead it selects the group of files depending on patterns. In the above example, FileSet adds defaultexcludes parameter and is set to yes, the default state. Then the common files like CVS files, backup files and temp files will be excluded.

shape Examples

<fileset dir="build" defaultexcludes="yes">
	<patternset id=”source”>
		<include name="**/*.java" />
		<exclude name="**/*Test*" />
	</patternset>
</fileset>


The below example uses include and exclude elements.


<fileset dir="build" defaultexcludes="yes">
		<include name="**/*.java" />
		<exclude name="**/*Test*" />
</fileset>


The following example has the include and exclude parameters within the FileSet element.

<fileset dir="build" defaultexcludes="yes" includes="**/*.java" excludes="**/*Test*" />

FileList

shape Description

FileList selects specific files using the parameters list in which parameters are separated by comma. FileList does not depend on patterns. To refer the files anywhere, assign ref id attribute. While referring to these files, firstly the directory attribute points to the directory and then the files get located.

shape Examples

<filelist id=”source” dir=”src” files=”SysConfig.java, IConstants.java, Encrypt.java” />

FileMapper

shape Description

FileMapper copies or removes the files and renames the files in a process. Six types of FileMappers are there in ANT.

shape Types

FileMapper Description
identity Target filename is identical to the source filename.
flatten Directory structure is flattened.
merge Target filename is same for all source files.
glob Glob matching used on files.
regexp Regular expression matching used on files.
package Based on Java package of source files.

shape Examples

The below code gives the example for FileMapper’s flatten mapper.

<?xml version="1.0" encoding="UTF-8"?>
<project name="Filemapper flatten example" default="flatten" basedir=".">
    
    <target name="flatten">
        <copy todir="build/flatten">
            <mapper type="flatten" />
            <fileset dir="src">
                <include name="**/*.java" />
            </fileset>
        </copy>
    </target>
    
</project>

When the above is run, the following output appears by copying the java files to the build directory irrespective of the directory structure.

The structure will be as follows.

FileReader

shape Description

Java.io.filterreader is the super class for FilterReader. It reads and filters the data. If a number of FilterReaders are grouped as a chain, it is referred as the FilterChain.

shape Conceptual
figure

shape More Info

There are various types of FilterReaders, they are:

FileReader Description
stripjavacomments Removes comments in .java files
striplinecomments Removes user-defined comments.
striplinebreaks Removes end-of-lines characters.
classconstants Output names/value pairs of constants in class files.
replacetokens Replaces tokens within files.
tabstospaces Replaces tabs with given number of spaces.
headfilter Returns the top given number of lines.
tailfilter Returns the bottom given number of lines.
linecontains Copies only lines containing a given string.
linecontainsregexp Copies only lines matching a regexp.
prefixlines Adds a string to the beginning of every line.
expand properties Expands ANT Properties.

shape Examples

stripjavacomments.xml

<?xml version="1.0" encoding="UTF-8"?>
<project name="Strip java comments" default="strip" basedir=".">
    
    <target name="strip">
        <copy todir="build/stripjava">
            <filterchain>
                <stripjavacomments />
            </filterchain>
            <fileset dir="src">
                <include name="**/*.java" />
            </fileset>
        </copy>
    </target>
    
</project>

DbConnection.java in src directory can be as follows.

/**
* Handles all connections to the database
* @version 1.0
* @Today@
*/
package com.splessons.db;
/** 
*Establishes a connection to the database
*@author splessons
*/
public class DbConnection {
/**
*Establishes a connection to the database
*@author splessons
*/
public void connect() {
}
}

When the stripjavacomments.java is made to run again, the following output appears in the build file by filtering all the comments.

package com.splessons.db;
public class DbConnection {
public void connect() {
}
}

Likewise, remaining filters can be implemented.

Selectors

shape Description

Selectors help in selecting the files based on various factors.

date

File selection done by date selector depends on the modification date. In the below example, java files will be selected and modified after the given date.

<!-- date example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <date datetime="01/01/2014 12:00 AM" when="after"/>
</fileset>

present

Present attribute selects both the versions or only a single version in the below example.

<!-- present example -->
<fileset dir="${v2.src.dir}" includes="**/*.java">
    <present present="srconly" targetdir="${v1.src.dir}"/>
</fileset>

size

Size attributes selects files by taking the size into consideration. In the below example, only files below 1k are selected.

<!-- size example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <size value="1" units="Ki" when="less" />
</fileset>

contains

The selection criteria for contains attribute is the string presence.

<!-- contains example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <contains text="TODO" casesensitive="no"/>
</fileset>

containsregexp

Contains Regular Expression checks for the regular expression.

<!-- containsregexp example -->
<fileset dir="${doc.path}" includes="*.txt">
    <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

depends

The selection criteria for depends is-it selects the files that are modified more recently.

<!-- depend example -->
<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend targetdir="${ant.1.4}/src/main"/>
</fileset>

Selector Containers

shape Description

Selectors can be combined in various ways using and, not, or and none.

and

The below example combines the date and size attributes using the and attribute.

<!-- and example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <and>
        <size value="4" units="Ki" when="more"/>
        <date datetime="01/01/2001 12:00 AM" when="before"/>
    </and>
</fileset>

or

The below example demonstrates or attribute and selects the files depending on the file type. It takes any of the three formats.

<!-- or example -->
<fileset dir="${image.dir}">
    <or>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>

not

Not attribute selects the java files that do not contain text test in them.

<!-- not example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <not>
        <contains text="test"/>
    </not>
</fileset>

none

None in the below example selects only the java files which don’t have equivalent files present in the destination directory.

<!-- none example -->
<fileset dir="${src.dir}" includes="**/*.java">
    <none>
        <present targetdir="${dest.dir}"/>
    </none>
</fileset>

ClassFileSet

shape Description

ClassFileSet root elements defines the root classes and files on which these root classes depends.

shape Examples

<?xml version="1.0" encoding="UTF-8"?>


<jar destfile="tools.jar">
    <fileset refid="reqdClasses"/>
</jar>

<classfileset id="reqdClasses" dir="${classes.dir}">
    <rootfileset dir="${classes.dir}" includes="com/splessons/tools/Util*.class"/>
</classfileset>

Paths

shape Description

Classpaths and paths are important in any programming language. ANT makes setting of paths much more easier by using path types. The path can be defined using ref id when used in other tasks. One can make the nested paths. By doing that, an extra jar file will be added to the first class path.

shape Examples

<?xml version="1.0" encoding="UTF-8"?>

<project name="Paths Example" default="compile" basedir=".">
    
    <target name="init">
        <path id="classpath">
            <pathelement path="{$servlet.dir}/servlet.jar" />
            <pathelement path="{$javamail.dir}/mail.jar" />
            <fileset dir="{$lib.dir}">
                <include name="**/*.jar" />
            </fileset>
        </path>
    </target>
    
    <target name="compile" depends="init">
        <javac srcdir="src" destdir="build">
            <classpath>
                <path refid="classpath" />
                <pathelement path="${xalan.jar}" />
            </classpath>
        </javac>
    </target>
    
</project>

Listeners

shape Description

Listeners are the user defined custom tasks. There are 7 events that take the help of Listeners.

Loggers depend on listeners and extend the capability of listeners. There are 9 types of loggers.

Logger Description
DefaultLogger Prints the target names.
No BannerLogger Prints the information if special loggings.
TimestampedLogger Similar to default logger but adds timestamp with today’s date and time.
BigProjectLogger This has very large build and sub-projects. It prints the boundaries between starting and ending of each project.
SimpleProjectLogger This is same as the BigProjectLogger, which does the same except more in style of no banner logger with less output.
ProfileLogger Same as the big project logger but prints the boundaries for tasks also.
AnsiColorLogger Output color codes is given by this logger.
MailLogger Success and failure messages are automatically sent to email by capturing all logged output.
Log4jListener This sends the output as log4j events.
XmlLogger Output is given in the XML format.

Summary

shape Key Points

  • PatternSets groups files or directories using ?,* or **.
  • ANT Elements DIRSet takes in only the required directories.
  • FileSet makes file grouping based on the patterns.
  • ref id is used by FileList to locate the required file.
  • FileMapper copy/remove and renames the files.
  • FilterReader filters the data.
  • ClassFileSet defines the root classes.
  • Loggers depend on listeners and extend the capability of listeners.