FileWriter.java: Merge with Classpath.

	* java/io/FileWriter.java: Merge with Classpath.
	* java/io/FilterInputStream.java: Ditto.
	(mark): no longer synchronized
	(reset): Likewise
	* java/io/FilterOutputStream.java: Merge with Classpath.
	* java/io/FilterReader.java: Ditto.
	(mark): no longer synchronized
	(reset): Likewise
	* java/io/FilterWriter.java: Merge with Classpath.
	* java/io/Writer.java: Ditto.
	* java/lang/Compiler.java: Ditto.
	* java/lang/Process.java: Ditto.
	* java/lang/Void.java: Ditto.
	* java/net/ContentHandler.java: Ditto.
	* java/net/DatagramPacket.java: Ditto.
	* java/net/MulticastSocket.java: Merge comments with Classpath.

From-SVN: r45930

6 files changed, 1045 insertions, 299 deletions

diff --git a/libjava/java/io/FileWriter.java b/libjava/java/io/FileWriter.java
index 5c49e5f..53e3658 100644
--- a/libjava/java/io/FileWriter.java
+++ b/libjava/java/io/FileWriter.java
@@ -1,44 +1,126 @@
-// FileWriter.java - Character output to a file.
+/* FileWriter.java -- Convenience class for writing to files.
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+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.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-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.
 
-package java.io;
+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. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 25, 1998 
- */
+
+package java.io;
 
 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  * "The Java Language Specification", ISBN 0-201-63451-1
  * Status:  Complete to version 1.1.
  */
 
+/**
+  * This is a convenience class for writing to files.  It creates an
+  * <code>FileOutputStream</code> and initializes an 
+  * <code>OutputStreamWriter</code> to write to it.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public class FileWriter extends OutputStreamWriter
 {
-  public FileWriter (String fileName) throws IOException
-  {
-    super (new FileOutputStream (fileName));
-  }
-
-  public FileWriter (String fileName, boolean append) throws IOException
-  {
-    super (new FileOutputStream (fileName, append));
-  }
-
-  public FileWriter (File file) throws IOException
-  {
-    super (new FileOutputStream (file));
-  }
-
-  public FileWriter (FileDescriptor fd)
-  {
-    super (new FileOutputStream (fd));
-  }
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+ 
+/**
+  * This method initializes a new <code>FileWriter</code> object to write
+  * to the specified <code>File</code> object.
+  *
+  * @param file The <code>File</code> object to write to.
+  *
+  * @param SecurityException If writing to this file is forbidden by the
+  *                          <code>SecurityManager</code>.
+  * @param IOException If any other error occurs
+  */
+public 
+FileWriter(File file) throws SecurityException, IOException
+{
+  super(new FileOutputStream(file));
+}
+
+/*************************************************************************/
+
+/**
+  * This method initializes a new <code>FileWriter</code> object to write
+  * to the specified <code>FileDescriptor</code> object.
+  *
+  * @param fd The <code>FileDescriptor</code> object to write to
+  *
+  * @param SecurityException If writing to this file is forbidden by the
+  *                          <code>SecurityManager</code>.
+  */
+public
+FileWriter(FileDescriptor fd) throws SecurityException
+{
+  super(new FileOutputStream(fd));
+}
+
+/*************************************************************************/
+
+/**
+  * This method intializes a new <code>FileWriter</code> object to write to the
+  * specified named file.
+  *
+  * @param name The name of the file to write to
+  *
+  * @param SecurityException If writing to this file is forbidden by the
+  *                          <code>SecurityManager</code>.
+  * @param IOException If any other error occurs
+  */
+public
+FileWriter(String name) throws IOException
+{
+  super(new FileOutputStream(name));
 }
+
+/*************************************************************************/
+
+/**
+  * This method intializes a new <code>FileWriter</code> object to write to the
+  * specified named file.  This form of the constructor allows the caller
+  * to determin whether data should be written starting at the beginning or
+  * the end of the file.
+  *
+  * @param name The name of the file to write to
+  * @param append <code>true</code> to start adding data at the end of the
+  *               file, <code>false</code> otherwise.
+  *
+  * @param SecurityException If writing to this file is forbidden by the
+  *                          <code>SecurityManager</code>.
+  * @param IOException If any other error occurs
+  */
+public
+FileWriter(String name, boolean append) throws IOException
+{
+  super(new FileOutputStream(name, append));
+}
+
+} // class FileWriter
+
diff --git a/libjava/java/io/FilterInputStream.java b/libjava/java/io/FilterInputStream.java
index 712be92..5b09312 100644
--- a/libjava/java/io/FilterInputStream.java
+++ b/libjava/java/io/FilterInputStream.java
@@ -1,75 +1,237 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* FilterInputStream.java -- Base class for classes that filter input
+   Copyright (C) 1998, 1999, 2001 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 Warren Levy <warrenl@cygnus.com>
- * @date October 8, 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 is the common superclass of all standard classes that filter 
+  * input.  It acts as a layer on top of an underlying <code>InputStream</code>
+  * and simply redirects calls made to it to the subordinate InputStream
+  * instead.  Subclasses of this class perform additional filtering
+  * functions in addition to simply redirecting the call.
+  * <p>
+  * This class is not abstract.  However, since it only redirects calls
+  * to a subordinate <code>InputStream</code> without adding any functionality
+  * on top of it, this class should not be used directly.  Instead, various
+  * subclasses of this class should be used.  This is enforced with a
+  * protected constructor.  Do not try to hack around it.
+  * <p>
+  * When creating a subclass of <code>FilterInputStream</code>, override the
+  * appropriate methods to implement the desired filtering.  However, note
+  * that the <code>read(byte[])</code> method does not need to be overridden
+  * as this class redirects calls to that method to 
+  * <code>read(byte[], int, int)</code> instead of to the subordinate
+  * <code>InputStream read(byte[])</code> method.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Warren Levy <warrenl@cygnus.com>
+  */
 public class FilterInputStream extends InputStream
 {
-  /* The input stream to be filtered. */
-  protected InputStream in;
-
-  protected FilterInputStream(InputStream in)
-  {
-    this.in = in; 
-  }
-
-  public int available() throws IOException
-  {
-    return in.available();
-  }
-
-  public void close() throws IOException
-  {
-    in.close();
-  }
-
-  public synchronized void mark(int readlimit)
-  {
-    in.mark(readlimit);
-  }
-
-  public boolean markSupported()
-  {
-    return in.markSupported();
-  }
-
-  public int read() throws IOException
-  {
-    return in.read();
-  }
-
-  public int read(byte[] b) throws IOException
-  {
-    return read(b, 0, b.length);
-  }
-
-  public int read(byte[] b, int off, int len) throws IOException
-  {
-    return in.read(b, off, len);
-  }
-
-  public synchronized void reset() throws IOException
-  {
-    in.reset();
-  }
-
-  public long skip(long n) throws IOException
-  {
-    return in.skip(n);
-  }
+
+/*************************************************************************/
+
+/*
+ * Instance Variables
+ */
+
+/**
+  * This is the subordinate <code>InputStream</code> to which method calls
+  * are redirected
+  */
+protected InputStream in;
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+
+/**
+  * Create a <code>FilterInputStream</code> with the specified subordinate
+  * <code>InputStream</code>.
+  *
+  * @param in The subordinate <code>InputStream</code>
+  */
+protected 
+FilterInputStream(InputStream in)
+{
+  this.in = in;
+}
+
+/*************************************************************************/
+
+/*
+ * Instance Methods
+ */
+
+/**
+  * Calls the <code>in.mark(int)</code> method.
+  *
+  * @param readlimit The parameter passed to <code>in.mark(int)</code>
+  */
+public void
+mark(int readlimit)
+{
+  in.mark(readlimit);
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.markSupported()</code> method.
+  *
+  * @return <code>true</code> if mark/reset is supported, <code>false</code>
+  *         otherwise
+  */
+public boolean
+markSupported()
+{
+  return(in.markSupported());
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.reset()</code> method.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+reset() throws IOException
+{
+  in.reset();
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.available()</code> method.
+  *
+  * @return The value returned from <code>in.available()</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+available() throws IOException
+{
+  return(in.available());
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.skip(long)</code> method
+  *
+  * @param The requested number of bytes to skip. 
+  *
+  * @return The value returned from <code>in.skip(long)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public long
+skip(long num_bytes) throws IOException
+{
+  return(in.skip(num_bytes));
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.read()</code> method
+  *
+  * @return The value returned from <code>in.read()</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+read() throws IOException
+{
+  return(in.read());
 }
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>read(byte[], int, int)</code> overloaded method.  Note that 
+  * this method does not redirect its call directly to a corresponding
+  * method in <code>in</code>.  This allows subclasses to override only the
+  * three argument version of <code>read</code>.
+  *
+  * @param buf The buffer to read bytes into
+  *
+  * @return The value retured from <code>in.read(byte[], int, int)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+read(byte[] buf) throws IOException
+{
+  return(read(buf, 0, buf.length));
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.read(byte[], int, int)</code> method.
+  *
+  * @param buf The buffer to read bytes into
+  * @param offset The index into the buffer to start storing bytes
+  * @param len The maximum number of bytes to read.
+  *
+  * @return The value retured from <code>in.read(byte[], int, int)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+read(byte[] buf, int offset, int len) throws IOException
+{
+  return(in.read(buf, offset, len));
+}
+
+/*************************************************************************/
+
+/**
+  * This method closes the input stream by closing the input stream that
+  * this object is filtering.  Future attempts to access this stream may
+  * throw an exception.
+  * 
+  * @exception IOException If an error occurs
+  */
+public void
+close() throws IOException
+{
+  in.close();
+}
+
+} // class FilterInputStream
diff --git a/libjava/java/io/FilterOutputStream.java b/libjava/java/io/FilterOutputStream.java
index c17ea26..53e519c 100644
--- a/libjava/java/io/FilterOutputStream.java
+++ b/libjava/java/io/FilterOutputStream.java
@@ -1,62 +1,171 @@
-// FilterOutputStream.java - A filtered stream
+/* FilterOutputStream.java -- Parent class for output streams that filter
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+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.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-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.
 
-package java.io;
+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. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 24, 1998 
- */
+
+package java.io;
 
 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  * "The Java Language Specification", ISBN 0-201-63451-1
  * Status:  Complete to version 1.1.
  */
 
+/**
+  * This class is the common superclass of output stream classes that 
+  * filter the output they write.  These classes typically transform the
+  * data in some way prior to writing it out to another underlying
+  * <code>OutputStream</code>.  This class simply overrides all the 
+  * methods in <code>OutputStream</code> to redirect them to the
+  * underlying stream.  Subclasses provide actual filtering.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public class FilterOutputStream extends OutputStream
 {
-  public void close () throws IOException
-  {
-    flush ();
-    out.close();
-  }
-
-  public FilterOutputStream (OutputStream ox)
-  {
-    out = ox;
-  }
-
-  public void flush () throws IOException
-  {
-    out.flush();
-  }
-
-  public void write (int b) throws IOException
-  {
-    out.write(b);
-  }
-
-  public void write (byte[] b) throws IOException, NullPointerException
-  {
-    // Don't do checking here, per Java Lang Spec.
-    write (b, 0, b.length);
-  }
-
-  public void write (byte[] b, int off, int len)
-    throws IOException, NullPointerException, IndexOutOfBoundsException
-  {
-    // Don't do checking here, per Java Lang Spec.
-    for (int i=0; i < len; i++) 
-      write (b[off + i]);
-  }
-
-  // The output stream.
-  protected OutputStream out;
+
+/*************************************************************************/
+
+/*
+ * Instance Variables
+ */
+
+/**
+  * This is the subordinate <code>OutputStream</code> that this class
+  * redirects its method calls to.
+  */
+protected OutputStream out;
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+
+/**
+  * This method initializes an instance of <code>FilterOutputStream</code>
+  * to write to the specified subordinate <code>OutputStream</code>.
+  *
+  * @param out The <code>OutputStream</code> to write to
+  */
+public
+FilterOutputStream(OutputStream out)
+{
+  this.out = out;
+}
+
+/*************************************************************************/
+
+/*
+ * Instance Methods
+ */
+
+/**
+  * This method closes the underlying <code>OutputStream</code>.  Any
+  * further attempts to write to this stream may throw an exception.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+close() throws IOException
+{
+  flush();
+  out.close();
+}
+
+/*************************************************************************/
+
+/**
+  * This method attempt to flush all buffered output to be written to the
+  * underlying output sink.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+flush() throws IOException
+{
+  out.flush();
 }
+
+/*************************************************************************/
+
+/**
+  * This method writes a single byte of output to the underlying
+  * <code>OutputStream</code>.
+  *
+  * @param b The byte to write, passed as an int.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(int b) throws IOException
+{
+  out.write(b);
+}
+
+/*************************************************************************/
+
+/**
+  * This method writes all the bytes in the specified array to the underlying
+  * <code>OutputStream</code>.  It does this by calling the three parameter
+  * version of this method - <code>write(byte[], int, int)</code> in this
+  * class instead of writing to the underlying <code>OutputStream</code>
+  * directly.  This allows most subclasses to avoid overriding this method.
+  *
+  * @param buf The byte array to write bytes from
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(byte[] buf) throws IOException
+{
+  // Don't do checking here, per Java Lang Spec.
+  write(buf, 0, buf.length);
+}
+
+/*************************************************************************/
+
+/**
+  * This method calls the <code>write(int)</code> method <code>len</code>
+  * times for all bytes from the array <code>buf</code> starting at index
+  * <code>offset</code>. Subclasses should overwrite this method to get a
+  * more efficient implementation.
+  *
+  * @param buf The byte array to write bytes from
+  * @param offset The index into the array to start writing bytes from
+  * @param len The number of bytes to write
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(byte[] buf, int offset, int len) throws IOException
+{
+  // Don't do checking here, per Java Lang Spec.
+  for (int i=0; i < len; i++) 
+    write(buf[offset + i]);
+
+}
+
+} // class FilterOutputStream
diff --git a/libjava/java/io/FilterReader.java b/libjava/java/io/FilterReader.java
index 608f910..a3897bc 100644
--- a/libjava/java/io/FilterReader.java
+++ b/libjava/java/io/FilterReader.java
@@ -1,75 +1,214 @@
-/* Copyright (C) 1998, 1999, 2001  Free Software Foundation
+/* FilterReader.java -- Base class for char stream classes that filter input
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
+
+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. */
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
 
 package java.io;
 
-/**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 15, 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 is the common superclass of all standard classes that filter 
+  * input.  It acts as a layer on top of an underlying <code>Reader</code>
+  * and simply redirects calls made to it to the subordinate Reader
+  * instead.  Subclasses of this class perform additional filtering
+  * functions in addition to simply redirecting the call.
+  * <p>
+  * When creating a subclass of <code>FilterReader</code>, override the
+  * appropriate methods to implement the desired filtering.  However, note
+  * that the <code>read(char[])</code> method does not need to be overridden
+  * as this class redirects calls to that method to 
+  * <code>read(yte[], int, int)</code> instead of to the subordinate
+  * <code>Reader} read(yte[])</code> method.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Warren Levy <warrenl@cygnus.com>
+  */
 public abstract class FilterReader extends Reader
 {
-  /* The input stream to be filtered. */
-  protected Reader in;
-
-  protected FilterReader(Reader in)
-  {
-    super(in.lock);
-    this.in = in; 
-  }
-
-  public void close() throws IOException
-  {
-    // We used to set `in = null' here.  We don't, though, because
-    // that is the simplest way to ensure that read-after-close will
-    // throw the appropriate exception -- we rely on the filtered
-    // stream to do it.
-    in.close();
-  }
-
-  public synchronized void mark(int readlimit) throws IOException
-  {
-    in.mark(readlimit);
-  }
-
-  public boolean markSupported()
-  {
-    return in.markSupported();
-  }
-
-  public int read() throws IOException
-  {
-    return in.read();
-  }
-
-  public int read(char[] b, int off, int len) throws IOException
-  {
-    return in.read(b, off, len);
-  }
-
-  public boolean ready() throws IOException
-  {
-    return in.ready();
-  }
-
-  public synchronized void reset() throws IOException
-  {
-    in.reset();
-  }
-
-  public long skip(long n) throws IOException
-  {
-    return in.skip(n);
-  }
+
+/*************************************************************************/
+
+/*
+ * Instance Variables
+ */
+
+/**
+  * This is the subordinate <code>Reader</code> to which method calls
+  * are redirected
+  */
+protected Reader in;
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+
+/**
+  * Create a <code>FilterReader</code> with the specified subordinate
+  * <code>Reader</code>.
+  * The <code>lock</code> of the new <code>FilterReader</code> will be set
+  * to <code>in.lock</code>.
+  *
+  * @param in The subordinate <code>Reader</code>
+  */
+protected 
+FilterReader(Reader in)
+{
+  super(in.lock);
+  this.in = in;
+}
+
+/*************************************************************************/
+
+/*
+ * Instance Methods
+ */
+
+/**
+  * Calls the <code>in.mark(int)</code> method.
+  *
+  * @param readlimit The parameter passed to <code>in.mark(int)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+mark(int readlimit) throws IOException
+{
+  in.mark(readlimit);
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.markSupported()</code> method.
+  *
+  * @return <code>true</code> if mark/reset is supported, <code>false</code> otherwise
+  */
+public boolean
+markSupported()
+{
+  return(in.markSupported());
 }
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.reset()</code> method.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+reset() throws IOException
+{
+  in.reset();
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.read()</code> method.
+  *
+  * @return The value returned from <code>in.available()</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public boolean
+ready() throws IOException
+{
+  return(in.ready());
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.skip(long)</code> method
+  *
+  * @param The requested number of chars to skip. 
+  *
+  * @return The value returned from <code>in.skip(long)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public long
+skip(long num_chars) throws IOException
+{
+  return(in.skip(num_chars));
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.read()</code> method
+  *
+  * @return The value returned from <code>in.read()</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+read() throws IOException
+{
+  return(in.read());
+}
+
+/*************************************************************************/
+
+/**
+  * Calls the <code>in.read(char[], int, int)</code> method.
+  *
+  * @param buf The buffer to read chars into
+  * @param offset The index into the buffer to start storing chars
+  * @param len The maximum number of chars to read.
+  *
+  * @return The value retured from <code>in.read(char[], int, int)</code>
+  *
+  * @exception IOException If an error occurs
+  */
+public int
+read(char[] buf, int offset, int len) throws IOException
+{
+  return(in.read(buf, offset, len));
+}
+
+/*************************************************************************/
+
+/**
+  * This method closes the stream by calling the <code>close()</code> method
+  * of the underlying stream.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+close() throws IOException
+{
+  in.close();
+}
+
+} // class FilterReader
diff --git a/libjava/java/io/FilterWriter.java b/libjava/java/io/FilterWriter.java
index aa6600c..eaa7066 100644
--- a/libjava/java/io/FilterWriter.java
+++ b/libjava/java/io/FilterWriter.java
@@ -1,58 +1,168 @@
-// FilterWriter.java - Filtered character output stream.
+/* FilterWriter.java -- Parent class for output streams that filter
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+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.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-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.
 
-package java.io;
+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. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 25, 1998 
- */
+
+package java.io;
 
 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  * "The Java Language Specification", ISBN 0-201-63451-1
  * Status:  Complete to version 1.1.
  */
 
+/**
+  * This class is the common superclass of output character stream classes 
+  * that filter the output they write.  These classes typically transform the
+  * data in some way prior to writing it out to another underlying
+  * <code>Writer</code>.  This class simply overrides all the 
+  * methods in <code>Writer</code> to redirect them to the
+  * underlying stream.  Subclasses provide actual filtering.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public abstract class FilterWriter extends Writer
 {
-  public void close () throws IOException
-  {
-    out.close();
-  }
-
-  protected FilterWriter (Writer ox)
-  {
-    super (ox);
-    out = ox;
-  }
-
-  public void flush () throws IOException
-  {
-    out.flush();
-  }
-
-  public void write (int oneChar) throws IOException
-  {
-    out.write(oneChar);
-  }
-
-  public void write (char[] buffer, int offset, int count) throws IOException
-  {
-    out.write(buffer, offset, count);
-  }
-
-  public void write (String str, int offset, int count) throws IOException
-  {
-    out.write(str, offset, count);
-  }
-
-  // Where our writes should go.
-  protected Writer out;
+
+/*************************************************************************/
+
+/*
+ * Instance Variables
+ */
+
+/**
+  * This is the subordinate <code>Writer</code> that this class
+  * redirects its method calls to.
+  */
+protected Writer out;
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+
+/**
+  * This method initializes an instance of <code>FilterWriter</code>
+  * to write to the specified subordinate <code>Writer</code>.
+  * The given <code>Writer</code> will be used as <code>lock</code> for
+  * the newly created <code>FilterWriter</code>.
+  *
+  * @param out The <code>Writer</code> to write to
+  */
+protected
+FilterWriter(Writer out)
+{
+  super(out);
+  this.out = out;
+}
+
+/*************************************************************************/
+
+/*
+ * Instance Methods
+ */
+
+/**
+  * This method closes the underlying <code>Writer</code>.  Any
+  * further attempts to write to this stream may throw an exception.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+close() throws IOException
+{
+  out.close();
+}
+
+/*************************************************************************/
+
+/**
+  * This method attempt to flush all buffered output to be written to the
+  * underlying output sink.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+flush() throws IOException
+{
+  out.flush();
 }
+
+/*************************************************************************/
+
+/**
+  * This method writes a single char of output to the underlying
+  * <code>Writer</code>.
+  *
+  * @param b The char to write, passed as an int.
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(int b) throws IOException
+{
+  out.write(b);
+}
+
+/*************************************************************************/
+
+/**
+  * This method writes <code>len</code> chars from the array <code>buf</code>
+  * starting at index <code>offset</code> to the underlying
+  * <code>Writer</code>.
+  *
+  * @param buf The char array to write chars from
+  * @param offset The index into the array to start writing chars from
+  * @param len The number of chars to write
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(char[] buf, int offset, int len) throws IOException
+{
+  out.write(buf, offset, len);
+}
+
+/*************************************************************************/
+
+/**
+  * This method writes <code>len</code> chars from the <code>String</code>
+  * starting at position <code>offset</code>.
+  *
+  * @param str The <code>String</code> that is to be written
+  * @param offset The character offset into the <code>String</code> to start writing from
+  * @param len The number of chars to write
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(String str, int offset, int len) throws IOException
+{
+  out.write(str, offset, len);
+}
+
+} // class FilterWriter
+
diff --git a/libjava/java/io/Writer.java b/libjava/java/io/Writer.java
index 96fa0fb..2ce5ca3 100644
--- a/libjava/java/io/Writer.java
+++ b/libjava/java/io/Writer.java
@@ -1,67 +1,211 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* Writer.java -- Base class for character output streams
+   Copyright (C) 1998, 1999, 2001 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 17, 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.
- * However, write(String, int, int) should be made a native method.
  */
 
+/**
+  * This abstract class forms the base of the hierarchy of classes that 
+  * write output as a stream of chars.  It provides a common set of methods
+  * for writing chars to stream.  Subclasses implement and/or extend these
+  * methods to write chars in a particular manner or to a particular 
+  * destination such as a file on disk or network connection.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Per Bothner <bothner@cygnus.com>
+  */
 public abstract class Writer
 {
-  protected Object lock;
-
-  protected Writer ()
-  {
-    lock = this;
-  }
-
-  protected Writer (Object lock)
-  {
-    this.lock = lock;
-  }
-
-  abstract public void close() throws IOException;
-
-  abstract public void flush() throws IOException;
-
-  abstract public void write(char[] buf, int offset, int count)
-     throws IOException;
-
-  public void write(char[] buf) throws IOException
-  {
-    write(buf, 0, buf.length);
-  }
-
-  public void write(int ch) throws IOException
-  {
-    char[] buf = new char[1];
-    buf[0] = (char) ch;
-    write(buf, 0, 1);
-  }
-
-  // FIXME - re-write using native code to not require copied buffer.
-  public void write (String str, int offset, int count) throws IOException
-  {
-    char[] buf = new char[count];
-    str.getChars(offset, offset + count, buf, 0);
-    write(buf, 0, count);
-  }
-
-  public void write (String str) throws IOException
-  {
-    write(str, 0, str.length());
-  }
 
+/*************************************************************************/
+
+/**
+  * This is the object used to synchronize criticial code sections for
+  * thread safety.  Subclasses should use this field instead of using
+  * synchronized methods or explicity synchronizations on <code>this</code>
+  */
+protected Object lock;
+
+/*************************************************************************/
+
+/*
+ * Constructors
+ */
+
+/**
+  * This is the default no-argument constructor for this class.  This method
+  * will set up the class to synchronize criticial sections on itself.
+  */
+protected
+Writer()
+{
+  lock = this;
 }
+
+/*************************************************************************/
+
+/**
+  * This method initializes a <code>Writer</code> that will synchronize
+  * on the specified <code>Object</code>.
+  *
+  * @param obj The <code>Object</code> to use for synchronizing critical
+  *            sections
+  */
+protected
+Writer(Object lock)
+{
+  this.lock = lock;
+}
+
+/*************************************************************************/
+
+/*
+ * Instance Methods
+ */
+
+/**
+  * This method forces any data that may have been buffered to be written
+  * to the underlying output device.  Please note that the host environment
+  * might perform its own buffering unbeknowst to Java.  In that case, a
+  * write made (for example, to a disk drive) might be cached in OS
+  * buffers instead of actually being written to disk.
+  *
+  * @exception IOException If an error occurs
+  */
+public abstract void
+flush() throws IOException;
+
+/*************************************************************************/
+
+/**
+  * This method closes the stream.  Any internal or native resources associated
+  * with this stream are freed.  Any subsequent attempt to access the stream
+  * might throw an exception.
+  * <p>
+  * This method in this class does nothing.
+  *
+  * @exception IOException If an error occurs
+  */
+public abstract void
+close() throws IOException;
+
+/*************************************************************************/
+
+/**
+  * This method writes a single char to the output stream. 
+  *
+  * @param b The char to be written to the output stream, passed as an int
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(int b) throws IOException
+{
+  char[] buf = new char[1];
+
+  buf[0] = (char)b;
+  write(buf, 0, buf.length);
+}
+
+/*************************************************************************/
+
+/**
+  * This method all the writes char from the passed array to the output stream.
+  * This method is equivalent to <code>write(buf, 0, buf.length)</code> which
+  * is exactly how it is implemented in this class.
+  *
+  * @param buf The array of char to write
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(char[] buf) throws IOException
+{
+  write(buf, 0, buf.length);
+}
+
+/*************************************************************************/
+
+/**
+  * This method writes <code>len</code> char from the specified array
+  * <code>buf</code> starting at index <code>offset</code> into the array.
+  * <p>
+  * Subclasses must provide an implementation of this abstract method.
+  *
+  * @param buf The array of char to write from
+  * @param offset The index into the array to start writing from
+  * @param len The number of char to write
+  * 
+  * @exception IOException If an error occurs
+  */
+public abstract void
+write(char[] buf, int offset, int len) throws IOException;
+
+/*************************************************************************/
+
+/**
+  * This method writes all the characters in a <code>String</code> to the
+  * output.
+  *
+  * @param str The <code>String</code> whose chars are to be written.
+  *
+  * @param IOException If an error occurs
+  */
+public void
+write(String str) throws IOException
+{
+  write(str, 0, str.length());
+} 
+
+/*************************************************************************/
+
+/**
+  * This method writes <code>len</code> chars from the <code>String</code>
+  * starting at position <code>offset</code>.
+  *
+  * @param str The <code>String</code> that is to be written
+  * @param offset The character offset into the <code>String</code> to start
+  *               writing from
+  * @param len The number of chars to write
+  *
+  * @exception IOException If an error occurs
+  */
+public void
+write(String str, int offset, int len) throws IOException
+{
+  // FIXME - for libgcj re-write using native code to not require copied buffer.
+  char[] buf = new char[len];
+
+  str.getChars(offset, offset + len, buf, 0);
+  write(buf, 0, len);
+}
+
+} // class Writer