1. Move a couple of common methods to an abstract base class.

2. Javadoc


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271594 13f79535-47bb-0310-9956-ffa450edef68

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/BaseFilterReader.java

@@ -0,0 +1,147 @@
+/*
+ *  The Apache Software License, Version 1.1
+ *
+ *  Copyright (c) 2002 The Apache Software Foundation.  All rights
+ *  reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions
+ *  are met:
+ *
+ *  1. Redistributions of source code must retain the above copyright
+ *  notice, this list of conditions and the following disclaimer.
+ *
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *  notice, this list of conditions and the following disclaimer in
+ *  the documentation and/or other materials provided with the
+ *  distribution.
+ *
+ *  3. The end-user documentation included with the redistribution, if
+ *  any, must include the following acknowlegement:
+ *  "This product includes software developed by the
+ *  Apache Software Foundation (http://www.apache.org/)."
+ *  Alternately, this acknowlegement may appear in the software itself,
+ *  if and wherever such third-party acknowlegements normally appear.
+ *
+ *  4. The names "The Jakarta Project", "Ant", and "Apache Software
+ *  Foundation" must not be used to endorse or promote products derived
+ *  from this software without prior written permission. For written
+ *  permission, please contact apache@apache.org.
+ *
+ *  5. Products derived from this software may not be called "Apache"
+ *  nor may "Apache" appear in their names without prior written
+ *  permission of the Apache Group.
+ *
+ *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ *  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ *  DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ *  ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ *  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ *  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ *  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ *  SUCH DAMAGE.
+ *  ====================================================================
+ *
+ *  This software consists of voluntary contributions made by many
+ *  individuals on behalf of the Apache Software Foundation.  For more
+ *  information on the Apache Software Foundation, please see
+ *  <http://www.apache.org/>.
+ */
+package org.apache.tools.ant.filters;
+
+import java.io.FilterReader;
+import java.io.IOException;
+import java.io.Reader;
+import java.io.StringReader;
+
+/**
+ * Base class for core filter readers.
+ *
+ * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
+ */
+public abstract class BaseFilterReader
+    extends FilterReader
+{
+    /**
+     * 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.
+     */
+    public BaseFilterReader() {
+        // Dummy constructor to be invoked by Ant's Introspector
+        super(new StringReader(new String()));
+        try {
+            close();
+        } catch (IOException  ioe) {
+            // Ignore
+        }
+    }
+
+    /**
+     * Create a new filtered reader.
+     *
+     * @param in  a Reader object providing the underlying stream.
+     */
+    public BaseFilterReader(final Reader in) {
+        super(in);
+    }
+
+    /**
+     * Read characters into a portion of an array.  This method will block
+     * until some input is available, an I/O error occurs, or the end of the
+     * stream is reached.
+     *
+     * @param      cbuf  Destination buffer
+     * @param      off   Offset at which to start storing characters
+     * @param      len   Maximum number of characters to read
+     *
+     * @return     The number of characters read, or -1 if the end of the
+     *             stream has been reached
+     *
+     * @exception  IOException  If an I/O error occurs
+     */
+    public final int read(final char cbuf[], final int off,
+                          final int len) throws IOException {
+        for (int i = 0; i < len; i++) {
+            final int ch = read();
+            if (ch == -1) {
+                if (i == 0) {
+                    return -1;
+                } else {
+                    return i;
+                }
+            }
+            cbuf[off + i] = (char) ch;
+        }
+        return len;
+    }
+
+    /**
+     * Skip characters.  This method will block until some characters are
+     * available, an I/O error occurs, or the end of the stream is reached.
+     *
+     * @param  n  The number of characters to skip
+     *
+     * @return    The number of characters actually skipped
+     *
+     * @exception  IllegalArgumentException  If <code>n</code> is negative.
+     * @exception  IOException  If an I/O error occurs
+     */
+    public final long skip(long n) throws IOException {
+        if (n < 0L) {
+            throw new IllegalArgumentException("skip value is negative");
+        }
+
+        for (long i = 0; i < n; i++) {
+            if (in.read() == -1) {
+                return i;
+            }
+        }
+        return n;
+    }
+}

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/HeadFilter.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
@@ -78,19 +76,25 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class HeadFilter
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** Lines key to represent the number of lines to be returned. */
     private static final String LINES_KEY = "lines";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
+    /** Number of lines currently read in. */
     private long linesRead = 0;
 
+    /** Default number of lines returned. */
     private long lines = 10;
 
+    /** If the next character being read is a linefeed, must it be ignored? */
     private boolean ignoreLineFeed = false;
 
     /**
@@ -100,13 +104,7 @@ public final class HeadFilter
      * that is created making it useless for further operations.
      */
     public HeadFilter() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -118,6 +116,9 @@ public final class HeadFilter
         super(in);
     }
 
+    /**
+     * Read the first n lines.
+     */
     public final int read() throws IOException {
         if (!getInitialized()) {
             initialize();
@@ -151,47 +152,38 @@ public final class HeadFilter
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set number of lines to be returned.
+     */
     public final void setLines(final long lines) {
         this.lines = lines;
     }
 
+    /**
+     * Get number of lines to be returned.
+     */
     private final long getLines() {
         return lines;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new HeadFilter using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         HeadFilter newFilter = new HeadFilter(rdr);
         newFilter.setLines(getLines());
@@ -207,6 +199,9 @@ public final class HeadFilter
         setInitialized(false);
     }
 
+    /**
+     * Scan for the lines parameter.
+     */
     private final void initialize() {
         if (parameters != null) {
             for (int i = 0; i < parameters.length; i++) {

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/LineContains.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 import java.util.Vector;
 
 import org.apache.tools.ant.types.Parameter;
@@ -86,17 +84,22 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class LineContains
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** contains key */
     private static final String CONTAINS_KEY = "contains";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
+    /** Vector that holds the strings that input lines must contain. */
     private Vector contains = new Vector();
 
+    /** Currently read in line. */
     private String line = null;
 
     /**
@@ -106,13 +109,7 @@ public final class LineContains
      * that is created making it useless for further operations.
      */
     public LineContains() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -124,6 +121,10 @@ public final class LineContains
         super(in);
     }
 
+    /**
+     * Choose only those lines that contains
+     * user defined values.
+     */
     public final int read() throws IOException {
         if (!initialized) {
             initialize();
@@ -169,49 +170,45 @@ public final class LineContains
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(final long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) return i;
-        }
-        return n;
-    }
-
+    /**
+     * Add a contains element.
+     */
     public final void addConfiguredContains(final Contains contains) {
         this.contains.addElement(contains.getValue());
     }
 
+    /**
+     * Set contains vector.
+     */
     private void setContains(final Vector contains) {
         this.contains = contains;
     }
 
+    /**
+     * Get contains vector.
+     */
     private final Vector getContains() {
         return contains;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new LineContains using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         LineContains newFilter = new LineContains(rdr);
         newFilter.setContains(getContains());
@@ -227,6 +224,9 @@ public final class LineContains
         initialized = false;
     }
 
+    /**
+     * Parse params to add user defined contains strings.
+     */
     private final void initialize() {
         if (parameters != null) {
             for (int i = 0; i < parameters.length; i++) {
@@ -237,13 +237,24 @@ public final class LineContains
         }
     }
 
+    /**
+     * Holds a contains element
+     */
     public static class Contains {
+
+        /** User defined contains string */
         private String value;
 
+        /**
+         * Set the contains string
+         */
         public final void setValue(String contains) {
             value = contains;
         }
 
+        /**
+         * Get the contains string
+         */
         public final String getValue() {
             return value;
         }

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/PrefixLines.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
@@ -78,20 +76,22 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class PrefixLines
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
-    /**
-     * prefix key
-     */
+    /** prefix key */
     private static final String PREFIX_KEY = "prefix";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
+    /** The prefix to be used. */
     private String prefix = null;
 
+    /** Data that must be read from, if not null. */
     private String queuedData = null;
 
     /**
@@ -101,13 +101,7 @@ public final class PrefixLines
      * that is created making it useless for further operations.
      */
     public PrefixLines() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -119,6 +113,9 @@ public final class PrefixLines
         super(in);
     }
 
+    /**
+     * Prefix lines with user defined prefix.
+     */
     public final int read() throws IOException {
         if (!getInitialized()) {
             initialize();
@@ -160,47 +157,38 @@ public final class PrefixLines
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set the prefix
+     */
     public final void setPrefix(final String prefix) {
         this.prefix = prefix;
     }
 
+    /**
+     * Get the prefix
+     */
     private final String getPrefix() {
         return prefix;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new PrefixLines using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         PrefixLines newFilter = new PrefixLines(rdr);
         newFilter.setPrefix(getPrefix());
@@ -216,6 +204,9 @@ public final class PrefixLines
         setInitialized(false);
     }
 
+    /**
+     * Initialize prefix if available from the param element.
+     */
     private final void initialize() {
         if (parameters != null) {
             for (int i = 0; i < parameters.length; i++) {

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/ReplaceTokens.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 import java.util.Hashtable;
 
 import org.apache.tools.ant.types.Parameter;
@@ -83,23 +81,31 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class ReplaceTokens
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** Default begin token character. */
     private static final char DEFAULT_BEGIN_TOKEN = '@';
 
+    /** Default end token character. */
     private static final char DEFAULT_END_TOKEN = '@';
 
+    /** Data that must be read from, if not null. */
     private String queuedData = null;
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Hashtable to hold the replacee-replacer pairs. */
     private Hashtable hash = new Hashtable();
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized;
 
+    /** Begin token. */
     private char beginToken = DEFAULT_BEGIN_TOKEN;
 
+    /** End token. */
     private char endToken = DEFAULT_END_TOKEN;
 
     /**
@@ -109,13 +115,7 @@ public final class ReplaceTokens
      * that is created making it useless for further operations.
      */
     public ReplaceTokens() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -176,67 +176,73 @@ public final class ReplaceTokens
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set begin token.
+     */
     public final void setBeginToken(final char beginToken) {
         this.beginToken = beginToken;
     }
 
+    /**
+     * Get begin token.
+     */
     private final char getBeginToken() {
         return beginToken;
     }
 
+    /**
+     * Set end token.
+     */
     public final void setEndToken(final char endToken) {
         this.endToken = endToken;
     }
 
+    /**
+     * Get begin token.
+     */
     private final char getEndToken() {
         return endToken;
     }
 
+    /**
+     * Add a token element.
+     */
     public final void addConfiguredToken(final Token token) {
         hash.put(token.getKey(), token.getValue());
     }
 
+    /**
+     * Set the tokens.
+     */
     private void setTokens(final Hashtable hash) {
         this.hash = hash;
     }
 
+    /**
+     * Get the tokens.
+     */
     private final Hashtable getTokens() {
         return hash;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new ReplaceTokens using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         ReplaceTokens newFilter = new ReplaceTokens(rdr);
         newFilter.setBeginToken(getBeginToken());
@@ -279,23 +285,41 @@ public final class ReplaceTokens
         }
     }
 
+    /**
+     * Holds a token
+     */
     public static class Token {
+
+        /** token key */
         private String key;
 
+        /** token value */
         private String value;
 
+        /**
+         * Set the token key
+         */
         public final void setKey(String key) {
             this.key = key;
         }
 
+        /**
+         * Set the token value
+         */
         public final void setValue(String value) {
             this.value = value;
         }
 
+        /**
+         * Get the token key
+         */
         public final String getKey() {
             return key;
         }
 
+        /**
+         * Get the token value
+         */
         public final String getValue() {
             return value;
         }

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/StripJavaComments.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 /**
  * This is a java comment and string stripper reader that filters
@@ -66,7 +64,7 @@ import java.io.StringReader;
  * you are reccomended to make it work on top of a buffered reader.
  */
 public final class StripJavaComments
-    extends FilterReader
+    extends BaseFilterReader
     implements ChainableReader
 {
     /**
@@ -76,13 +74,7 @@ public final class StripJavaComments
      * that is created making it useless for further operations.
      */
     public StripJavaComments() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -94,6 +86,9 @@ public final class StripJavaComments
         super(in);
     }
 
+    /**
+     * Filter out Java Style comments
+     */
     public final int read() throws IOException {
         int ch = in.read();
         if (ch == '/') {
@@ -144,29 +139,10 @@ public final class StripJavaComments
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(final long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) return i;
-        }
-        return n;
-    }
-
+    /**
+     * Create a new StripJavaComments object using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         StripJavaComments newFilter = new StripJavaComments(rdr);
         return newFilter;

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/StripLineBreaks.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
@@ -74,7 +72,7 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class StripLineBreaks
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
     /**
@@ -88,10 +86,13 @@ public final class StripLineBreaks
      */
     private static final String LINE_BREAKS_KEY = "linebreaks";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Holds the characters that are recognized as line breaks. */
     private String lineBreaks = DEFAULT_LINE_BREAKS;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
     /**
@@ -101,13 +102,7 @@ public final class StripLineBreaks
      * that is created making it useless for further operations.
      */
     public StripLineBreaks() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -119,6 +114,11 @@ public final class StripLineBreaks
         super(in);
     }
 
+    /**
+     * If the character that is being read in is a
+     * line break character, ignore it and move on to the
+     * next one.
+     */
     public final int read() throws IOException {
         if (!initialized) {
             initialize();
@@ -136,47 +136,38 @@ public final class StripLineBreaks
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set the line break characters.
+     */
     public final void setLineBreaks(final String lineBreaks) {
         this.lineBreaks = lineBreaks;
     }
 
+    /**
+     * Get the line breaks characters
+     */
     private final String getLineBreaks() {
         return lineBreaks;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new StripLineBreaks object using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         StripLineBreaks newFilter = new StripLineBreaks(rdr);
         newFilter.setLineBreaks(getLineBreaks());
@@ -192,6 +183,9 @@ public final class StripLineBreaks
         setInitialized(false);
     }
 
+    /**
+     * Line break characters set using the param element.
+     */
     private final void initialize() {
         String userDefinedLineBreaks = null;
         if (parameters != null) {

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/StripLineComments.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 import java.util.Vector;
 
 import org.apache.tools.ant.types.Parameter;
@@ -89,17 +87,22 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class StripLineComments
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** The type that param recognizes to set the comments. */
     private static final String COMMENTS_KEY = "comment";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
+    /** Vector that holds comments. */
     private Vector comments = new Vector();
 
+    /** The line that has been read ahead. */
     private String line = null;
 
     /**
@@ -109,13 +112,7 @@ public final class StripLineComments
      * that is created making it useless for further operations.
      */
     public StripLineComments() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -127,6 +124,10 @@ public final class StripLineComments
         super(in);
     }
 
+    /**
+     * Read in line by line; Ignore line if it
+     * begins with a comment string.
+     */
     public final int read() throws IOException {
         if (!getInitialized()) {
             initialize();
@@ -171,49 +172,45 @@ public final class StripLineComments
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(final long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) return i;
-        }
-        return n;
-    }
-
+    /**
+     * Add the Comment element.
+     */
     public final void addConfiguredComment(final Comment comment) {
         comments.addElement(comment.getValue());
     }
 
+    /**
+     * Set the comments vector.
+     */
     private void setComments(final Vector comments) {
         this.comments = comments;
     }
 
+    /**
+     * Get the comments vector.
+     */
     private final Vector getComments() {
         return comments;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new StripLineComments object using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         StripLineComments newFilter = new StripLineComments(rdr);
         newFilter.setComments(getComments());
@@ -229,6 +226,9 @@ public final class StripLineComments
         setInitialized(false);
     }
 
+    /**
+     * Comments set using the param element.
+     */
     private final void initialize() {
         if (parameters != null) {
             for (int i = 0; i < parameters.length; i++) {
@@ -239,13 +239,24 @@ public final class StripLineComments
         }
     }
 
+    /**
+     * The class that holds a comment.
+     */
     public static class Comment {
+
+        /** The comment*/
         private String value;
 
+        /**
+         * Set the comment.
+         */
         public final void setValue(String comment) {
             value = comment;
         }
 
+        /**
+         * Get the comment.
+         */
         public final String getValue() {
             return value;
         }

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/TabsToSpaces.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
@@ -78,19 +76,25 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class TabsToSpaces
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** The default tab length is 8 */
     private static final int DEFAULT_TAB_LENGTH = 8;
 
+    /** The name that param recognizes to set the tablength. */
     private static final String TAB_LENGTH_KEY = "tablength";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized;
 
+    /** Default tab length. */
     private int tabLength = DEFAULT_TAB_LENGTH;
 
+    /** How many more spaces must be returned to replace a tab? */
     private int spacesRemaining = 0;
 
     /**
@@ -100,13 +104,7 @@ public final class TabsToSpaces
      * that is created making it useless for further operations.
      */
     public TabsToSpaces() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -142,47 +140,38 @@ public final class TabsToSpaces
         return ch;
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set the tab length.
+     */
     public final void setTablength(final int tabLength) {
         this.tabLength = tabLength;
     }
 
+    /**
+     * Get the tab length
+     */
     private final int getTablength() {
         return tabLength;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new TabsToSpaces object using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         TabsToSpaces newFilter = new TabsToSpaces(rdr);
         newFilter.setTablength(getTablength());

proposal/sandbox/filterreaders/src/main/org/apache/tools/ant/filters/TailFilter.java

@@ -53,10 +53,8 @@
  */
 package org.apache.tools.ant.filters;
 
-import java.io.FilterReader;
 import java.io.IOException;
 import java.io.Reader;
-import java.io.StringReader;
 
 import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
@@ -78,27 +76,37 @@ import org.apache.tools.ant.types.Parameterizable;
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class TailFilter
-    extends FilterReader
+    extends BaseFilterReader
     implements Parameterizable, ChainableReader
 {
+    /** The name that param recognizes to set the number of lines. */
     private static final String LINES_KEY = "lines";
 
+    /** The passed in parameter array. */
     private Parameter[] parameters;
 
+    /** Have the parameters passed been interpreted? */
     private boolean initialized = false;
 
+    /** Number of lines currently read in. */
     private long linesRead = 0;
 
+    /** Default number of lines returned. */
     private long lines = 10;
 
+    /** If the next character being read is a linefeed, must it be ignored? */
     private boolean ignoreLineFeed = false;
 
+    /** Buffer to hold in characters read ahead. */
     private char[] buffer = new char[4096];
 
+    /** The character position that has been returned from the buffer. */
     private int returnedCharPos = -1;
 
+    /** Has read ahead been completed? */
     private boolean completedReadAhead = false;
 
+    /** Current index position on the buffer. */
     private int bufferPos = 0;
 
     /**
@@ -108,13 +116,7 @@ public final class TailFilter
      * that is created making it useless for further operations.
      */
     public TailFilter() {
-        // Dummy constructor to be invoked by Ant's Introspector
-        super(new StringReader(new String()));
-        try {
-            close();
-        } catch (IOException  ioe) {
-            // Ignore
-        }
+        super();
     }
 
     /**
@@ -196,47 +198,38 @@ public final class TailFilter
         }
     }
 
-    public final int read(final char cbuf[], final int off,
-                          final int len) throws IOException {
-        for (int i = 0; i < len; i++) {
-            final int ch = read();
-            if (ch == -1) {
-                if (i == 0) {
-                    return -1;
-                } else {
-                    return i;
-                }
-            }
-            cbuf[off + i] = (char) ch;
-        }
-        return len;
-    }
-
-    public final long skip(long n) throws IOException {
-        for (long i = 0; i < n; i++) {
-            if (in.read() == -1) {
-                return i;
-            }
-        }
-        return n;
-    }
-
+    /**
+     * Set number of lines to be returned.
+     */
     public final void setLines(final long lines) {
         this.lines = lines;
     }
 
+    /**
+     * Get number of lines to be returned.
+     */
     private final long getLines() {
         return lines;
     }
 
+    /**
+     * Set the initialized status.
+     */
     private final void setInitialized(final boolean initialized) {
         this.initialized = initialized;
     }
 
+    /**
+     * Get the initialized status.
+     */
     private final boolean getInitialized() {
         return initialized;
     }
 
+    /**
+     * Create a new TailFilter using the passed in
+     * Reader for instantiation.
+     */
     public final Reader chain(final Reader rdr) {
         TailFilter newFilter = new TailFilter(rdr);
         newFilter.setLines(getLines());
@@ -252,6 +245,9 @@ public final class TailFilter
         setInitialized(false);
     }
 
+    /**
+     * Scan for the lines parameter.
+     */
     private final void initialize() {
         if (parameters != null) {
             for (int i = 0; i < parameters.length; i++) {