001/* BufferedInputStream.java -- An input stream that implements buffering
002   Copyright (C) 1998, 1999, 2001, 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038 
039package java.io;
040
041/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
042 * "The Java Language Specification", ISBN 0-201-63451-1
043 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
044 * Status:  Believed complete and correct.
045 */
046 
047/**
048 * This subclass of <code>FilterInputStream</code> buffers input from an 
049 * underlying implementation to provide a possibly more efficient read
050 * mechanism.  It maintains the buffer and buffer state in instance 
051 * variables that are available to subclasses.  The default buffer size
052 * of 2048 bytes can be overridden by the creator of the stream.
053 * <p>
054 * This class also implements mark/reset functionality.  It is capable
055 * of remembering any number of input bytes, to the limits of
056 * system memory or the size of <code>Integer.MAX_VALUE</code>
057 * <p>
058 * Please note that this class does not properly handle character
059 * encodings.  Consider using the <code>BufferedReader</code> class which
060 * does.
061 *
062 * @author Aaron M. Renn (arenn@urbanophile.com)
063 * @author Warren Levy (warrenl@cygnus.com)
064 * @author Jeroen Frijters (jeroen@frijters.net)
065 */
066public class BufferedInputStream extends FilterInputStream
067{
068
069  /**
070   * This is the default buffer size
071   */
072  private static final int DEFAULT_BUFFER_SIZE = 2048;
073
074  /**
075   * The buffer used for storing data from the underlying stream.
076   */
077  protected byte[] buf;
078
079  /**
080   * The number of valid bytes currently in the buffer.  It is also the index
081   * of the buffer position one byte past the end of the valid data.
082   */
083  protected int count;
084
085  /**
086   * The index of the next character that will by read from the buffer.
087   * When <code>pos == count</code>, the buffer is empty.
088   */
089  protected int pos;
090
091  /**
092   * The value of <code>pos</code> when the <code>mark()</code> method was
093   * called.  
094   * This is set to -1 if there is no mark set.
095   */
096  protected int markpos = -1;
097
098  /**
099   * This is the maximum number of bytes than can be read after a 
100   * call to <code>mark()</code> before the mark can be discarded.
101   * After this may bytes are read, the <code>reset()</code> method
102   * may not be called successfully.
103   */
104  protected int marklimit;
105
106  /**
107   * This is the initial buffer size. When the buffer is grown because
108   * of marking requirements, it will be grown by bufferSize increments.
109   * The underlying stream will be read in chunks of bufferSize.
110   */
111  private final int bufferSize;
112
113  /**
114   * This method initializes a new <code>BufferedInputStream</code> that will
115   * read from the specified subordinate stream with a default buffer size
116   * of 2048 bytes
117   *
118   * @param in The subordinate stream to read from
119   */
120  public BufferedInputStream(InputStream in)
121  {
122    this(in, DEFAULT_BUFFER_SIZE);
123  }
124
125  /**
126   * This method initializes a new <code>BufferedInputStream</code> that will
127   * read from the specified subordinate stream with a buffer size that
128   * is specified by the caller.
129   *
130   * @param in The subordinate stream to read from
131   * @param size The buffer size to use
132   *
133   * @exception IllegalArgumentException when size is smaller then 1
134   */
135  public BufferedInputStream(InputStream in, int size)
136  {
137    super(in);
138    if (size <= 0)
139      throw new IllegalArgumentException();
140    buf = new byte[size];
141    // initialize pos & count to bufferSize, to prevent refill from
142    // allocating a new buffer (if the caller starts out by calling mark()).
143    pos = count = bufferSize = size;
144  }
145
146  /**
147   * This method returns the number of bytes that can be read from this
148   * stream before a read can block.  A return of 0 indicates that blocking
149   * might (or might not) occur on the very next read attempt.
150   * <p>
151   * The number of available bytes will be the number of read ahead bytes 
152   * stored in the internal buffer plus the number of available bytes in
153   * the underlying stream.
154   *
155   * @return The number of bytes that can be read before blocking could occur
156   *
157   * @exception IOException If an error occurs
158   */
159  public synchronized int available() throws IOException
160  {
161    return count - pos + in.available();
162  }
163
164  /**
165   * This method closes the underlying input stream and frees any
166   * resources associated with it. Sets <code>buf</code> to <code>null</code>.
167   *
168   * @exception IOException If an error occurs.
169   */
170  public void close() throws IOException
171  {
172    // Free up the array memory.
173    buf = null;
174    pos = count = 0;
175    markpos = -1;
176    in.close();
177  }
178
179  /**
180   * This method marks a position in the input to which the stream can be
181   * "reset" by calling the <code>reset()</code> method.  The parameter
182   * <code>readlimit</code> is the number of bytes that can be read from the 
183   * stream after setting the mark before the mark becomes invalid.  For
184   * example, if <code>mark()</code> is called with a read limit of 10, then
185   * when 11 bytes of data are read from the stream before the
186   * <code>reset()</code> method is called, then the mark is invalid and the
187   * stream object instance is not required to remember the mark.
188   * <p>
189   * Note that the number of bytes that can be remembered by this method
190   * can be greater than the size of the internal read buffer.  It is also
191   * not dependent on the subordinate stream supporting mark/reset
192   * functionality.
193   *
194   * @param readlimit The number of bytes that can be read before the mark
195   * becomes invalid
196   */
197  public synchronized void mark(int readlimit)
198  {
199    marklimit = readlimit;
200    markpos = pos;
201  }
202
203  /**
204   * This method returns <code>true</code> to indicate that this class
205   * supports mark/reset functionality.
206   *
207   * @return <code>true</code> to indicate that mark/reset functionality is
208   * supported
209   *
210   */
211  public boolean markSupported()
212  {
213    return true;
214  }
215
216  /**
217   * This method reads an unsigned byte from the input stream and returns it
218   * as an int in the range of 0-255.  This method also will return -1 if
219   * the end of the stream has been reached.
220   * <p>
221   * This method will block until the byte can be read.
222   *
223   * @return The byte read or -1 if end of stream
224   *
225   * @exception IOException If an error occurs
226   */
227  public synchronized int read() throws IOException
228  {
229    if (pos >= count && !refill())
230      return -1;        // EOF
231
232    return buf[pos++] & 0xFF;
233  }
234
235  /**
236   * This method reads bytes from a stream and stores them into a caller
237   * supplied buffer.  It starts storing the data at index <code>off</code>
238   * into the buffer and attempts to read <code>len</code> bytes.  This method
239   * can return before reading the number of bytes requested, but it will try
240   * to read the requested number of bytes by repeatedly calling the underlying
241   * stream as long as available() for this stream continues to return a
242   * non-zero value (or until the requested number of bytes have been read).
243   * The actual number of bytes read is returned as an int.  A -1 is returned
244   * to indicate the end of the stream.
245   * <p>
246   * This method will block until some data can be read.
247   *
248   * @param b The array into which the bytes read should be stored
249   * @param off The offset into the array to start storing bytes
250   * @param len The requested number of bytes to read
251   *
252   * @return The actual number of bytes read, or -1 if end of stream.
253   *
254   * @exception IOException If an error occurs.
255   * @exception IndexOutOfBoundsException when <code>off</code> or
256   *            <code>len</code> are negative, or when <code>off + len</code>
257   *            is larger then the size of <code>b</code>,
258   */
259  public synchronized int read(byte[] b, int off, int len) throws IOException
260  {
261    if (off < 0 || len < 0 || b.length - off < len)
262      throw new IndexOutOfBoundsException();
263
264    if (len == 0)
265      return 0;
266
267    if (pos >= count && !refill())
268      return -1;                // No bytes were read before EOF.
269
270    int totalBytesRead = Math.min(count - pos, len);
271    System.arraycopy(buf, pos, b, off, totalBytesRead);
272    pos += totalBytesRead;
273    off += totalBytesRead;
274    len -= totalBytesRead;
275
276    while (len > 0 && in.available() > 0 && refill())
277      {
278        int remain = Math.min(count - pos, len);
279        System.arraycopy(buf, pos, b, off, remain);
280        pos += remain;
281        off += remain;
282        len -= remain;
283        totalBytesRead += remain;
284      }
285
286    return totalBytesRead;
287  }
288
289  /**
290   * This method resets a stream to the point where the <code>mark()</code>
291   * method was called.  Any bytes that were read after the mark point was
292   * set will be re-read during subsequent reads.
293   * <p>
294   * This method will throw an IOException if the number of bytes read from
295   * the stream since the call to <code>mark()</code> exceeds the mark limit
296   * passed when establishing the mark.
297   *
298   * @exception IOException If <code>mark()</code> was never called or more
299   *            then <code>marklimit</code> bytes were read since the last
300   *            call to <code>mark()</code>
301   */
302  public synchronized void reset() throws IOException
303  {
304    if (markpos == -1)
305      throw new IOException(buf == null ? "Stream closed." : "Invalid mark.");
306
307    pos = markpos;
308  }
309
310  /**
311   * This method skips the specified number of bytes in the stream.  It
312   * returns the actual number of bytes skipped, which may be less than the
313   * requested amount.
314   *
315   * @param n The requested number of bytes to skip
316   *
317   * @return The actual number of bytes skipped.
318   *
319   * @exception IOException If an error occurs
320   */
321  public synchronized long skip(long n) throws IOException
322  {
323    if (buf == null)
324      throw new IOException("Stream closed.");
325
326    final long origN = n;
327
328    while (n > 0L)
329      {
330        if (pos >= count)
331          {
332            if (markpos == -1)
333              {
334                // Buffer is empty and no mark is set, skip on the
335                // underlying stream.
336                n -= in.skip(n);
337                break;
338              }
339            else if (!refill())
340              break;
341          }
342
343        int numread = (int) Math.min((long) (count - pos), n);
344        pos += numread;
345        n -= numread;
346      }
347
348    return origN - n;
349  }
350
351  // GCJ LOCAL: package-private for use by InputStreamReader
352  /**
353   * Called to refill the buffer (when count is equal to pos).
354   *
355   * @return <code>true</code> when at least one additional byte was read
356   *         into <code>buf</code>, <code>false</code> otherwise (at EOF).
357   */
358  boolean refill() throws IOException
359  {
360    if (buf == null)
361      throw new IOException("Stream closed.");
362
363    if (markpos == -1 || count - markpos >= marklimit)
364      {
365        markpos = -1;
366        pos = count = 0;
367      }
368    else
369      {
370        byte[] newbuf = buf;
371        if (markpos < bufferSize)
372          {
373            newbuf = new byte[count - markpos + bufferSize];
374          }
375        System.arraycopy(buf, markpos, newbuf, 0, count - markpos);
376        buf = newbuf;
377        count -= markpos;
378        pos -= markpos;
379        markpos = 0;
380      }
381
382    int numread = in.read(buf, count, bufferSize);
383
384    if (numread <= 0)        // EOF
385      return false;
386
387    count += numread;
388    return true;
389  }
390}