<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>
<HEAD>
  <TITLE>FilterChains and FilterReaders</TITLE>
</HEAD>

<BODY>

<H2>FilterChains and FilterReaders</H2>
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<P>
<code>
cat foo|head -n10|grep blee > bar
</code><P>
Ant was not flexible enough.  There was no way for the
&lt;copy&gt; task to do something similar.  If you wanted
the &lt;copy&gt; task to get the first 10 lines, you would have
had to create special attributes:<P>
<code>
&lt;copy file=&quot;foo&quot; tofile=&quot;bar&quot; head=&quot;10&quot; contains=&quot;blee&quot;/&gt;
</code><P>
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.<P>

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
&lt;filterchain&gt; by using &lt;filterreader&gt; elements.
<P>
Example:
<BLOCKQUOTE><PRE>
&lt;copy file=&quot;${src.file}&quot; tofile=&quot;${dest.file}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;your.extension.of.java.io.FilterReader&quot;&gt;
      &lt;param name=&quot;foo&quot; value=&quot;bar&quot;/&gt;
    &lt;/filterreader&gt;
    &lt;filterreader classname=&quot;another.extension.of.java.io.FilterReader&quot;&gt;
      &lt;classpath&gt;
        &lt;pathelement path="${classpath}"/&gt;
      &lt;/classpath&gt;
      &lt;param name=&quot;blah&quot; value=&quot;blee&quot;/&gt;
      &lt;param type=&quot;abra&quot; value=&quot;cadabra&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/copy&gt;
</PRE></BLOCKQUOTE>

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.<P>
Example:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
  &lt;filterchain&gt;
    &lt;headfilter lines=&quot;15&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>
is equivalent to:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
      &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

The following built-in tasks support nested &lt;filterchain&gt; elements.<BR>
<a href="../CoreTasks/copy.html">Copy</a>,<BR>
<a href="../CoreTasks/loadfile.html">LoadFile</a>,<BR>
<a href="../CoreTasks/loadproperties.html">LoadProperties</a>,<BR>
<a href="../CoreTasks/move.html">Move</a><BR><BR>

A FilterChain is formed by defining zero or more of the following
nested elements.<BR>
<a href="#filterreader">FilterReader</a><BR>
<a href="#classconstants">ClassConstants</a><BR>
<a href="#expandproperties">ExpandProperties</a><BR>
<a href="#headfilter">HeadFilter</a><BR>
<a href="#linecontains">LineContains</a><BR>
<a href="#linecontainsregexp">LineContainsRegExp</a><BR>
<a href="#prefixlines">PrefixLines</a><BR>
<a href="#replacetokens">ReplaceTokens</a><BR>
<a href="#stripjavacomments">StripJavaComments</a><BR>
<a href="#striplinebreaks">StripLineBreaks</a><BR>
<a href="#striplinecomments">StripLineComments</a><BR>
<a href="#tabstospaces">TabsToSpaces</a><BR>
<a href="#tailfilter">TailFilter</a><BR>

<H3><a name="filterreader">FilterReader</a></H3>

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.

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Attribute</B></TD>
    <TD vAlign=top><B>Description</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>classname</TD>
    <TD vAlign=top>The class name of the filter reader.</TD>
    <TD vAlign=top align="center">Yes</TD>
  </TR>
</TABLE>

<P>
<H4>Nested Elements:</H4>
&lt;filterreader&gt; supports &lt;classpath&gt; and &lt;param&gt;
as nested elements.  Each &lt;param&gt; element may take in the following
attributes - name, type and value.
<P>
The following FilterReaders are supplied with the default
distribution.

<H3><a name="classconstants">ClassConstants</a></H3>
<P>
This filters basic constants defined in a Java Class,
and outputs them in lines composed of the format name=value
<P>
<H4>Example:</H4>

This loads the basic constants defined in a Java class as Ant properties.
<BLOCKQUOTE><PRE>
&lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ClassConstants&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadproperties&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
  &lt;filterchain&gt;
    &lt;classconstants/&gt;
  &lt;/filterchain&gt;
&lt;/loadproperties&gt;
</PRE></BLOCKQUOTE>

<H3><a name="expandproperties">ExpandProperties</a></H3>
<P>
If the data contains data that represents Ant
properties (of the form ${...}), that is substituted
with the property's actual value.
<P>
<H4>Example:</H4>

This results in the property modifiedmessage holding the value
&quot;All these moments will be lost in time, like teardrops in the rain&quot;
<BLOCKQUOTE><PRE>
&lt;echo
  message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
  file=&quot;loadfile1.tmp&quot;
  /&gt;
&lt;property name=&quot;weather&quot; value=&quot;rain&quot; /&gt;
&lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ExpandProperties&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;echo
  message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
  file=&quot;loadfile1.tmp&quot;
  /&gt;
&lt;property name=&quot;weather&quot; value=&quot;rain&quot; /&gt;
&lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
  &lt;filterchain&gt;
    &lt;expandproperties/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="headfilter">HeadFilter</a></H3>

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

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Parameter Name</B></TD>
    <TD vAlign=top><B>Parameter Value</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>lines</TD>
    <TD vAlign=top align="center">Number of lines to be read.
    Defaults to &quot;10&quot;</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
</TABLE>
<P>
<H4>Example:</H4>

This stores the first 15 lines of the supplied data in the property ${src.file.head}
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
      &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
  &lt;filterchain&gt;
    &lt;headfilter lines=&quot;15&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="replacetokens">ReplaceTokens</a></H3>

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

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Parameter Type</B></TD>
    <TD vAlign=top><B>Parameter Name</B></TD>
    <TD vAlign=top><B>Parameter Value</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>tokenchar</TD>
    <TD vAlign=top>begintoken</TD>
    <TD vAlign=top>Character marking the
    beginning of a token.  Defaults to @</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
  <TR>
    <TD vAlign=top>tokenchar</TD>
    <TD vAlign=top>endtoken</TD>
    <TD vAlign=top>Character marking the
    end of a token.  Defaults to @</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
  <TR>
    <TD vAlign=top>token</TD>
    <TD vAlign=top>User defined String.</TD>
    <TD vAlign=top>User defined search String</TD>
    <TD vAlign=top align="center">Yes</TD>
  </TR>
</TABLE>
<P>

<H4>Example:</H4>

This replaces occurences of the string @DATE@ in the data
with today's date and stores it in the property ${src.file.replaced}
<BLOCKQUOTE><PRE>
&lt;tstamp/&gt;
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ReplaceTokens&quot;&gt;
      &lt;param type=&quot;token&quot; name=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;tstamp/&gt;
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
  &lt;filterchain&gt;
    &lt;replacetokens&gt;
      &lt;token key=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
    &lt;/replacetokens&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="stripjavacomments">StripJavaComments</a></H3>

This filter reader strips away comments from the data,
using Java syntax guidelines.  This filter does not
take in any parameters.
<P>
<H4>Example:</H4>

<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripJavaComments&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
  &lt;filterchain&gt;
    &lt;stripjavacomments/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="striplinebreaks">StripLineBreaks</a></H3>

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

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Parameter Name</B></TD>
    <TD vAlign=top><B>Parameter Value</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>linebreaks</TD>
    <TD vAlign=top align="center">Characters that are to
    be stripped out.  Defaults to &quot;\r\n&quot;</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
</TABLE>
<P>
<H4>Examples:</H4>

This strips the '\r' and '\n' characters.
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
  &lt;filterchain&gt;
    &lt;striplinebreaks/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

This treats the '(' and ')' characters as line break characters and
strips them.
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;&gt;
      &lt;param name=&quot;linebreaks&quot; value=&quot;()&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="tabstospaces">TabsToSpaces</a></H3>

This filter replaces tabs with spaces

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Parameter Name</B></TD>
    <TD vAlign=top><B>Parameter Value</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>lines</TD>
    <TD vAlign=top align="center">tablength
    Defaults to &quot;8&quot;</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
</TABLE>
<P>
<H4>Examples:</H4>

This replaces tabs in ${src.file} with spaces.
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TabsToSpaces&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
  &lt;filterchain&gt;
    &lt;tabstospaces/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<H3><a name="tailfilter">TailFilter</a></H3>

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

<TABLE cellSpacing=0 cellPadding=2 border=1>
  <TR>
    <TD vAlign=top><B>Parameter Name</B></TD>
    <TD vAlign=top><B>Parameter Value</B></TD>
    <TD vAlign=top align="center"><B>Required</B></TD>
  </TR>
  <TR>
    <TD vAlign=top>lines</TD>
    <TD vAlign=top align="center">Number of lines to be read.
    Defaults to &quot;10&quot;</TD>
    <TD vAlign=top align="center">No</TD>
  </TR>
</TABLE>
<P>
<H4>Examples:</H4>

This stores the last 15 lines of the supplied data in the property ${src.file.tail}
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
      &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
  &lt;filterchain&gt;
    &lt;tailfilter lines=&quot;15&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>


This stores the last 5 lines of the first 15 lines of the supplied
data in the property ${src.file.mid}
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
  &lt;filterchain&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
      &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
    &lt;/filterreader&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
      &lt;param name=&quot;lines&quot; value=&quot;5&quot;/&gt;
    &lt;/filterreader&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

Convenience method:
<BLOCKQUOTE><PRE>
&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
  &lt;filterchain&gt;
    &lt;HeadFilter lines=&quot;15&quot;/&gt;
    &lt;TailFilter lines=&quot;5&quot;/&gt;
  &lt;/filterchain&gt;
&lt;/loadfile&gt;
</PRE></BLOCKQUOTE>

<HR>

<P align=center>Copyright &copy; 2002 Apache Software Foundation. All rights
Reserved.</P></BODY></HTML>