diff options
Diffstat (limited to 'libjava/java/io/BufferedReader.java')
| -rw-r--r-- | libjava/java/io/BufferedReader.java | 144 |
1 files changed, 138 insertions, 6 deletions
diff --git a/libjava/java/io/BufferedReader.java b/libjava/java/io/BufferedReader.java index 73601de..9a293da 100644 --- a/libjava/java/io/BufferedReader.java +++ b/libjava/java/io/BufferedReader.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,15 +8,25 @@ details. */ package java.io; -/** - * @author Per Bothner <bothner@cygnus.com> - * @date April 22, 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 subclass of <code>FilterReader</code> buffers input from an + * underlying implementation to provide a possibly more efficient read + * mechanism. It maintains the buffer and buffer state in instance + * variables that are available to subclasses. The default buffer size + * of 512 chars can be overridden by the creator of the stream. + * <p> + * This class also implements mark/reset functionality. It is capable + * of remembering any number of input chars, to the limits of + * system memory or the size of <code>Integer.MAX_VALUE</code> + * + * @author Per Bothner <bothner@cygnus.com> + * @author Aaron M. Renn <arenn@urbanophile.com> + */ public class BufferedReader extends Reader { Reader in; @@ -43,11 +53,25 @@ public class BufferedReader extends Reader guaranteed to be >= the read-limit requested in the call to mark. */ int markPos = -1; + /** + * Create a new <code>BufferedReader</code> that will read from the + * specified subordinate stream with a default buffer size of 4096 chars. + * + * @param in The subordinate stream to read from + */ public BufferedReader(Reader in) { this(in, 8192); } + /** + * Create a new <code>BufferedReader</code> that will read from the + * specified subordinate stream with a buffer size that is specified by the + * caller. + * + * @param in The subordinate stream to read from + * @param bufsize The buffer size to use + */ public BufferedReader(Reader in, int size) { super(in.lock); @@ -55,6 +79,11 @@ public class BufferedReader extends Reader buffer = new char[size]; } + /** + * This method closes the stream + * + * @exception IOException If an error occurs + */ public void close() throws IOException { synchronized (lock) @@ -66,13 +95,40 @@ public class BufferedReader extends Reader } } + /** + * Returns <code>true</code> to indicate that this class supports mark/reset + * functionality. + * + * @return <code>true</code> + */ public boolean markSupported() { return true; } + /** + * Mark 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. + * <p> + * Note that the number of chars that can be remembered by this method + * can be greater than the size of the internal read buffer. It is also + * not dependent on the subordinate stream supporting mark/reset + * functionality. + * + * @param readlimit The number of chars that can be read before the mark + * becomes invalid + * + * @exception IOException If an error occurs + */ public void mark(int readLimit) throws IOException { + checkStatus(); synchronized (lock) { // In this method we need to be aware of the special case where @@ -116,8 +172,20 @@ public class BufferedReader extends Reader } } + /** + * Reset the 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 will throw an IOException if the number of chars read from + * the stream since the call to <code>mark()</code> exceeds the mark limit + * passed when establishing the mark. + * + * @exception IOException If an error occurs; + */ public void reset() throws IOException { + checkStatus(); synchronized (lock) { if (markPos < 0) @@ -136,16 +204,45 @@ public class BufferedReader extends Reader } } + /** + * This method determines whether or not a stream is ready to be read. If + * This method returns <code>false</code> then this stream could (but is + * not guaranteed to) block on the next read attempt. + * + * @return <code>true</code> if this stream is ready to be read, <code>false</code> otherwise + * + * @exception IOException If an error occurs + */ public boolean ready() throws IOException { + checkStatus(); synchronized (lock) { return pos < limit || in.ready(); } } + /** + * This method 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. + * + * @param buf The array into which the chars read should be stored + * @param offset The offset into the array to start storing chars + * @param count 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 int read(char[] buf, int offset, int count) throws IOException { + checkStatus(); synchronized (lock) { // Once again, we need to handle the special case of a readLine @@ -202,6 +299,7 @@ public class BufferedReader extends Reader Return number of chars read (never 0), or -1 on eof. */ private int fill() throws IOException { + checkStatus(); // Handle the special case of a readLine that has a '\r' at the end of // the buffer. In this case, we'll need to skip a '\n' if it is the // next char to be read. This special case is indicated by 'pos > limit'. @@ -228,9 +326,10 @@ public class BufferedReader extends Reader return count; } - + public int read() throws IOException { + checkStatus(); synchronized (lock) { if (pos >= limit && fill () <= 0) @@ -255,8 +354,20 @@ public class BufferedReader extends Reader return i; } + /** + * This method reads a single line of text from the input stream, returning + * it as a <code>String</code>. A line is terminated by "\n", a "\r", or + * an "\r\n" sequence. The system dependent line separator is not used. + * The line termination characters are not returned in the resulting + * <code>String</code>. + * + * @return The line of text read, or <code>null</code> if end of stream. + * + * @exception IOException If an error occurs + */ public String readLine() throws IOException { + checkStatus(); // Handle the special case where a previous readLine (with no intervening // reads/skips) had a '\r' at the end of the buffer. // In this case, we'll need to skip a '\n' if it's the next char to be read. @@ -317,8 +428,23 @@ public class BufferedReader extends Reader return (sbuf.length() == 0 && eof) ? null : sbuf.toString(); } + /** + * This method 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 first discards chars in the buffer, then calls the + * <code>skip</code> method on the underlying stream to skip the remaining chars. + * + * @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 { + checkStatus(); if (count <= 0) return 0; synchronized (lock) @@ -370,4 +496,10 @@ public class BufferedReader extends Reader return count - todo; } } + + private void checkStatus() throws IOException + { + if (in == null) + throw new IOException("Stream closed"); + } } |