FilterChains and FilterReaders

Look at Unix pipes - they offer you so much flexibility - say you wanted to copy just those lines that contained the string blee from the first 10 lines of a file 'foo' to a file 'bar' - you would do something like

cat foo|head -n10|grep blee > bar

Ant was not flexible enough. There was no way for the <copy> task to do something similar. If you wanted the <copy> task to get the first 10 lines, you would have had to create special attributes:

<copy file="foo" tofile="bar" head="10" contains="blee"/>

The obvious problem thus surfaced: Ant tasks would not be able to accomodate such data transformation attributes as they would be endless. The task would also not know in which order these attributes were to be interpreted. That is, must the task execute the contains attribute first and then the head attribute or vice-versa? What Ant tasks needed was a mechanism to allow pluggable filter (data tranformer) chains. Ant would provide a few filters for which there have been repeated requests. Users with special filtering needs would be able to easily write their own and plug them in.

The solution was to refactor data transformation oriented tasks to support FilterChains. A FilterChain is a group of ordered FilterReaders. Users can define their own FilterReaders by just extending the java.io.FilterReader class. Such custom FilterReaders can be easily plugged in as nested elements of <filterchain> by using <filterreader> elements.

Example:


<copy file="${src.file}" tofile="${dest.file}">

  <filterchain>

    <filterreader classname="your.extension.of.java.io.FilterReader">

      <param name="foo" value="bar"/>

    </filterreader>

    <filterreader classname="another.extension.of.java.io.FilterReader">

      <classpath>

        <pathelement path="${classpath}"/>

      </classpath>

      <param name="blah" value="blee"/>

      <param type="abra" value="cadabra"/>

    </filterreader>

  </filterchain>

</copy>

Ant provides some built-in filter readers. These filter readers can also be declared using a syntax similar to the above syntax. However, they can be declared using some simpler syntax also.

Example:


<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>

    <headfilter lines="15"/>

  </filterchain>

</loadfile>

is equivalent to:


<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">

      <param name="lines" value="15"/>

    </filterreader>

  </filterchain>

</loadfile>

The following built-in tasks support nested <filterchain> elements.
Copy,
LoadFile,
LoadProperties,
Move

A FilterChain is formed by defining zero or more of the following nested elements.
FilterReader
ClassConstants
ExpandProperties
HeadFilter
LineContains
LineContainsRegExp
PrefixLines
ReplaceTokens
StripJavaComments
StripLineBreaks
StripLineComments
TabsToSpaces
TailFilter

FilterReader

The filterreader element is the generic way to define a filter. User defined filter elements are defined in the build file using this. Please note that built in filter readers can also be defined using this syntax. A FilterReader element must be supplied with a class name as an attribute value. The class resolved by this name must extend java.io.FilterReader. If the custom filter reader needs to be parameterized, it must implement org.apache.tools.type.Parameterizable.

Attribute	Description	Required
classname	The class name of the filter reader.	Yes

Nested Elements:

<filterreader> supports <classpath> and <param> as nested elements. Each <param> element may take in the following attributes - name, type and value.

The following FilterReaders are supplied with the default distribution.

ClassConstants

This filters basic constants defined in a Java Class, and outputs them in lines composed of the format name=value

Example:

This loads the basic constants defined in a Java class as Ant properties.


<loadproperties srcfile="foo.class">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/>

  </filterchain>

</loadproperties>

Convenience method:


<loadproperties srcfile="foo.class">

  <filterchain>

    <classconstants/>

  </filterchain>

</loadproperties>

ExpandProperties

If the data contains data that represents Ant properties (of the form ${...}), that is substituted with the property's actual value.

Example:

This results in the property modifiedmessage holding the value "All these moments will be lost in time, like teardrops in the rain"


<echo

  message="All these moments will be lost in time, like teardrops in the ${weather}"

  file="loadfile1.tmp"

  />

<property name="weather" value="rain" />

<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/>

  </filterchain>

</loadfile>

Convenience method:


<echo

  message="All these moments will be lost in time, like teardrops in the ${weather}"

  file="loadfile1.tmp"

  />

<property name="weather" value="rain" />

<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">

  <filterchain>

    <expandproperties/>

  </filterchain>

</loadfile>

HeadFilter

This filter reads the first few lines from the data supplied to it.

Parameter Name	Parameter Value	Required
lines	Number of lines to be read. Defaults to "10"	No

Example:

This stores the first 15 lines of the supplied data in the property ${src.file.head}


<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">

      <param name="lines" value="15"/>

    </filterreader>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>

    <headfilter lines="15"/>

  </filterchain>

</loadfile>

LineContains

This filter includes only those lines that contain all the user-specified strings.

Parameter Type	Parameter Value	Required
contains	Substring to be searched for.	Yes

Example:

This will include only those lines that contain foo and bar.


<filterreader classname="org.apache.tools.ant.filters.LineContains">

  <param type="contains" value="foo"/>

  <param type="contains" value="bar"/>

</filterreader>

Convenience method:


<linecontains>

  <contains value="foo">

  <contains value="bar">

</linecontains>

LineContainsRegExp

Filter which includes only those lines that contain the user-specified regular expression matching strings.

Parameter Type	Parameter Value	Required
regexp	Pattern of the substring to be searched for.	Yes

Example:

This will fetch all those lines that contain the pattern foo


<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">

  <param type="regexp" value="foo*"/>

</filterreader>

Convenience method:


<linecontainsregexp>

  <regexp pattern="foo*">

</linecontainsregexp>

PrefixLines

Attaches a prefix to every line.

Parameter Name	Parameter Value	Required
prefix	Prefix to be attached to lines.	Yes

Example:

This will attach the prefix Foo to all lines.


<filterreader classname="org.apache.tools.ant.filters.PrefixLines">

  <param name="prefix" value="Foo"/>

</filterreader>

Convenience method:


<prefixlines prefix="Foo"/>

ReplaceTokens

This filter reader replaces all strings that are sandwiched between begintoken and endtoken with user defined values.

Parameter Type	Parameter Name	Parameter Value	Required
tokenchar	begintoken	Character marking the beginning of a token. Defaults to @	No
tokenchar	endtoken	Character marking the end of a token. Defaults to @	No
token	User defined String.	User defined search String	Yes

Example:

This replaces occurences of the string @DATE@ in the data with today's date and stores it in the property ${src.file.replaced}


<tstamp/>

<loadfile srcfile="${src.file}" property="${src.file.replaced}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">

      <param type="token" name="DATE" value="${TODAY}"/>

    </filterreader>

  </filterchain>

</loadfile>

Convenience method:


<tstamp/>

<loadfile srcfile="${src.file}" property="${src.file.replaced}">

  <filterchain>

    <replacetokens>

      <token key="DATE" value="${TODAY}"/>

    </replacetokens>

  </filterchain>

</loadfile>

StripJavaComments

This filter reader strips away comments from the data, using Java syntax guidelines. This filter does not take in any parameters.

Example:


<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">

  <filterchain>

    <stripjavacomments/>

  </filterchain>

</loadfile>

StripLineBreaks

This filter reader strips away specific characters from the data supplied to it.

Parameter Name	Parameter Value	Required
linebreaks	Characters that are to be stripped out. Defaults to "\r\n"	No

Examples:

This strips the '\r' and '\n' characters.


<loadfile srcfile="${src.file}" property="${src.file.contents}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${src.file}" property="${src.file.contents}">

  <filterchain>

    <striplinebreaks/>

  </filterchain>

</loadfile>

This treats the '(' and ')' characters as line break characters and strips them.


<loadfile srcfile="${src.file}" property="${src.file.contents}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks">

      <param name="linebreaks" value="()"/>

    </filterreader>

  </filterchain>

</loadfile>

StripLineComments

This filter removes all those lines that begin with strings that represent comments as specified by the user.

Parameter Type	Parameter Value	Required
comment	Strings that identify a line as a comment when they appear at the start of the line.	Yes

Examples:

This removes all lines that begin with #, --, REM, rem and //


<filterreader classname="org.apache.tools.ant.filters.StripLineComments">

  <param type="comment" value="#"/>

  <param type="comment" value="--"/>

  <param type="comment" value="REM "/>

  <param type="comment" value="rem "/>

  <param type="comment" value="//"/>

</filterreader>

Convenience method:


<striplinecomments>

  <comment value="#"/>

  <comment value="--"/>

  <comment value="REM "/>

  <comment value="rem "/>

  <comment value="//"/>

</striplinecomments>

TabsToSpaces

This filter replaces tabs with spaces

Parameter Name	Parameter Value	Required
lines	tablength Defaults to "8"	No

Examples:

This replaces tabs in ${src.file} with spaces.


<loadfile srcfile="${src.file}" property="${src.file.notab}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${src.file}" property="${src.file.notab}">

  <filterchain>

    <tabstospaces/>

  </filterchain>

</loadfile>

TailFilter

This filter reads the last few lines from the data supplied to it.

Parameter Name	Parameter Value	Required
lines	Number of lines to be read. Defaults to "10"	No

Examples:

This stores the last 15 lines of the supplied data in the property ${src.file.tail}


<loadfile srcfile="${src.file}" property="${src.file.tail}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.TailFilter">

      <param name="lines" value="15"/>

    </filterreader>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${src.file}" property="${src.file.tail}">

  <filterchain>

    <tailfilter lines="15"/>

  </filterchain>

</loadfile>

This stores the last 5 lines of the first 15 lines of the supplied data in the property ${src.file.mid}


<loadfile srcfile="${src.file}" property="${src.file.mid}">

  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">

      <param name="lines" value="15"/>

    </filterreader>

    <filterreader classname="org.apache.tools.ant.filters.TailFilter">

      <param name="lines" value="5"/>

    </filterreader>

  </filterchain>

</loadfile>

Convenience method:


<loadfile srcfile="${src.file}" property="${src.file.mid}">

  <filterchain>

    <headfilter lines="15"/>

    <tailfilter lines="5"/>

  </filterchain>

</loadfile>