001    /* BufferedInputStream.java -- An input stream that implements buffering
002       Copyright (C) 1998, 1999, 2001, 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038     
039    package 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     */
066    public 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    }