diff options
| author | Jon Skeet <jskeet@apache.org> | 2002-04-30 10:32:01 +0000 |
|---|---|---|
| committer | Jon Skeet <jskeet@apache.org> | 2002-04-30 10:32:01 +0000 |
| commit | 880c151f68cb961ced780a61780ebf8b941be2dd (patch) | |
| tree | 673617eaa3efc2827d0c69601a7eddb949725763 /src/main/org/apache | |
| parent | 9db5bc1b033edacde2afe2c9ec3fc8e7049690f8 (diff) | |
| download | ant-880c151f68cb961ced780a61780ebf8b941be2dd.tar.gz | |
Fix-up of JavaDocs for filters (and a couple of style fixes too).
git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272615 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/main/org/apache')
16 files changed, 590 insertions, 296 deletions
diff --git a/src/main/org/apache/tools/ant/filters/BaseFilterReader.java b/src/main/org/apache/tools/ant/filters/BaseFilterReader.java index d0965f29c..a5438b251 100644 --- a/src/main/org/apache/tools/ant/filters/BaseFilterReader.java +++ b/src/main/org/apache/tools/ant/filters/BaseFilterReader.java @@ -207,13 +207,14 @@ public abstract class BaseFilterReader protected final String readLine() throws IOException { int ch = in.read(); - if (ch==-1) + if (ch == -1) { return null; + } StringBuffer line = new StringBuffer(); while (ch != -1) { - line.append ((char)ch); + line.append ((char) ch); if (ch == '\n') { break; } diff --git a/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java b/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java index 0917308f5..833fe052a 100644 --- a/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java +++ b/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java @@ -59,7 +59,7 @@ import org.apache.tools.ant.types.Parameter; import org.apache.tools.ant.types.Parameterizable; /** - * Parameterized Base class for core filter readers. + * Parameterized base class for core filter readers. * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ @@ -70,32 +70,41 @@ public abstract class BaseParamFilterReader private Parameter[] parameters; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public BaseParamFilterReader() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public BaseParamFilterReader(final Reader in) { super(in); } /** - * Set Parameters + * Sets the parameters used by this filter, and sets + * the filter to an uninitialized status. + * + * @param parameters The parameters to be used by this filter. + * Should not be <code>null</code>. */ public final void setParameters(final Parameter[] parameters) { this.parameters = parameters; setInitialized(false); } + /** + * Returns the parameters to be used by this filter. + * + * @return the parameters to be used by this filter + */ protected final Parameter[] getParameters() { return parameters; } diff --git a/src/main/org/apache/tools/ant/filters/ChainableReader.java b/src/main/org/apache/tools/ant/filters/ChainableReader.java index 1b2c5ff28..5b5dcda3c 100644 --- a/src/main/org/apache/tools/ant/filters/ChainableReader.java +++ b/src/main/org/apache/tools/ant/filters/ChainableReader.java @@ -56,10 +56,19 @@ package org.apache.tools.ant.filters; import java.io.Reader; /** - * Chains readers. + * Interface indicating that a reader may be chained to another one. * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public interface ChainableReader { + /** + * Returns a reader with the same configuration as this one, + * but filtering input from the specified reader. + * + * @param rdr the reader which the returned reader should be filtering + * + * @return a reader with the same configuration as this one, but + * filtering input from the specified reader + */ public Reader chain(Reader rdr); } diff --git a/src/main/org/apache/tools/ant/filters/ClassConstants.java b/src/main/org/apache/tools/ant/filters/ClassConstants.java index 1292c6c81..f42b25d49 100644 --- a/src/main/org/apache/tools/ant/filters/ClassConstants.java +++ b/src/main/org/apache/tools/ant/filters/ClassConstants.java @@ -60,28 +60,23 @@ import java.lang.reflect.Method; /** - * Assemble the constants declared in a Java class in - * key1=value1(line separator)key2=value2 - * format - * + * Assembles the constants declared in a Java class in + * <code>key1=value1(line separator)key2=value2</code> + * format. + *<p> * Notes: - * ===== - * 1. This filter uses the BCEL external toolkit. - * 2. This assembles only those constants that are not created - * using the syntax new whatever(). - * 3. This assembles constants declared using the basic datatypes - * and String only. - * 4. The access modifiers of the declared constants do not matter. - * - * Example: - * ======= - * - * <classconstants/> - * + * <ol> + * <li>This filter uses the BCEL external toolkit. + * <li>This assembles only those constants that are not created + * using the syntax <code>new whatever()</code> + * <li>This assembles constants declared using the basic datatypes + * and String only.</li> + * <li>The access modifiers of the declared constants do not matter.</li> + *</ol> + * Example:<br> + * <pre><classconstants/></pre> * Or: - * - * <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/> - * + * <pre><filterreader classname="org.apache.tools.ant.filters.ClassConstants"/></pre> * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class ClassConstants @@ -91,30 +86,39 @@ public final class ClassConstants private String queuedData = null; /** Helper Class to be invoked via reflection. */ - private String JAVA_CLASS_HELPER = + private static final String JAVA_CLASS_HELPER = "org.apache.tools.ant.filters.util.JavaClassHelper"; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public ClassConstants() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. The contents of the passed-in reader + * are expected to be the name of the class from which to produce a + * list of constants. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public ClassConstants(final Reader in) { super(in); } /** - * Read and assemble the constants declared in a class file. + * Reads and assembles the constants declared in a class file. + * + * @return the next character in the list of constants, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading, or if the constants for the specified class cannot + * be read (for example due to the class not being found). */ public final int read() throws IOException { @@ -148,7 +152,7 @@ public final class ClassConstants final Object[] args = { bytes }; - // getConstants is a staic method, no need to + // getConstants is a static method, no need to // pass in the object final StringBuffer sb = (StringBuffer) getConstants.invoke(null, args); @@ -174,8 +178,14 @@ public final class ClassConstants } /** - * Create a new ClassConstants using the passed in + * Creates a new ClassConstants using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { ClassConstants newFilter = new ClassConstants(rdr); diff --git a/src/main/org/apache/tools/ant/filters/ExpandProperties.java b/src/main/org/apache/tools/ant/filters/ExpandProperties.java index 00288de22..8f0a7867d 100644 --- a/src/main/org/apache/tools/ant/filters/ExpandProperties.java +++ b/src/main/org/apache/tools/ant/filters/ExpandProperties.java @@ -59,17 +59,13 @@ import java.io.Reader; import org.apache.tools.ant.Project; /** - * Expand Ant properties, if any, in the data. - * - * Example: - * ======= - * - * <expandproperties/> - * + * Expands Ant properties, if any, in the data. + * <p> + * Example:<br> + * <pre><expandproperties/></pre> * Or: - * - * <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/> - * + * <pre><filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/></pre> + * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class ExpandProperties @@ -79,26 +75,35 @@ public final class ExpandProperties private String queuedData = null; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public ExpandProperties() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public ExpandProperties(final Reader in) { super(in); } /** - * Prefix lines with user defined prefix. + * Returns the next character in the filtered stream. The original + * stream is first read in fully, and the Ant properties are expanded. + * The results of this expansion are then queued so they can be read + * character-by-character. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { @@ -128,8 +133,14 @@ public final class ExpandProperties } /** - * Create a new PrefixLines using the passed in + * Creates a new ExpandProperties filter using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { ExpandProperties newFilter = new ExpandProperties(rdr); diff --git a/src/main/org/apache/tools/ant/filters/HeadFilter.java b/src/main/org/apache/tools/ant/filters/HeadFilter.java index 6acb26c63..25e9044c9 100644 --- a/src/main/org/apache/tools/ant/filters/HeadFilter.java +++ b/src/main/org/apache/tools/ant/filters/HeadFilter.java @@ -59,54 +59,60 @@ import java.io.Reader; import org.apache.tools.ant.types.Parameter; /** - * Read the first n lines (Default is first 10 lines) - * + * Reads the first <code>n</code> lines of a stream. + * (Default is first 10 lines.) + * <p> * Example: - * ======= - * - * <headfilter lines="3"/> - * + * <pre><headfilter lines="3"/></pre> * Or: - * - * <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> + * <pre><filterreader classname="org.apache.tools.ant.filters.HeadFilter"> * <param name="lines" value="3"/> - * </filterreader> + * </filterreader></pre> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class HeadFilter extends BaseParamFilterReader implements ChainableReader { - /** Lines key to represent the number of lines to be returned. */ + /** Parameter name for the number of lines to be returned. */ private static final String LINES_KEY = "lines"; /** Number of lines currently read in. */ private long linesRead = 0; - /** Default number of lines returned. */ + /** Number of lines to be returned in the filtered stream. */ private long lines = 10; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public HeadFilter() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public HeadFilter(final Reader in) { super(in); } /** - * Read the first n lines. + * Returns the next character in the filtered stream. If the desired + * number of lines have already been read, the resulting stream is + * effectively at an end. Otherwise, the next character from the + * underlying stream is read and returned. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -129,22 +135,32 @@ public final class HeadFilter } /** - * Set number of lines to be returned. + * Sets the number of lines to be returned in the filtered stream. + * + * @param lines the number of lines to be returned in the filtered stream */ public final void setLines(final long lines) { this.lines = lines; } /** - * Get number of lines to be returned. + * Returns the number of lines to be returned in the filtered stream. + * + * @return the number of lines to be returned in the filtered stream */ private final long getLines() { return lines; } /** - * Create a new HeadFilter using the passed in + * Creates a new HeadFilter using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { HeadFilter newFilter = new HeadFilter(rdr); @@ -154,7 +170,8 @@ public final class HeadFilter } /** - * Scan for the lines parameter. + * Scans the parameters list for the "lines" parameter and uses + * it to set the number of lines to be returned in the filtered stream. */ private final void initialize() { Parameter[] params = getParameters(); diff --git a/src/main/org/apache/tools/ant/filters/LineContains.java b/src/main/org/apache/tools/ant/filters/LineContains.java index 8ad24143f..f4246ca09 100644 --- a/src/main/org/apache/tools/ant/filters/LineContains.java +++ b/src/main/org/apache/tools/ant/filters/LineContains.java @@ -60,62 +60,72 @@ import java.util.Vector; import org.apache.tools.ant.types.Parameter; /** - * Filter Reader to fetch only those lines that contain user specified + * Filter which includes only those lines that contain all the user-specified * strings. * * Example: - * ======= * - * <linecontains> + * <pre><linecontains> * <contains value="foo"> * <contains value="bar"> - * </linecontains> + * </linecontains></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.LineContains"> + * <pre><filterreader classname="org.apache.tools.ant.filters.LineContains"> * <param type="contains" value="foo"/> * <param type="contains" value="bar"/> - * </filterreader> + * </filterreader></pre> * - * This will fetch all those lines that contain foo and bar + * This will include only those lines that contain <code>foo</code> and + * <code>bar</code>. * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class LineContains extends BaseParamFilterReader implements ChainableReader { - /** contains key */ + /** Parameter name for the words to filter on. */ private static final String CONTAINS_KEY = "contains"; /** Vector that holds the strings that input lines must contain. */ private Vector contains = new Vector(); - /** Currently read in line. */ + /** + * Remaining line to be read from this filter, or <code>null</code> if + * the next call to <code>read()</code> should read the original stream + * to find the next matching line. + */ private String line = null; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public LineContains() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public LineContains(final Reader in) { super(in); } /** - * Choose only those lines that contains - * user defined values. + * Returns the next character in the filtered stream, only including + * lines from the original stream which contain all of the specified words. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -154,29 +164,48 @@ public final class LineContains } /** - * Add a contains element. + * Adds a <code>contains</code> element. + * + * @param contains The <code>contains</code> element to add. + * Must not be <code>null</code>. */ public final void addConfiguredContains(final Contains contains) { this.contains.addElement(contains.getValue()); } /** - * Set contains vector. + * Sets the vector of words which must be contained within a line read + * from the original stream in order for it to match this filter. + * + * @param contains A vector of words which must be contained within a line + * in order for it to match in this filter. Must not be <code>null</code>. */ private void setContains(final Vector contains) { this.contains = contains; } /** - * Get contains vector. + * Returns the vector of words which must be contained within a line read + * from the original stream in order for it to match this filter. + * + * @return the vector of words which must be contained within a line read + * from the original stream in order for it to match this filter. The + * returned object is "live" - in other words, changes made to the + * returned object are mirrored in the filter. */ private final Vector getContains() { return contains; } /** - * Create a new LineContains using the passed in + * Creates a new LineContains using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { LineContains newFilter = new LineContains(rdr); @@ -186,7 +215,7 @@ public final class LineContains } /** - * Parse params to add user defined contains strings. + * Parses the parameters to add user-defined contains strings. */ private final void initialize() { Parameter[] params = getParameters(); @@ -208,14 +237,19 @@ public final class LineContains private String value; /** - * Set the contains string + * Sets the contains string + * + * @param contains The contains string to set. + * Must not be <code>null</code>. */ public final void setValue(String contains) { value = contains; } /** - * Get the contains string + * Returns the contains string. + * + * @return the contains string for this element */ public final String getValue() { return value; diff --git a/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java b/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java index 04702b9fd..222beca7f 100644 --- a/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java +++ b/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java @@ -62,60 +62,69 @@ import org.apache.tools.ant.types.RegularExpression; import org.apache.tools.ant.util.regexp.Regexp; /** - * Filter Reader to fetch only those lines that contain user specified + * Filter which includes only those lines that contain the user-specified * regular expression matching strings. * * Example: - * ======= - * - * <linecontainsregexp> + * <pre><linecontainsregexp> * <regexp pattern="foo*"> - * </linecontainsregexp> + * </linecontainsregexp></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> + * <pre><filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> * <param type="regexp" value="foo*"/> - * </filterreader> + * </filterreader></pre> * - * This will fetch all those lines that contain the pattern foo + * This will fetch all those lines that contain the pattern <code>foo</code> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class LineContainsRegExp extends BaseParamFilterReader implements ChainableReader { - /** contains key */ + /** Parameter name for the regular expression to filter on. */ private static final String REGEXP_KEY = "regexp"; - /** Vector that holds the strings that input lines must contain. */ + /** Vector that holds the expressions that input lines must contain. */ private Vector regexps = new Vector(); - /** Currently read in line. */ + /** + * Remaining line to be read from this filter, or <code>null</code> if + * the next call to <code>read()</code> should read the original stream + * to find the next matching line. + */ private String line = null; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public LineContainsRegExp() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public LineContainsRegExp(final Reader in) { super(in); } /** - * Choose only those lines that contains - * user defined values. + * Returns the next character in the filtered stream, only including + * lines from the original stream which match all of the specified + * regular expressions. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -157,29 +166,51 @@ public final class LineContainsRegExp } /** - * Add a contains element. + * Adds a <code>regexp</code> element. + * + * @param regExp The <code>regexp</code> element to add. + * Must not be <code>null</code>. */ public final void addConfiguredRegexp(final RegularExpression regExp) { this.regexps.addElement(regExp); } /** - * Set regexps vector. + * Sets the vector of regular expressions which must be contained within + * a line read from the original stream in order for it to match this + * filter. + * + * @param regexps A vector of regular expressions which must be contained + * within a line in order for it to match in this filter. Must not be + * <code>null</code>. */ private void setRegexps(final Vector regexps) { this.regexps = regexps; } /** - * Get regexps vector. + * Returns the vector of regular expressions which must be contained within + * a line read from the original stream in order for it to match this + * filter. + * + * @return the vector of regular expressions which must be contained within + * a line read from the original stream in order for it to match this + * filter. The returned object is "live" - in other words, changes made to + * the returned object are mirrored in the filter. */ private final Vector getRegexps() { return regexps; } /** - * Create a new LineContainsRegExp using the passed in + * Creates a new LineContainsRegExp using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { LineContainsRegExp newFilter = new LineContainsRegExp(rdr); @@ -189,7 +220,7 @@ public final class LineContainsRegExp } /** - * Parse params to add user defined contains strings. + * Parses parameters to add user defined regular expressions. */ private final void initialize() { Parameter[] params = getParameters(); diff --git a/src/main/org/apache/tools/ant/filters/PrefixLines.java b/src/main/org/apache/tools/ant/filters/PrefixLines.java index a985d6dda..1886f5af0 100644 --- a/src/main/org/apache/tools/ant/filters/PrefixLines.java +++ b/src/main/org/apache/tools/ant/filters/PrefixLines.java @@ -59,25 +59,23 @@ import java.io.Reader; import org.apache.tools.ant.types.Parameter; /** - * Attach a prefix to every line + * Attaches a prefix to every line. * * Example: - * ======= - * - * <prefixlines prefix="Foo"/> + * <pre><prefixlines prefix="Foo"/></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.PrefixLines"> - * <param name="prefix" value="Foo"/> - * </filterreader> + * <pre><filterreader classname="org.apache.tools.ant.filters.PrefixLines"> + * <param name="prefix" value="Foo"/> + * </filterreader></pre> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class PrefixLines extends BaseParamFilterReader implements ChainableReader { - /** prefix key */ + /** Parameter name for the prefix. */ private static final String PREFIX_KEY = "prefix"; /** The prefix to be used. */ @@ -87,26 +85,35 @@ public final class PrefixLines private String queuedData = null; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public PrefixLines() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public PrefixLines(final Reader in) { super(in); } /** - * Prefix lines with user defined prefix. + * Returns the next character in the filtered stream. One line is read + * from the original input, and the prefix added. The resulting + * line is then used until it ends, at which point the next original line + * is read, etc. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -141,22 +148,34 @@ public final class PrefixLines } /** - * Set the prefix + * Sets the prefix to add at the start of each input line. + * + * @param prefix The prefix to add at the start of each input line. + * May be <code>null</code>, in which case no prefix + * is added. */ public final void setPrefix(final String prefix) { this.prefix = prefix; } /** - * Get the prefix + * Returns the prefix which will be added at the start of each input line. + * + * @return the prefix which will be added at the start of each input line */ private final String getPrefix() { return prefix; } /** - * Create a new PrefixLines using the passed in + * Creates a new PrefixLines filter using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { PrefixLines newFilter = new PrefixLines(rdr); @@ -166,7 +185,7 @@ public final class PrefixLines } /** - * Initialize prefix if available from the param element. + * Initializes the prefix if it is available from the parameters. */ private final void initialize() { Parameter[] params = getParameters(); diff --git a/src/main/org/apache/tools/ant/filters/ReplaceTokens.java b/src/main/org/apache/tools/ant/filters/ReplaceTokens.java index 40e0fd853..19aa14d36 100644 --- a/src/main/org/apache/tools/ant/filters/ReplaceTokens.java +++ b/src/main/org/apache/tools/ant/filters/ReplaceTokens.java @@ -60,67 +60,73 @@ import java.util.Hashtable; import org.apache.tools.ant.types.Parameter; /** - * Replace tokens with user supplied values + * Replaces tokens in the original input with user-supplied values * - * Example Usage: - * ============= + * Example: * - * <replacetokens begintoken="#" endtoken="#"> + * <pre><replacetokens begintoken="#" endtoken="#"> * <token key="DATE" value="${TODAY}"/> - * </replacetokens> + * </replacetokens></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"> - * <param type="tokenchar" name="begintoken" value="#"/> - * <param type="tokenchar" name="endtoken" value="#"/> - * <param type="token" name="DATE" value="${TODAY}"/> - * </filterreader> + * <pre><filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"> + * <param type="tokenchar" name="begintoken" value="#"/> + * <param type="tokenchar" name="endtoken" value="#"/> + * <param type="token" name="DATE" value="${TODAY}"/> + * </filterreader></pre> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class ReplaceTokens extends BaseParamFilterReader implements ChainableReader { - /** Default begin token character. */ + /** Default "begin token" character. */ private static final char DEFAULT_BEGIN_TOKEN = '@'; - /** Default end token character. */ + /** Default "end token" character. */ private static final char DEFAULT_END_TOKEN = '@'; /** Data that must be read from, if not null. */ private String queuedData = null; - /** Hashtable to hold the replacee-replacer pairs. */ + /** Hashtable to hold the replacee-replacer pairs (String to String). */ private Hashtable hash = new Hashtable(); - /** Begin token. */ + /** Character marking the beginning of a token. */ private char beginToken = DEFAULT_BEGIN_TOKEN; - /** End token. */ + /** Character marking the end of a token. */ private char endToken = DEFAULT_END_TOKEN; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public ReplaceTokens() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public ReplaceTokens(final Reader in) { super(in); } /** - * Replace tokens with values. + * Returns the next character in the filtered stream, replacing tokens + * from the original stream. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -169,57 +175,80 @@ public final class ReplaceTokens } /** - * Set begin token. + * Sets the "begin token" character. + * + * @param beginToken the character used to denote the beginning of a token */ public final void setBeginToken(final char beginToken) { this.beginToken = beginToken; } /** - * Get begin token. + * Returns the "begin token" character. + * + * @return the character used to denote the beginning of a token */ private final char getBeginToken() { return beginToken; } /** - * Set end token. + * Sets the "end token" character. + * + * @param endToken the character used to denote the end of a token */ public final void setEndToken(final char endToken) { this.endToken = endToken; } /** - * Get begin token. + * Returns the "end token" character. + * + * @return the character used to denote the end of a token */ private final char getEndToken() { return endToken; } /** - * Add a token element. + * Adds a token element to the map of tokens to replace. + * + * @param token The token to add to the map of replacements. + * Must not be <code>null</code>. */ public final void addConfiguredToken(final Token token) { hash.put(token.getKey(), token.getValue()); } /** - * Set the tokens. + * Sets the map of tokens to replace. + * + * @param hash A map (String->String) of token keys to replacement + * values. Must not be <code>null</code>. */ private void setTokens(final Hashtable hash) { this.hash = hash; } /** - * Get the tokens. + * Returns the map of tokens which will be replaced. + * + * @return a map (String->String) of token keys to replacement + * values */ private final Hashtable getTokens() { return hash; } /** - * Create a new ReplaceTokens using the passed in + * Creates a new ReplaceTokens using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { ReplaceTokens newFilter = new ReplaceTokens(rdr); @@ -231,7 +260,7 @@ public final class ReplaceTokens } /** - * Initialize tokens and load the replacee-replacer hashtable. + * Initializes tokens and loads the replacee-replacer hashtable. */ private final void initialize() { Parameter[] params = getParameters(); @@ -261,35 +290,43 @@ public final class ReplaceTokens */ public static class Token { - /** token key */ + /** Token key */ private String key; - /** token value */ + /** Token value */ private String value; /** - * Set the token key + * Sets the token key + * + * @param key The key for this token. Must not be <code>null</code>. */ public final void setKey(String key) { this.key = key; } /** - * Set the token value + * Sets the token value + * + * @param value The value for this token. Must not be <code>null</code>. */ public final void setValue(String value) { this.value = value; } /** - * Get the token key + * Returns the key for this token. + * + * @return the key for this token */ public final String getKey() { return key; } /** - * Get the token value + * Returns the value for this token. + * + * @return the value for this token */ public final String getValue() { return value; diff --git a/src/main/org/apache/tools/ant/filters/StringInputStream.java b/src/main/org/apache/tools/ant/filters/StringInputStream.java index 2ddb561a5..5eb3e4e0d 100644 --- a/src/main/org/apache/tools/ant/filters/StringInputStream.java +++ b/src/main/org/apache/tools/ant/filters/StringInputStream.java @@ -58,38 +58,53 @@ import java.io.InputStream; import java.io.StringReader; /** - * Wrap a String as an InputStream + * Wraps a String as an InputStream. Note that data will be lost for + * characters not in ISO Latin 1, as a simple char->byte mapping is assumed. * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public class StringInputStream extends InputStream { - /** Source string is stored as a StringReader */ + /** Source string, stored as a StringReader */ private StringReader in; /** - * Compose a stream from a String + * Composes a stream from a String + * + * @param source The string to read from. Must not be <code>null</code>. */ public StringInputStream(String source) { in = new StringReader(source); } /** - * Read from the Stringreader + * Reads from the Stringreader, returning the same value. Note that + * data will be lost for characters not in ISO Latin 1. Clients + * assuming a return value in the range -1 to 255 may even fail on + * such input. + * + * @return the value of the next character in the StringReader + * + * @exception IOException if the original StringReader fails to be read */ public int read() throws IOException { return in.read(); } /** - * Close the Stringreader + * Closes the Stringreader. + * + * @exception IOException if the original StringReader fails to be closed */ public void close() throws IOException { in.close(); } /** - * Mark the read limit of the StringReader + * Marks the read limit of the StringReader. + * + * @param limit the maximum limit of bytes that can be read before the + * mark position becomes invalid */ public synchronized void mark(final int limit) { try { @@ -100,7 +115,9 @@ public class StringInputStream } /** - * Reset the StringReader. + * Resets the StringReader. + * + * @exception IOException if the StringReader fails to be reset */ public synchronized void reset() throws IOException { in.reset(); diff --git a/src/main/org/apache/tools/ant/filters/StripJavaComments.java b/src/main/org/apache/tools/ant/filters/StripJavaComments.java index 4dc623f60..3dbe46efc 100644 --- a/src/main/org/apache/tools/ant/filters/StripJavaComments.java +++ b/src/main/org/apache/tools/ant/filters/StripJavaComments.java @@ -57,8 +57,8 @@ import java.io.IOException; import java.io.Reader; /** - * This is a java comment and string stripper reader that filters - * these lexical tokens out for purposes of simple Java parsing. + * This is a Java comment and string stripper reader that filters + * those lexical tokens out for purposes of simple Java parsing. * (if you have more complex Java parsing needs, use a real lexer). * Since this class heavily relies on the single char read function, * you are reccomended to make it work on top of a buffered reader. @@ -66,31 +66,47 @@ import java.io.Reader; public final class StripJavaComments extends BaseFilterReader implements ChainableReader { + + /** + * The read-ahead character, used for effectively pushing a single + * character back. -1 indicates that no character is in the buffer. + */ private int readAheadCh = -1; + /** + * Whether or not the parser is currently in the middle of a string + * literal. + */ private boolean inString = false; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public StripJavaComments() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public StripJavaComments(final Reader in) { super(in); } /** - * Filter out Java Style comments + * Returns the next character in the filtered stream, not including + * Java comments. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { int ch = -1; @@ -137,9 +153,16 @@ public final class StripJavaComments } /** - * Create a new StripJavaComments object using the passed in + * Creates a new StripJavaComments using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ + public final Reader chain(final Reader rdr) { StripJavaComments newFilter = new StripJavaComments(rdr); return newFilter; diff --git a/src/main/org/apache/tools/ant/filters/StripLineBreaks.java b/src/main/org/apache/tools/ant/filters/StripLineBreaks.java index c19466a91..0b1be719c 100644 --- a/src/main/org/apache/tools/ant/filters/StripLineBreaks.java +++ b/src/main/org/apache/tools/ant/filters/StripLineBreaks.java @@ -60,12 +60,14 @@ import org.apache.tools.ant.types.Parameter; /** * Filter to flatten the stream to a single line. + * + * Example: * - * <striplinebreaks/> + * <pre><striplinebreaks/></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/> + * <pre><filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/></pre> * * @author Steve Loughran * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> @@ -74,43 +76,45 @@ public final class StripLineBreaks extends BaseParamFilterReader implements ChainableReader { /** - * Linebreaks. What do to on funny IBM mainframes with odd line endings? + * Line-breaking characters. + * What should we do on funny IBM mainframes with odd line endings? */ private static final String DEFAULT_LINE_BREAKS = "\r\n"; - /** - * Linebreaks key that can be set via param element of - * AntFilterReader - */ + /** Parameter name for the line-breaking characters parameter. */ private static final String LINE_BREAKS_KEY = "linebreaks"; - - /** Holds the characters that are recognized as line breaks. */ + /** The characters that are recognized as line breaks. */ private String lineBreaks = DEFAULT_LINE_BREAKS; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public StripLineBreaks() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public StripLineBreaks(final Reader in) { super(in); } /** - * If the character that is being read in is a - * line break character, ignore it and move on to the - * next one. + * Returns the next character in the filtered stream, only including + * characters not in the set of line-breaking characters. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -130,22 +134,34 @@ public final class StripLineBreaks } /** - * Set the line break characters. + * Sets the line-breaking characters. + * + * @param lineBreaks A String containing all the characters to be + * considered as line-breaking. */ public final void setLineBreaks(final String lineBreaks) { this.lineBreaks = lineBreaks; } /** - * Get the line breaks characters + * Returns the line-breaking characters as a String. + * + * @return a String containing all the characters considered as + * line-breaking */ private final String getLineBreaks() { return lineBreaks; } /** - * Create a new StripLineBreaks object using the passed in + * Creates a new StripLineBreaks using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { StripLineBreaks newFilter = new StripLineBreaks(rdr); @@ -155,7 +171,7 @@ public final class StripLineBreaks } /** - * Line break characters set using the param element. + * Parses the parameters to set the line-breaking characters. */ private final void initialize() { String userDefinedLineBreaks = null; diff --git a/src/main/org/apache/tools/ant/filters/StripLineComments.java b/src/main/org/apache/tools/ant/filters/StripLineComments.java index 87d319c01..7a48a89b7 100644 --- a/src/main/org/apache/tools/ant/filters/StripLineComments.java +++ b/src/main/org/apache/tools/ant/filters/StripLineComments.java @@ -60,65 +60,71 @@ import java.util.Vector; import org.apache.tools.ant.types.Parameter; /** - * This is a line comment stripper reader + * This filter strips line comments. * * Example: - * ======= * - * <striplinecomments> + * <pre><striplinecomments> * <comment value="#"/> * <comment value="--"/> * <comment value="REM "/> * <comment value="rem "/> * <comment value="//"/> - * </striplinecomments> + * </striplinecomments></pre> * * Or: * - * <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><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> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class StripLineComments extends BaseParamFilterReader implements ChainableReader { - /** The type that param recognizes to set the comments. */ + /** Parameter name for the comment prefix. */ private static final String COMMENTS_KEY = "comment"; - /** Vector that holds comments. */ + /** Vector that holds the comment prefixes. */ private Vector comments = new Vector(); /** The line that has been read ahead. */ private String line = null; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public StripLineComments() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public StripLineComments(final Reader in) { super(in); } /** - * Read in line by line; Ignore line if it - * begins with a comment string. + * Returns the next character in the filtered stream, only including + * lines from the original stream which don't start with any of the + * specified comment prefixes. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -156,29 +162,43 @@ public final class StripLineComments } /** - * Add the Comment element. + * Adds a <code>comment</code> element to the list of prefixes. + * + * @param comment The <code>comment</code> element to add to the + * list of comment prefixes to strip. Must not be <code>null</code>. */ public final void addConfiguredComment(final Comment comment) { comments.addElement(comment.getValue()); } /** - * Set the comments vector. + * Sets the list of comment prefixes to strip. + * + * @param comments A list of strings, each of which is a prefix + * for a comment line. Must not be <code>null</code>. */ private void setComments(final Vector comments) { this.comments = comments; } /** - * Get the comments vector. + * Returns the list of comment prefixes to strip. + * + * @return the list of comment prefixes to strip. */ private final Vector getComments() { return comments; } /** - * Create a new StripLineComments object using the passed in + * Creates a new StripLineComments using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { StripLineComments newFilter = new StripLineComments(rdr); @@ -188,7 +208,7 @@ public final class StripLineComments } /** - * Comments set using the param element. + * Parses the parameters to set the comment prefixes. */ private final void initialize() { Parameter[] params = getParameters(); @@ -202,22 +222,27 @@ public final class StripLineComments } /** - * The class that holds a comment. + * The class that holds a comment representation. */ public static class Comment { - /** The comment*/ + /** The prefix for a line comment. */ private String value; /** - * Set the comment. + * Sets the prefix for this type of line comment. + * + * @param comment The prefix for a line comment of this type. + * Must not be <code>null</code>. */ public final void setValue(String comment) { value = comment; } /** - * Get the comment. + * Returns the prefix for this type of line comment. + * + * @return the prefix for this type of line comment. */ public final String getValue() { return value; diff --git a/src/main/org/apache/tools/ant/filters/TabsToSpaces.java b/src/main/org/apache/tools/ant/filters/TabsToSpaces.java index 5fe5914a2..efcfc1e7e 100644 --- a/src/main/org/apache/tools/ant/filters/TabsToSpaces.java +++ b/src/main/org/apache/tools/ant/filters/TabsToSpaces.java @@ -61,55 +61,61 @@ import org.apache.tools.ant.types.Parameter; /** * Converts tabs to spaces. * - * Example Usage: - * ============= + * Example: * - * <tabtospaces tablength="8"/> + * <pre><tabtospaces tablength="8"/></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"> - * <param name="tablength" value="8"/> - * </filterreader> + * <pre><filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"> + * <param name="tablength" value="8"/> + * </filterreader></pre> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class TabsToSpaces extends BaseParamFilterReader implements ChainableReader { - /** The default tab length is 8 */ + /** The default tab length. */ private static final int DEFAULT_TAB_LENGTH = 8; - /** The name that param recognizes to set the tablength. */ + /** Parameter name for the length of a tab. */ private static final String TAB_LENGTH_KEY = "tablength"; - /** Default tab length. */ + /** Tab length in this filter. */ private int tabLength = DEFAULT_TAB_LENGTH; - /** How many more spaces must be returned to replace a tab? */ + /** The number of spaces still to be read to represent the last-read tab. */ private int spacesRemaining = 0; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public TabsToSpaces() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public TabsToSpaces(final Reader in) { super(in); } /** - * Convert tabs with spaces + * Returns the next character in the filtered stream, converting tabs + * to the specified number of spaces. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -133,22 +139,32 @@ public final class TabsToSpaces } /** - * Set the tab length. + * Sets the tab length. + * + * @param tabLength the number of spaces to be used when converting a tab. */ public final void setTablength(final int tabLength) { this.tabLength = tabLength; } /** - * Get the tab length + * Returns the tab length. + * + * @return the number of spaces used when converting a tab */ private final int getTablength() { return tabLength; } /** - * Create a new TabsToSpaces object using the passed in + * Creates a new TabsToSpaces using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { TabsToSpaces newFilter = new TabsToSpaces(rdr); @@ -158,7 +174,7 @@ public final class TabsToSpaces } /** - * Initialize tokens + * Parses the parameters to set the tab length. */ private final void initialize() { Parameter[] params = getParameters(); diff --git a/src/main/org/apache/tools/ant/filters/TailFilter.java b/src/main/org/apache/tools/ant/filters/TailFilter.java index 38478f9f6..cabef1c63 100644 --- a/src/main/org/apache/tools/ant/filters/TailFilter.java +++ b/src/main/org/apache/tools/ant/filters/TailFilter.java @@ -59,31 +59,30 @@ import java.io.Reader; import org.apache.tools.ant.types.Parameter; /** - * Read the last n lines. Default is last 10 lines. + * Reads the last <code>n</code> lines of a stream. (Default is last10 lines.) * * Example: - * ======= * - * <tailfilter lines="3"/> + * <pre><tailfilter lines="3"/></pre> * * Or: * - * <filterreader classname="org.apache.tools.ant.filters.TailFilter"> - * <param name="lines" value="3"/> - * </filterreader> + * <pre><filterreader classname="org.apache.tools.ant.filters.TailFilter"> + * <param name="lines" value="3"/> + * </filterreader></pre> * * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a> */ public final class TailFilter extends BaseParamFilterReader implements ChainableReader { - /** The name that param recognizes to set the number of lines. */ + /** Parameter name for the number of lines to be returned. */ private static final String LINES_KEY = "lines"; /** Number of lines currently read in. */ private long linesRead = 0; - /** Default number of lines returned. */ + /** Number of lines to be returned in the filtered stream. */ private long lines = 10; /** Buffer to hold in characters read ahead. */ @@ -92,34 +91,43 @@ public final class TailFilter /** The character position that has been returned from the buffer. */ private int returnedCharPos = -1; - /** Has read ahead been completed? */ + /** Whether or not read-ahead been completed. */ private boolean completedReadAhead = false; /** Current index position on the buffer. */ private int bufferPos = 0; /** - * This constructor is a dummy constructor and is - * not meant to be used by any class other than Ant's - * introspection mechanism. This will close the filter - * that is created making it useless for further operations. + * Constructor for "dummy" instances. + * + * @see BaseFilterReader#BaseFilterReader() */ public TailFilter() { super(); } /** - * Create a new filtered reader. + * Creates a new filtered reader. * - * @param in a Reader object providing the underlying stream. + * @param in A Reader object providing the underlying stream. + * Must not be <code>null</code>. */ public TailFilter(final Reader in) { super(in); } /** - * Read ahead and keep in buffer last n lines only at any given - * point. Grow buffer as needed. + * Returns the next character in the filtered stream. If the read-ahead + * has been completed, the next character in the buffer is returned. + * Otherwise, the stream is read to the end and buffered (with the buffer + * growing as necessary), then the appropriate position in the buffer is + * set to read from. + * + * @return the next character in the resulting stream, or -1 + * if the end of the resulting stream has been reached + * + * @exception IOException if the underlying stream throws an IOException + * during reading */ public final int read() throws IOException { if (!getInitialized()) { @@ -176,22 +184,32 @@ public final class TailFilter } /** - * Set number of lines to be returned. + * Sets the number of lines to be returned in the filtered stream. + * + * @param lines the number of lines to be returned in the filtered stream */ public final void setLines(final long lines) { this.lines = lines; } /** - * Get number of lines to be returned. + * Returns the number of lines to be returned in the filtered stream. + * + * @return the number of lines to be returned in the filtered stream */ private final long getLines() { return lines; } /** - * Create a new TailFilter using the passed in + * Creates a new TailFilter using the passed in * Reader for instantiation. + * + * @param rdr A Reader object providing the underlying stream. + * Must not be <code>null</code>. + * + * @return a new filter based on this configuration, but filtering + * the specified reader */ public final Reader chain(final Reader rdr) { TailFilter newFilter = new TailFilter(rdr); @@ -201,7 +219,8 @@ public final class TailFilter } /** - * Scan for the lines parameter. + * Scans the parameters list for the "lines" parameter and uses + * it to set the number of lines to be returned in the filtered stream. */ private final void initialize() { Parameter[] params = getParameters(); |