From 67f279dfebbb2690ebf57246e27794e6b18fdae9 Mon Sep 17 00:00:00 2001 From: Bryce McKinlay Date: Mon, 30 Oct 2000 09:20:47 +0000 Subject: [PATCH] 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 --- libjava/ChangeLog | 7 ++ libjava/java/io/FileReader.java | 81 ++++++++++--- libjava/java/io/Reader.java | 188 +++++++++++++++++++++++++++--- libjava/java/io/StringReader.java | 72 +++++++++--- 4 files changed, 299 insertions(+), 49 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index be1a10a1107..a1b3d5c944b 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 * java/util/AbstractCollection.java (addAll): Use size() instead of diff --git a/libjava/java/io/FileReader.java b/libjava/java/io/FileReader.java index c82ce5b37e2..0dbcd0e07c7 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 - * @date April 22, 1998. + * This class provides a convenient way to set up a Reader + * to read from a file. It opens the specified file for reading and creates + * the InputStreamReader to read from the + * resulting FileInputStream. This class can only be used + * to read from files using the default character encoding. Use + * InputStreamReader 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 FileReader instance to read from + * the specified File object. + * + * @param file The File 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 FileReader instance to read from + * this specified FileDescriptor object. + * + * @param fd The FileDescriptor to read from. + */ public FileReader(FileDescriptor fd) { super(new FileInputStream(fd)); } + + /** + * This method initializes a FileReader 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 c8e8f29c6fa..e8329d604fd 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 - * @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 + * @date April 21, 1998. + * @author Aaron M. Renn (arenn@urbanophile.com) + */ public abstract class Reader { + /** + * This is the Object used for synchronizing critical code + * sections. Subclasses should use this variable instead of a + * synchronized method or an explicit synchronization on this + */ protected Object lock; - + + /** + * Unitializes a Reader that will use the object + * itself for synchronization of critical code sections. + */ protected Reader() { this.lock = this; } + /** + * Initializes a Reader that will use the specified + * Object for synchronization of critical code sections. + * + * @param lock The Object 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 offset + * into the buffer and attempts to read len 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. + *

+ * This method will block until some data can be read. + *

+ * This method operates by calling the single char read() 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. + *

+ * This method will block until some data can be read. + *

+ * This method operates by calling an overloaded read method like so: + * read(buf, 0, buf.length) + * + * @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. + *

+ * 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 IOException. + * + * @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. + *

+ * This method always returns false in this class, but + * subclasses can override this method to return true if they + * support mark/reset functionality. + * + * @return true if mark/reset functionality is supported, + * false otherwise + * + */ public boolean markSupported() { return false; } + /** + * Marks a position in the input to which the stream can be + * "reset" by calling the reset() method. The parameter + * readlimit is the number of chars that can be read from the + * stream after setting the mark before the mark becomes invalid. For + * example, if mark() is called with a read limit of 10, then + * when 11 chars of data are read from the stream before the + * reset() 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 mark() + * method was called. Any chars that were read after the mark point was + * set will be re-read during subsequent reads. + *

+ * 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 false the stream may block if a + * read is attempted, but it is not guaranteed to do so. + *

+ * This method always returns false in this class + * + * @return true if the stream is ready to be read, false 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. + *

+ * 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 60a912975af..66d37325a4c 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 - * @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 String to be read as a character + * input stream. + *

+ * The mark/reset functionality in this class behaves differently than + * normal. If no mark has been set, then calling the reset() + * method rewinds the read pointer to the beginning of the String. + * + * @version 0.0 + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + * @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 StringReader that will read chars from the + * passed in String. This stream will read from the beginning to the + * end of the String. + * + * @param s The String 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 true, unless + * close() has previously been called in which case an IOException is + * thrown. + * + * @return true 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 pos 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