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
This commit is contained in:
Bryce McKinlay 2000-10-30 09:20:47 +00:00 committed by Bryce McKinlay
parent b1628585d3
commit 67f279dfeb
4 changed files with 299 additions and 49 deletions

View File

@ -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

View File

@ -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.
* 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)
*/
/* Written using "Java Class Libraries", 2nd edition.
* Status: Believed complete and correct.
*/
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));
}
}

View File

@ -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;
}
}

View File

@ -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