|
|
|
@@ -0,0 +1,488 @@ |
|
|
|
<!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="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="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> |
Magesh Umasankar