Reader.java: Merge docs from classpath.

	* java/io/Reader.java: Merge docs from classpath.
	(skip): Synchronize on `lock'.
	* java/io/FileReader.java: Import correct implementation from
	classpath.
	* java/io/StringReader.java: Merge docs from classpath.
	(ready): Throw IOException if stream is closed.

From-SVN: r37143

4 files changed, 299 insertions, 49 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index be1a10a..a1b3d5c 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -2,6 +2,13 @@
 
 	* java/util/BitSet.java: Updated @specnote.
 
+	* java/io/Reader.java: Merge docs from classpath.
+	(skip): Synchronize on `lock'.
+	* java/io/FileReader.java: Import correct implementation from 
+	classpath.
+	* java/io/StringReader.java: Merge docs from classpath.
+	(ready): Throw IOException if stream is closed.
+
 2000-10-29  Bryce McKinlay  <bryce@albatross.co.nz>
 
 	* java/util/AbstractCollection.java (addAll): Use size() instead of
diff --git a/libjava/java/io/FileReader.java b/libjava/java/io/FileReader.java
index c82ce5b..0dbcd0e0 100644
--- a/libjava/java/io/FileReader.java
+++ b/libjava/java/io/FileReader.java
@@ -1,35 +1,82 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* FileReader.java -- Convenience class for reading characters from a file
+   Copyright (C) 1998, 2000 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
  
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
+
+
 package java.io;
 
 /**
- * @author Per Bothner <bothner@cygnus.com>
- * @date April 22, 1998.  
- */
-/* Written using "Java Class Libraries", 2nd edition.
- * Status:  Believed complete and correct.
+ * This class provides a convenient way to set up a <code>Reader</code>
+ * to read from a file.  It opens the specified file for reading and creates
+ * the <code>InputStreamReader</code> to read from the 
+ * resulting <code>FileInputStream</code>.  This class can only be used
+ * to read from files using the default character encoding.  Use
+ * <code>InputStreamReader</code> directly to use a non-default encoding.
+ *
+ * @version 0.0
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
  */
-
 public class FileReader extends InputStreamReader
 {
-  public FileReader(String filename) throws IOException
-  {
-    super(new FileInputStream(filename));
-  }
-
-  public FileReader(File file) throws IOException
+  /**
+   * This method initializes a <code>FileReader</code> instance to read from
+   * the specified <code>File</code> object.
+   *
+   * @param file The <code>File</code> object representing the file to read from
+   *
+   * @exception FileNotFoundException If the file is not found or some other 
+   *            error occurs
+   */
+  public FileReader(File file) throws FileNotFoundException
   {
     super(new FileInputStream(file));
   }
 
+  /**
+   * This method initializes a <code>FileReader</code> instance to read from
+   * this specified <code>FileDescriptor</code> object.
+   *
+   * @param fd The <code>FileDescriptor</code> to read from.
+   */
   public FileReader(FileDescriptor fd)
   {
     super(new FileInputStream(fd));
   }
+
+  /**
+   * This method initializes a <code>FileReader</code> instance to read from
+   * the specified named file.
+   *
+   * @param name The name of the file to read from
+   *
+   * @exception FileNotFoundException If the file is not found or some other 
+   *            error occurs
+   */
+  public FileReader(String name) throws FileNotFoundException
+  {
+    super(new FileInputStream(name));
+  }
 }
diff --git a/libjava/java/io/Reader.java b/libjava/java/io/Reader.java
index c8e8f29..e8329d6 100644
--- a/libjava/java/io/Reader.java
+++ b/libjava/java/io/Reader.java
@@ -1,4 +1,4 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* Copyright (C) 1998, 1999, 2000  Free Software Foundation
 
    This file is part of libgcj.
 
@@ -7,38 +7,115 @@ Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
 details.  */
  
 package java.io;
-
-/**
- * @author Per Bothner <bothner@cygnus.com>
- * @date April 21, 1998.  
- */
+ 
 /* Written using "Java Class Libraries", 2nd edition, plus online
  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  * Status:  Believed complete and correct.
  */
 
+/**
+ * This abstract class forms the base of the hierarchy of classes that read
+ * input as a stream of characters.  It provides a common set of methods for
+ * reading characters from streams.  Subclasses implement and extend these
+ * methods to read characters from a particular input source such as a file
+ * or network connection.
+ *
+ * @author Per Bothner <bothner@cygnus.com>
+ * @date April 21, 1998.  
+ * @author Aaron M. Renn (arenn@urbanophile.com) 
+ */
 public abstract class Reader
 {
+  /**
+   * This is the <code>Object</code> used for synchronizing critical code
+   * sections.  Subclasses should use this variable instead of a 
+   * synchronized method or an explicit synchronization on <code>this</code>
+   */
   protected Object lock;
-
+  
+  /**
+    * Unitializes a <code>Reader</code> that will use the object
+    * itself for synchronization of critical code sections.
+    */
   protected Reader()
   {
     this.lock = this;
   }
 
+  /**
+    * Initializes a <code>Reader</code> that will use the specified
+    * <code>Object</code> for synchronization of critical code sections.
+    *
+    * @param lock The <code>Object</code> to use for synchronization
+    */
   protected Reader(Object lock)
   {
     this.lock = lock;
   }
 
-  abstract public int read(char buf[], int offset, int count)
+  /**
+   * Read chars from a stream and stores them into a caller
+   * supplied buffer.  It starts storing the data at index <code>offset</code> 
+   * into the buffer and attempts to read <code>len</code> chars.  This method 
+   * can return before reading the number of chars requested.  The actual 
+   * number of chars read is returned as an int.  A -1 is returned to indicate 
+   * the end of the stream.
+   * <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method operates by calling the single char <code>read()</code> method
+   * in a loop until the desired number of chars are read.  The read loop
+   * stops short if the end of the stream is encountered or if an IOException
+   * is encountered on any read operation except the first.  If the first
+   * attempt to read a chars fails, the IOException is allowed to propagate
+   * upward.  And subsequent IOException is caught and treated identically
+   * to an end of stream condition.  Subclasses can (and should if possible)
+   * override this method to provide a more efficient implementation.
+   *
+   * @param buf The array into which the chars read should be stored
+   * @param offset The offset into the array to start storing chars
+   * @param len The requested number of chars to read
+   *
+   * @return The actual number of chars read, or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
+  public abstract int read(char buf[], int offset, int count)
     throws IOException;
-
+    
+  /**
+   * Reads chars from a stream and stores them into a caller
+   * supplied buffer.  This method attempts to completely fill the buffer,
+   * but can return before doing so.  The actual number of chars read is
+   * returned as an int.  A -1 is returned to indicate the end of the stream.
+   * <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method operates by calling an overloaded read method like so:
+   * <code>read(buf, 0, buf.length)</code>
+   *
+   * @param buf The buffer into which the chars read will be stored.
+   *
+   * @return The number of chars read or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public int read(char buf[]) throws IOException
   {
     return read(buf, 0, buf.length);
   }
 
+  /**
+   * Reads an char from the input stream and returns it
+   * as an int in the range of 0-65535.  This method also will return -1 if
+   * the end of the stream has been reached.
+   * <p>
+   * This method will block until the char can be read.
+   *
+   * @return The char read or -1 if end of stream
+   *
+   * @exception IOException If an error occurs
+   */
   public int read() throws IOException
   {
     char[] buf = new char[1];
@@ -46,28 +123,102 @@ public abstract class Reader
     return count > 0 ? buf[0] : -1;
   }
 
-  abstract public void close() throws IOException;
+  /**
+   * Closes the stream.  Any futher attempts to read from the
+   * stream may generate an <code>IOException</code>.
+   *
+   * @exception IOException If an error occurs
+   */
+  public abstract void close() throws IOException;
 
+  /**
+   * Returns a boolean that indicates whether the mark/reset
+   * methods are supported in this class.  Those methods can be used to
+   * remember a specific point in the stream and reset the stream to that
+   * point.
+   * <p>
+   * This method always returns <code>false</code> in this class, but
+   * subclasses can override this method to return <code>true</code> if they 
+   * support mark/reset functionality.
+   *
+   * @return <code>true</code> if mark/reset functionality is supported, 
+   *         <code>false</code> otherwise
+   *
+   */
   public boolean markSupported()
   {
     return false;
   }
 
+  /**
+    * Marks a position in the input to which the stream can be
+    * "reset" by calling the <code>reset()</code> method.  The parameter
+    * <code>readlimit</code> is the number of chars that can be read from the 
+    * stream after setting the mark before the mark becomes invalid.  For
+    * example, if <code>mark()</code> is called with a read limit of 10, then 
+    * when 11 chars of data are read from the stream before the 
+    * <code>reset()</code> method is called, then the mark is invalid and the 
+    * stream object instance is not required to remember the mark.
+    *
+    * @param readlimit The number of chars that can be read before the mark 
+    *        becomes invalid
+    *
+    * @exception IOException If an error occurs such as mark not being 
+    *            supported for this class
+    */
   public void mark(int readLimit) throws IOException
   {
     throw new IOException("mark not supported");
   }
 
+  /**
+    * Resets a stream to the point where the <code>mark()</code> 
+    * method was called.  Any chars that were read after the mark point was 
+    * set will be re-read during subsequent reads.
+    * <p>
+    * This method always throws an IOException in this class, but subclasses
+    * can override this method if they provide mark/reset functionality.
+    *
+    * @exception IOException Always thrown for this class
+    */
   public void reset() throws IOException
   {
     throw new IOException("reset not supported");
   }
 
+  /**
+    * Determines whether or not this stream is ready to be
+    * read.  If it returns <code>false</code> the stream may block if a
+    * read is attempted, but it is not guaranteed to do so.
+    * <p>
+    * This method always returns <code>false</code> in this class
+    *
+    * @return <code>true</code> if the stream is ready to be read, <code>false</code> otherwise.
+    *
+    * @exception IOException If an error occurs
+    */
   public boolean ready() throws IOException
   {
     return false;
   }
 
+  /**
+    * Skips the specified number of chars in the stream.  It
+    * returns the actual number of chars skipped, which may be less than the
+    * requested amount.
+    * <p>
+    * This method reads and discards chars into a 256 char array until the
+    * specified number of chars were skipped or until either the end of stream
+    * is reached or a read attempt returns a short count.  Subclasses can
+    * override this method to provide a more efficient implementation where
+    * one exists.
+    *
+    * @param num_chars The requested number of chars to skip
+    *
+    * @return The actual number of chars skipped.
+    *
+    * @exception IOException If an error occurs
+    */
   public long skip(long count) throws IOException
   {
     if (count <= 0)
@@ -75,13 +226,16 @@ public abstract class Reader
     int bsize = count > 1024 ? 1024 : (int) count;
     char[] buffer = new char[bsize];
     long todo = count;
-    while (todo > 0)
-      {
-	int skipped = read(buffer, 0, bsize > todo ? (int) todo : bsize);
-	if (skipped <= 0)
-	  break;
-	todo -= skipped;
-      }
+    synchronized (lock)
+    {
+      while (todo > 0)
+	{
+	  int skipped = read(buffer, 0, bsize > todo ? (int) todo : bsize);
+	  if (skipped <= 0)
+	    break;
+	  todo -= skipped;
+	}
+    }
     return count - todo;
   }
 }
diff --git a/libjava/java/io/StringReader.java b/libjava/java/io/StringReader.java
index 60a9129..66d3732 100644
--- a/libjava/java/io/StringReader.java
+++ b/libjava/java/io/StringReader.java
@@ -1,4 +1,4 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* Copyright (C) 1998, 1999, 2000  Free Software Foundation
 
    This file is part of libgcj.
 
@@ -8,16 +8,26 @@ details.  */
  
 package java.io;
 
-/**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 19, 1998.  
- */
 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  * "The Java Language Specification", ISBN 0-201-63451-1
  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
  * Status:  Believed complete and correct
  */
- 
+
+/**
+ * This class permits a <code>String</code> to be read as a character 
+ * input stream.
+ * <p>
+ * The mark/reset functionality in this class behaves differently than
+ * normal.  If no mark has been set, then calling the <code>reset()</code>
+ * method rewinds the read pointer to the beginning of the <code>String</code>.
+ *
+ * @version 0.0
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @date October 19, 1998.  
+ */
 public class StringReader extends Reader
 {
   /* A String provided by the creator of the stream. */
@@ -32,6 +42,13 @@ public class StringReader extends Reader
   /* The index in buf one greater than the last valid character. */
   private int count;
 
+  /**
+   * Create a new <code>StringReader</code> that will read chars from the 
+   * passed in <code>String</code>.  This stream will read from the beginning to the 
+   * end of the <code>String</code>.
+   *
+   * @param s The <code>String</code> this stream will read from.
+   */
   public StringReader(String buffer)
   {
     super();
@@ -54,7 +71,7 @@ public class StringReader extends Reader
     synchronized (lock)
     {
       if (buf == null)
-        throw new IOException();
+        throw new IOException("Stream closed");
 
       // readAheadLimit is ignored per Java Class Lib. book, p. 1692.
       markedPos = pos;
@@ -71,7 +88,7 @@ public class StringReader extends Reader
     synchronized (lock)
     {
       if (buf == null)
-        throw new IOException();
+        throw new IOException("Stream closed");
 
       if (pos < count)
         return ((int) buf.charAt(pos++)) & 0xFFFF;
@@ -84,7 +101,7 @@ public class StringReader extends Reader
     synchronized (lock)
     {
       if (buf == null)
-        throw new IOException();
+        throw new IOException("Stream closed");
 
       /* Don't need to check pos value, arraycopy will check it. */
       if (off < 0 || len < 0 || off + len > b.length)
@@ -101,31 +118,56 @@ public class StringReader extends Reader
     }
   }
 
-  public boolean ready() // TODO12: throws IOException
+  /**
+   * This method determines if the stream is ready to be read.  This class
+   * is always ready to read and so always returns <code>true</code>, unless
+   * close() has previously been called in which case an IOException is
+   * thrown.
+   *
+   * @return <code>true</code> to indicate that this object is ready to be read.
+   * @exception IOException If the stream is closed.
+   */
+  public boolean ready() throws IOException
   {
-    // TODO12: The JCL specifically says this returns true even if the
-    // reader has been closed, whereas the online 1.2 doc specifically
-    // says to throw an IOException if closed.
+    if (buf == null)
+      throw new IOException("Stream closed");
+
     return true;
   }
 
+  /**
+   * Sets the read position in the stream to the previously
+   * marked position or to 0 (i.e., the beginning of the stream) if the mark
+   * has not already been set.
+   */
   public void reset() throws IOException
   {
     synchronized (lock)
     {
       if (buf == null)
-        throw new IOException();
+        throw new IOException("Stream closed");
 
       pos = markedPos;
     }
   }
 
+  /**
+    * This method attempts to skip the requested number of chars in the
+    * input stream.  It does this by advancing the <code>pos</code> value by 
+    * the specified number of chars.  It this would exceed the length of the
+    * buffer, then only enough chars are skipped to position the stream at
+    * the end of the buffer.  The actual number of chars skipped is returned.
+    *
+    * @param num_chars The requested number of chars to skip
+    *
+    * @return The actual number of chars skipped.
+    */
   public long skip(long n) throws IOException
   {
     synchronized (lock)
     {
       if (buf == null)
-        throw new IOException();
+        throw new IOException("Stream closed");
 
       // Even though the var numChars is a long, in reality it can never
       // be larger than an int since the result of subtracting 2 positive