| <!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 |
| <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:<P> |
| <code> |
| <copy file="foo" tofile="bar" head="10" contains="blee"/> |
| </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 |
| <filterchain> by using <filterreader> elements. |
| <P> |
| Example: |
| <BLOCKQUOTE><PRE> |
| <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> |
| </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> |
| <loadfile srcfile="${src.file}" property="${src.file.head}"> |
| <filterchain> |
| <headfilter lines="15"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| is equivalent to: |
| <BLOCKQUOTE><PRE> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| The following built-in tasks support nested <filterchain> 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> |
| <filterreader> supports <classpath> and <param> |
| as nested elements. Each <param> 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> |
| <loadproperties srcfile="foo.class"> |
| <filterchain> |
| <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/> |
| </filterchain> |
| </loadproperties> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadproperties srcfile="foo.class"> |
| <filterchain> |
| <classconstants/> |
| </filterchain> |
| </loadproperties> |
| </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 |
| "All these moments will be lost in time, like teardrops in the rain" |
| <BLOCKQUOTE><PRE> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <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> |
| </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 "10"</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> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.head}"> |
| <filterchain> |
| <headfilter lines="15"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| <H3><a name="linecontains">LineContains</a></H3> |
| |
| This filter includes only those lines that contain all the user-specified |
| strings. |
| |
| <TABLE cellSpacing=0 cellPadding=2 border=1> |
| <TR> |
| <TD vAlign=top><B>Parameter Type</B></TD> |
| <TD vAlign=top><B>Parameter Value</B></TD> |
| <TD vAlign=top align="center"><B>Required</B></TD> |
| </TR> |
| <TR> |
| <TD vAlign=top>contains</TD> |
| <TD vAlign=top align="center">Substring to be searched for.</TD> |
| <TD vAlign=top align="center">Yes</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Example:</H4> |
| |
| This will include only those lines that contain <code>foo</code> and |
| <code>bar</code>. |
| <BLOCKQUOTE><PRE> |
| <filterreader classname="org.apache.tools.ant.filters.LineContains"> |
| <param type="contains" value="foo"/> |
| <param type="contains" value="bar"/> |
| </filterreader> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <linecontains> |
| <contains value="foo"> |
| <contains value="bar"> |
| </linecontains> |
| </PRE></BLOCKQUOTE> |
| |
| <H3><a name="linecontainsregexp">LineContainsRegExp</a></H3> |
| |
| Filter which includes only those lines that contain the user-specified |
| regular expression matching strings. |
| |
| <TABLE cellSpacing=0 cellPadding=2 border=1> |
| <TR> |
| <TD vAlign=top><B>Parameter Type</B></TD> |
| <TD vAlign=top><B>Parameter Value</B></TD> |
| <TD vAlign=top align="center"><B>Required</B></TD> |
| </TR> |
| <TR> |
| <TD vAlign=top>regexp</TD> |
| <TD vAlign=top align="center">Pattern of the substring to be searched for.</TD> |
| <TD vAlign=top align="center">Yes</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Example:</H4> |
| |
| This will fetch all those lines that contain the pattern <code>foo</code> |
| <BLOCKQUOTE><PRE> |
| <filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> |
| <param type="regexp" value="foo*"/> |
| </filterreader> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <linecontainsregexp> |
| <regexp pattern="foo*"> |
| </linecontainsregexp> |
| </PRE></BLOCKQUOTE> |
| |
| <H3><a name="prefixlines">PrefixLines</a></H3> |
| |
| Attaches a prefix to every line. |
| |
| <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>prefix</TD> |
| <TD vAlign=top align="center">Prefix to be attached to lines.</TD> |
| <TD vAlign=top align="center">Yes</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Example:</H4> |
| |
| This will attach the prefix <code>Foo</code> to all lines. |
| <BLOCKQUOTE><PRE> |
| <filterreader classname="org.apache.tools.ant.filters.PrefixLines"> |
| <param name="prefix" value="Foo"/> |
| </filterreader> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <prefixlines prefix="Foo"/> |
| </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> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <tstamp/> |
| <loadfile srcfile="${src.file}" property="${src.file.replaced}"> |
| <filterchain> |
| <replacetokens> |
| <token key="DATE" value="${TODAY}"/> |
| </replacetokens> |
| </filterchain> |
| </loadfile> |
| </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> |
| <loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> |
| <filterchain> |
| <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> |
| <filterchain> |
| <stripjavacomments/> |
| </filterchain> |
| </loadfile> |
| </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 "\r\n"</TD> |
| <TD vAlign=top align="center">No</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Examples:</H4> |
| |
| This strips the '\r' and '\n' characters. |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.contents}"> |
| <filterchain> |
| <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.contents}"> |
| <filterchain> |
| <striplinebreaks/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| This treats the '(' and ')' characters as line break characters and |
| strips them. |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.contents}"> |
| <filterchain> |
| <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"> |
| <param name="linebreaks" value="()"/> |
| </filterreader> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| <H3><a name="striplinecomments">StripLineComments</a></H3> |
| |
| This filter removes all those lines that begin with strings |
| that represent comments as specified by the user. |
| |
| <TABLE cellSpacing=0 cellPadding=2 border=1> |
| <TR> |
| <TD vAlign=top><B>Parameter Type</B></TD> |
| <TD vAlign=top><B>Parameter Value</B></TD> |
| <TD vAlign=top align="center"><B>Required</B></TD> |
| </TR> |
| <TR> |
| <TD vAlign=top>comment</TD> |
| <TD vAlign=top align="center">Strings that identify a line as a comment |
| when they appear at the start of the line.</TD> |
| <TD vAlign=top align="center">Yes</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Examples:</H4> |
| |
| This removes all lines that begin with #, --, REM, rem and // |
| <BLOCKQUOTE><PRE> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <striplinecomments> |
| <comment value="#"/> |
| <comment value="--"/> |
| <comment value="REM "/> |
| <comment value="rem "/> |
| <comment value="//"/> |
| </striplinecomments> |
| </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 "8"</TD> |
| <TD vAlign=top align="center">No</TD> |
| </TR> |
| </TABLE> |
| <P> |
| <H4>Examples:</H4> |
| |
| This replaces tabs in ${src.file} with spaces. |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.notab}"> |
| <filterchain> |
| <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.notab}"> |
| <filterchain> |
| <tabstospaces/> |
| </filterchain> |
| </loadfile> |
| </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 "10"</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> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.tail}"> |
| <filterchain> |
| <tailfilter lines="15"/> |
| </filterchain> |
| </loadfile> |
| </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> |
| <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> |
| </PRE></BLOCKQUOTE> |
| |
| Convenience method: |
| <BLOCKQUOTE><PRE> |
| <loadfile srcfile="${src.file}" property="${src.file.mid}"> |
| <filterchain> |
| <headfilter lines="15"/> |
| <tailfilter lines="5"/> |
| </filterchain> |
| </loadfile> |
| </PRE></BLOCKQUOTE> |
| |
| <HR> |
| |
| <P align=center>Copyright © 2002 Apache Software Foundation. All rights |
| Reserved.</P></BODY></HTML> |