From: mark Date: Mon, 8 Oct 2001 18:53:49 +0000 (+0000) Subject: * java/io/BufferedInputStream.java: Merge with Classpath X-Git-Tag: upstream/4.9.2~91732 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7f066fb6d45ad66fd39a2e39d8a40d32c87a9ac7;p=platform%2Fupstream%2Flinaro-gcc.git * java/io/BufferedInputStream.java: Merge with Classpath git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@46086 138bc75d-0d04-0410-961f-82ee72b054a4 --- diff --git a/libjava/ChangeLog b/libjava/ChangeLog index cd9e847..b79cb49 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,7 @@ +2001-10-06 Mark Wielaard + + * java/io/BufferedInputStream.java: Merge with Classpath + 2001-10-07 Joseph S. Myers * defineclass.cc, java/awt/image/ColorModel.java, diff --git a/libjava/java/io/BufferedInputStream.java b/libjava/java/io/BufferedInputStream.java index 15fa936..8eae02d 100644 --- a/libjava/java/io/BufferedInputStream.java +++ b/libjava/java/io/BufferedInputStream.java @@ -1,45 +1,118 @@ -/* Copyright (C) 1998, 1999, 2001 Free Software Foundation +/* BufferedInputStream.java -- An input stream that implements buffering + 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 - * @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 subclass of FilterInputStream 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 2048 bytes can be overridden by the creator of the stream. + *

+ * This class also implements mark/reset functionality. It is capable + * of remembering any number of input bytes, to the limits of + * system memory or the size of Integer.MAX_VALUE + *

+ * Please note that this class does not properly handle character + * encodings. Consider using the BufferedReader class which + * does. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class BufferedInputStream extends FilterInputStream { - /* Internal buffer array for data. */ + + /** + * This is the default buffer size + */ + private static final int DEFAULT_BUFFER_SIZE = 2048; + + /** + * The buffer used for storing data from the underlying stream. + */ protected byte[] buf; - /* Index one greater than the last valid byte in the buffer. */ + /** + * The number of valid bytes currently in the buffer. It is also the index + * of the buffer position one byte past the end of the valid data. + */ protected int count = 0; - /* The current position in the buffer. */ + /** + * The index of the next character that will by read from the buffer. + * When pos == count, the buffer is empty. + */ protected int pos = 0; - /* The value of pos the last time mark() was called. */ + /** + * The value of pos when the mark() method was + * called. + * This is set to -1 if there is no mark set. + */ protected int markpos = -1; - /* The maximum read-ahead allowed before calls to reset() fail. */ + /** + * This is the maximum number of bytes than can be read after a + * call to mark() before the mark can be discarded. + * After this may bytes are read, the reset() method + * may not be called successfully. + */ protected int marklimit = 0; + /** + * This method initializes a new BufferedInputStream that will + * read from the specified subordinate stream with a default buffer size + * of 2048 bytes + * + * @param in The subordinate stream to read from + */ public BufferedInputStream(InputStream in) { - this(in, 2048); + this(in, DEFAULT_BUFFER_SIZE); } + /** + * This method initializes a new BufferedInputStream 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 size The buffer size to use + * + * @exception IllegalArgumentException when size is smaller then 1 + */ public BufferedInputStream(InputStream in, int size) { super(in); @@ -48,11 +121,30 @@ public class BufferedInputStream extends FilterInputStream buf = new byte[size]; } + /** + * This method returns the number of bytes that can be read from this + * stream before a read can block. A return of 0 indicates that blocking + * might (or might not) occur on the very next read attempt. + *

+ * The number of available bytes will be the number of read ahead bytes + * stored in the internal buffer plus the number of available bytes in + * the underlying stream. + * + * @return The number of bytes that can be read before blocking could occur + * + * @exception IOException If an error occurs + */ public synchronized int available() throws IOException { return count - pos + super.available(); } + /** + * This method closes the underlying input stream and frees any + * resources associated with it. Sets buf to null. + * + * @exception IOException If an error occurs. + */ public void close() throws IOException { // Free up the array memory. @@ -60,17 +152,54 @@ public class BufferedInputStream extends FilterInputStream super.close(); } + /** + * This method 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 bytes 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 bytes 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. + *

+ * Note that the number of bytes 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 bytes that can be read before the mark + * becomes invalid + */ public synchronized void mark(int readlimit) { marklimit = readlimit; markpos = pos; } + /** + * This method returns true to indicate that this class + * supports mark/reset functionality. + * + * @return true to indicate that mark/reset functionality is + * supported + * + */ public boolean markSupported() { return true; } + /** + * This method reads an unsigned byte from the input stream and returns it + * as an int in the range of 0-255. This method also will return -1 if + * the end of the stream has been reached. + *

+ * This method will block until the byte can be read. + * + * @return The byte read or -1 if end of stream + * + * @exception IOException If an error occurs + */ public synchronized int read() throws IOException { if (pos >= count && !refill()) @@ -82,10 +211,31 @@ public class BufferedInputStream extends FilterInputStream return ((int) buf[pos++]) & 0xFF; } + /** + * This method reads bytes from a stream and stores them into a caller + * supplied buffer. It starts storing the data at index off + * into the buffer and attempts to read len bytes. This method + * can return before reading the number of bytes requested. The actual + * number of bytes 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. + * + * @param b The array into which the bytes read should be stored + * @param off The offset into the array to start storing bytes + * @param len The requested number of bytes to read + * + * @return The actual number of bytes read, or -1 if end of stream. + * + * @exception IOException If an error occurs. + * @exception IndexOutOfBoundsException when off or + * len are negative, or when off + len + * is larger then the size of b, + */ public synchronized int read(byte[] b, int off, int len) throws IOException { if (off < 0 || len < 0 || off + len > b.length) - throw new ArrayIndexOutOfBoundsException(); + throw new IndexOutOfBoundsException(); if (pos >= count && !refill()) return -1; // No bytes were read before EOF. @@ -100,6 +250,19 @@ public class BufferedInputStream extends FilterInputStream return remain; } + /** + * This method resets a stream to the point where the mark() + * method was called. Any bytes that were read after the mark point was + * set will be re-read during subsequent reads. + *

+ * This method will throw an IOException if the number of bytes read from + * the stream since the call to mark() exceeds the mark limit + * passed when establishing the mark. + * + * @exception IOException If mark() was never called or more + * then markLimit bytes were read since the last + * call to mark() + */ public synchronized void reset() throws IOException { if (markpos < 0) @@ -108,6 +271,17 @@ public class BufferedInputStream extends FilterInputStream pos = markpos; } + /** + * This method skips the specified number of bytes in the stream. It + * returns the actual number of bytes skipped, which may be less than the + * requested amount. + * + * @param n The requested number of bytes to skip + * + * @return The actual number of bytes skipped. + * + * @exception IOException If an error occurs + */ public synchronized long skip(long n) throws IOException { final long origN = n; @@ -131,6 +305,13 @@ public class BufferedInputStream extends FilterInputStream return origN - n; } + /** + * Called to refill the buffer (when count is equal or greater the pos). + * Package local so BufferedReader can call it when needed. + * + * @return true when buf can be (partly) refilled, + * false otherwise. + */ boolean refill() throws IOException { if (markpos < 0)