libjava/java/io/PushbackInputStream.java

   1 /* PushbackInputStream.java -- An input stream that can unread bytes
   2    Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.io;
  39
  40 /**
  41   * This subclass of <code>FilterInputStream</code> provides the ability to
  42   * unread data from a stream.  It maintains an internal buffer of unread
  43   * data that is supplied to the next read operation.  This is conceptually
  44   * similar to mark/reset functionality, except that in this case the
  45   * position to reset the stream to does not need to be known in advance.
  46   * <p>
  47   * The default pushback buffer size one byte, but this can be overridden
  48   * by the creator of the stream.
  49   * <p>
  50   *
  51   * @author Aaron M. Renn (arenn@urbanophile.com)
  52   * @author Warren Levy <warrenl@cygnus.com>
  53   */
  54 public class PushbackInputStream extends FilterInputStream
  55 {
  56   /**
  57    * This is the default buffer size
  58    */
  59   private static final int DEFAULT_BUFFER_SIZE = 1;
  60
  61   /**
  62    * This is the buffer that is used to store the pushed back data
  63    */
  64   protected byte[] buf;
  65
  66   /**
  67    * This is the position in the buffer from which the next byte will be
  68    * read.  Bytes are stored in reverse order in the buffer, starting from
  69    * <code>buf[buf.length - 1]</code> to <code>buf[0]</code>.  Thus when
  70    * <code>pos</code> is 0 the buffer is full and <code>buf.length</code> when
  71    * it is empty
  72    */
  73   protected int pos;
  74
  75   /**
  76    * This method initializes a <code>PushbackInputStream</code> to
  77    * read from the specified subordinate <code>InputStream</code>
  78    * with a default pushback buffer size of 1.
  79    *
  80    * @param in The subordinate stream to read from
  81    */
  82   public PushbackInputStream(InputStream in)
  83   {
  84     this(in, DEFAULT_BUFFER_SIZE);
  85   }
  86
  87   /**
  88    * This method initializes a <code>PushbackInputStream</code> to
  89    * read from the specified subordinate <code>InputStream</code> with
  90    * the specified buffer size
  91    *
  92    * @param in The subordinate <code>InputStream</code> to read from
  93    * @param size The pushback buffer size to use
  94    */
  95   public PushbackInputStream(InputStream in, int size)
  96   {
  97     super(in);
  98     if (size < 0)
  99       throw new IllegalArgumentException();
 100     buf = new byte[size];
 101     pos = buf.length;
 102   }
 103
 104   /**
 105    * This method returns the number of bytes that can be read from this
 106    * stream before a read can block.  A return of 0 indicates that blocking
 107    * might (or might not) occur on the very next read attempt.
 108    * <p>
 109    * This method will return the number of bytes available from the
 110    * pushback buffer plus the number of bytes available from the
 111    * underlying stream.
 112    *
 113    * @return The number of bytes that can be read before blocking could occur
 114    *
 115    * @exception IOException If an error occurs
 116    */
 117   public int available() throws IOException
 118   {
 119     return (buf.length - pos) + super.available();
 120   }
 121
 122   /**
 123    * This method closes the stream and releases any associated resources.
 124    *
 125    * @exception IOException If an error occurs.
 126    */
 127   public synchronized void close() throws IOException
 128   {
 129     buf = null;
 130     super.close();
 131   }
 132
 133   /**
 134    * This method returns <code>false</code> to indicate that it does
 135    * not support mark/reset functionality.
 136    *
 137    * @return This method returns <code>false</code> to indicate that
 138    * this class does not support mark/reset functionality
 139    */
 140   public boolean markSupported()
 141   {
 142     return false;
 143   }
 144
 145   /**
 146    * This method always throws an IOException in this class because
 147    * mark/reset functionality is not supported.
 148    *
 149    * @exception IOException Always thrown for this class
 150    */
 151   public void reset() throws IOException
 152   {
 153     throw new IOException("Mark not supported in this class");
 154   }
 155
 156   /**
 157    * This method reads an unsigned byte from the input stream and returns it
 158    * as an int in the range of 0-255.  This method also will return -1 if
 159    * the end of the stream has been reached.  The byte returned will be read
 160    * from the pushback buffer, unless the buffer is empty, in which case
 161    * the byte will be read from the underlying stream.
 162    * <p>
 163    * This method will block until the byte can be read.
 164    *
 165    * @return The byte read or -1 if end of stream
 166    *
 167    * @exception IOException If an error occurs
 168    */
 169   public synchronized int read() throws IOException
 170   {
 171     if (pos < buf.length)
 172       return ((int) buf[pos++]) & 0xFF;
 173
 174     return super.read();
 175   }
 176
 177   /**
 178    * This method read bytes from a stream and stores them into a
 179    * caller supplied buffer.  It starts storing the data at index
 180    * <code>offset</code> into the buffer and attempts to read
 181    * <code>len</code> bytes.  This method can return before reading the
 182    * number of bytes requested.  The actual number of bytes read is
 183    * returned as an int.  A -1 is returned to indicate the end of the
 184    * stream.
 185    *  <p>
 186    * This method will block until some data can be read.
 187    * <p>
 188    * This method first reads bytes from the pushback buffer in order to
 189    * satisfy the read request.  If the pushback buffer cannot provide all
 190    * of the bytes requested, the remaining bytes are read from the
 191    * underlying stream.
 192    *
 193    * @param b The array into which the bytes read should be stored
 194    * @param off The offset into the array to start storing bytes
 195    * @param len The requested number of bytes to read
 196    *
 197    * @return The actual number of bytes read, or -1 if end of stream.
 198    *
 199    * @exception IOException If an error occurs.
 200    */
 201   public synchronized int read(byte[] b, int off, int len) throws IOException
 202   {
 203     int numBytes = Math.min(buf.length - pos, len);
 204
 205     if (numBytes > 0)
 206       {
 207         System.arraycopy (buf, pos, b, off, numBytes);
 208         pos += numBytes;
 209         len -= numBytes;
 210         off += numBytes;
 211       }
 212
 213     if (len > 0)
 214       {
 215         len = super.read(b, off, len);
 216         if (len == -1) //EOF
 217           return numBytes > 0 ? numBytes : -1;
 218         numBytes += len;
 219       }
 220     return numBytes;
 221   }
 222
 223   /**
 224    * This method pushes a single byte of data into the pushback buffer.
 225    * The byte pushed back is the one that will be returned as the first byte
 226    * of the next read.
 227    * <p>
 228    * If the pushback buffer is full, this method throws an exception.
 229    * <p>
 230    * The argument to this method is an <code>int</code>.  Only the low
 231    * eight bits of this value are pushed back.
 232    *
 233    * @param b The byte to be pushed back, passed as an int
 234    *
 235    * @exception IOException If the pushback buffer is full.
 236    */
 237   public synchronized void unread(int b) throws IOException
 238   {
 239     if (pos <= 0)
 240       throw new IOException("Insufficient space in pushback buffer");
 241
 242     buf[--pos] = (byte) b;
 243   }
 244
 245   /**
 246    * This method pushes all of the bytes in the passed byte array into
 247    * the pushback bfer.  These bytes are pushed in reverse order so that
 248    * the next byte read from the stream after this operation will be
 249    * <code>b[0]</code> followed by <code>b[1]</code>, etc.
 250    * <p>
 251    * If the pushback buffer cannot hold all of the requested bytes, an
 252    * exception is thrown.
 253    *
 254    * @param b The byte array to be pushed back
 255    *
 256    * @exception IOException If the pushback buffer is full
 257    */
 258   public synchronized void unread(byte[] b) throws IOException
 259   {
 260     unread(b, 0, b.length);
 261   }
 262
 263   /**
 264    * This method pushed back bytes from the passed in array into the
 265    * pushback buffer.  The bytes from <code>b[offset]</code> to
 266    * <cdoe>b[offset + len]</code> are pushed in reverse order so that
 267    * the next byte read from the stream after this operation will be
 268    * <code>b[offset]</code> followed by <code>b[offset + 1]</code>,
 269    * etc.
 270    * <p>
 271    * If the pushback buffer cannot hold all of the requested bytes, an
 272    * exception is thrown.
 273    *
 274    * @param b The byte array to be pushed back
 275    * @param off The index into the array where the bytes to be push start
 276    * @param len The number of bytes to be pushed.
 277    *
 278    * @exception IOException If the pushback buffer is full
 279    */
 280   public synchronized void unread(byte[] b, int off, int len)
 281     throws IOException
 282   {
 283     if (pos < len)
 284       throw new IOException("Insufficient space in pushback buffer");
 285
 286     // Note the order that these bytes are being added is the opposite
 287     // of what would be done if they were added to the buffer one at a time.
 288     // See the Java Class Libraries book p. 1390.
 289     System.arraycopy(b, off, buf, pos - len, len);
 290
 291     // Don't put this into the arraycopy above, an exception might be thrown
 292     // and in that case we don't want to modify pos.
 293     pos -= len;
 294   }
 295
 296   /**
 297    * This method skips the specified number of bytes in the stream.  It
 298    * returns the actual number of bytes skipped, which may be less than the
 299    * requested amount.
 300    * <p>
 301    * This method first discards bytes from the buffer, then calls the
 302    * <code>skip</code> method on the underlying <code>InputStream</code> to
 303    * skip additional bytes if necessary.
 304    *
 305    * @param numBytes The requested number of bytes to skip
 306    *
 307    * @return The actual number of bytes skipped.
 308    *
 309    * @exception IOException If an error occurs
 310    *
 311    * @since 1.2
 312    */
 313   public synchronized long skip(long n) throws IOException
 314   {
 315     final long origN = n;
 316
 317     if (n > 0L)
 318       {
 319         int numread = (int) Math.min((long) (buf.length - pos), n);
 320         pos += numread;
 321         n -= numread;
 322         if (n > 0)
 323           n -= super.skip(n);
 324       }
 325
 326     return origN - n;
 327   }
 328 }