Robust/src/ClassLibrary/SSJava/PushbackInputStream.java

   1 /* PushbackInputStream.java -- An input stream that can unread bytes
   2    Copyright (C) 1998, 1999, 2001, 2002, 2005  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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 @LATTICE("IN<T,IN<POS,POS<SH,SH<F,SH*,POS*")
  55 @METHODDEFAULT("OUT<SH,SH<IN,SH*,THISLOC=OUT,GLOBALLOC=OUT")
  56 public class PushbackInputStream extends FilterInputStream
  57 {
  58   /**
  59    * This is the default buffer size
  60    */
  61   @LOC("F") private static final int DEFAULT_BUFFER_SIZE = 1;
  62
  63   /**
  64    * This is the buffer that is used to store the pushed back data
  65    */
  66   @LOC("SH") protected byte[] buf;
  67
  68   /**
  69    * This is the position in the buffer from which the next byte will be
  70    * read.  Bytes are stored in reverse order in the buffer, starting from
  71    * <code>buf[buf.length - 1]</code> to <code>buf[0]</code>.  Thus when
  72    * <code>pos</code> is 0 the buffer is full and <code>buf.length</code> when
  73    * it is empty
  74    */
  75   @LOC("POS") protected int pos;
  76
  77   /**
  78    * This method initializes a <code>PushbackInputStream</code> to
  79    * read from the specified subordinate <code>InputStream</code>
  80    * with a default pushback buffer size of 1.
  81    *
  82    * @param in The subordinate stream to read from
  83    */
  84   public PushbackInputStream(InputStream in)
  85   {
  86     this(in, DEFAULT_BUFFER_SIZE);
  87   }
  88
  89   /**
  90    * This method initializes a <code>PushbackInputStream</code> to
  91    * read from the specified subordinate <code>InputStream</code> with
  92    * the specified buffer size
  93    *
  94    * @param in The subordinate <code>InputStream</code> to read from
  95    * @param size The pushback buffer size to use
  96    */
  97     public PushbackInputStream(@LOC("IN")InputStream in, @LOC("IN")int size)
  98   {
  99     super(in);
 100     if (size < 0)
 101       throw new IllegalArgumentException();
 102     buf = new byte[size];
 103     pos = buf.length;
 104   }
 105
 106   /**
 107    * This method returns the number of bytes that can be read from this
 108    * stream before a read can block.  A return of 0 indicates that blocking
 109    * might (or might not) occur on the very next read attempt.
 110    * <p>
 111    * This method will return the number of bytes available from the
 112    * pushback buffer plus the number of bytes available from the
 113    * underlying stream.
 114    *
 115    * @return The number of bytes that can be read before blocking could occur
 116    *
 117    * @exception IOException If an error occurs
 118    */
 119   public int available() throws IOException
 120   {
 121     try
 122       {
 123         return (buf.length - pos) + super.available();
 124       }
 125     catch (NullPointerException npe)
 126       {
 127         throw new IOException ("Stream closed");
 128       }
 129   }
 130
 131   /**
 132    * This method closes the stream and releases any associated resources.
 133    *
 134    * @exception IOException If an error occurs.
 135    */
 136   public synchronized void close() throws IOException
 137   {
 138     buf = null;
 139     super.close();
 140   }
 141
 142   /**
 143    * This method returns <code>false</code> to indicate that it does
 144    * not support mark/reset functionality.
 145    *
 146    * @return This method returns <code>false</code> to indicate that
 147    * this class does not support mark/reset functionality
 148    */
 149   public boolean markSupported()
 150   {
 151     return false;
 152   }
 153
 154   /**
 155    * This method always throws an IOException in this class because
 156    * mark/reset functionality is not supported.
 157    *
 158    * @exception IOException Always thrown for this class
 159    */
 160   public void reset() throws IOException
 161   {
 162     throw new IOException("Mark not supported in this class");
 163   }
 164
 165   /**
 166    * This method reads an unsigned byte from the input stream and returns it
 167    * as an int in the range of 0-255.  This method also will return -1 if
 168    * the end of the stream has been reached.  The byte returned will be read
 169    * from the pushback buffer, unless the buffer is empty, in which case
 170    * the byte will be read from the underlying stream.
 171    * <p>
 172    * This method will block until the byte can be read.
 173    *
 174    * @return The byte read or -1 if end of stream
 175    *
 176    * @exception IOException If an error occurs
 177    */
 178   public synchronized int read() throws IOException
 179   {
 180     if (pos < buf.length)
 181       return ((int) buf[pos++]) & 0xFF;
 182
 183     return super.read();
 184   }
 185
 186   /**
 187    * This method read bytes from a stream and stores them into a
 188    * caller supplied buffer.  It starts storing the data at index
 189    * <code>offset</code> into the buffer and attempts to read
 190    * <code>len</code> bytes.  This method can return before reading the
 191    * number of bytes requested.  The actual number of bytes read is
 192    * returned as an int.  A -1 is returned to indicate the end of the
 193    * stream.
 194    *  <p>
 195    * This method will block until some data can be read.
 196    * <p>
 197    * This method first reads bytes from the pushback buffer in order to
 198    * satisfy the read request.  If the pushback buffer cannot provide all
 199    * of the bytes requested, the remaining bytes are read from the
 200    * underlying stream.
 201    *
 202    * @param b The array into which the bytes read should be stored
 203    * @param off The offset into the array to start storing bytes
 204    * @param len The requested number of bytes to read
 205    *
 206    * @return The actual number of bytes read, or -1 if end of stream.
 207    *
 208    * @exception IOException If an error occurs.
 209    */
 210   @LATTICE("OUT<THIS,THISLOC=THIS")
 211   @RETURNLOC("THIS")
 212   public synchronized int read(@LOC("OUT") byte[] b,
 213                                @LOC("THIS,PushbackInputStream.POS") int off,
 214                                @LOC("THIS,PushbackInputStream.POS") int len) throws IOException
 215   {
 216     @LOC("THIS,PushbackInputStream.POS") int numBytes = Math.min(buf.length - pos,len);
 217
 218     if (numBytes > 0)
 219       {
 220         System.arraycopy (buf, pos, b, off, numBytes);
 221         pos += numBytes;
 222         len -= numBytes;
 223         off += numBytes;
 224       }
 225
 226     if (len > 0)
 227       {
 228         len = super.read(b, off, len);
 229         if (len == -1) //EOF
 230           return numBytes > 0 ? numBytes : -1;
 231         numBytes += len;
 232       }
 233     return numBytes;
 234   }
 235
 236   /**
 237    * This method pushes a single byte of data into the pushback buffer.
 238    * The byte pushed back is the one that will be returned as the first byte
 239    * of the next read.
 240    * <p>
 241    * If the pushback buffer is full, this method throws an exception.
 242    * <p>
 243    * The argument to this method is an <code>int</code>.  Only the low
 244    * eight bits of this value are pushed back.
 245    *
 246    * @param b The byte to be pushed back, passed as an int
 247    *
 248    * @exception IOException If the pushback buffer is full.
 249    */
 250   public synchronized void unread(int b) throws IOException
 251   {
 252     if (pos <= 0)
 253       throw new IOException("Insufficient space in pushback buffer");
 254
 255     buf[--pos] = (byte) b;
 256   }
 257
 258   /**
 259    * This method pushes all of the bytes in the passed byte array into
 260    * the pushback bfer.  These bytes are pushed in reverse order so that
 261    * the next byte read from the stream after this operation will be
 262    * <code>b[0]</code> followed by <code>b[1]</code>, etc.
 263    * <p>
 264    * If the pushback buffer cannot hold all of the requested bytes, an
 265    * exception is thrown.
 266    *
 267    * @param b The byte array to be pushed back
 268    *
 269    * @exception IOException If the pushback buffer is full
 270    */
 271   public synchronized void unread(byte[] b) throws IOException
 272   {
 273     unread(b, 0, b.length);
 274   }
 275
 276   /**
 277    * This method pushed back bytes from the passed in array into the
 278    * pushback buffer.  The bytes from <code>b[offset]</code> to
 279    * <code>b[offset + len]</code> are pushed in reverse order so that
 280    * the next byte read from the stream after this operation will be
 281    * <code>b[offset]</code> followed by <code>b[offset + 1]</code>,
 282    * etc.
 283    * <p>
 284    * If the pushback buffer cannot hold all of the requested bytes, an
 285    * exception is thrown.
 286    *
 287    * @param b The byte array to be pushed back
 288    * @param off The index into the array where the bytes to be push start
 289    * @param len The number of bytes to be pushed.
 290    *
 291    * @exception IOException If the pushback buffer is full
 292    */
 293   public synchronized void unread(@LOC("IN") byte[] b, @LOC("IN") int off, @LOC("IN") int len)
 294     throws IOException
 295   {
 296     if (pos < len)
 297       throw new IOException("Insufficient space in pushback buffer");
 298
 299     // Note the order that these bytes are being added is the opposite
 300     // of what would be done if they were added to the buffer one at a time.
 301     // See the Java Class Libraries book p. 1390.
 302     System.arraycopy(b, off, buf, pos - len, len);
 303
 304     // Don't put this into the arraycopy above, an exception might be thrown
 305     // and in that case we don't want to modify pos.
 306     pos -= len;
 307   }
 308
 309   /**
 310    * This method skips the specified number of bytes in the stream.  It
 311    * returns the actual number of bytes skipped, which may be less than the
 312    * requested amount.
 313    * <p>
 314    * This method first discards bytes from the buffer, then calls the
 315    * <code>skip</code> method on the underlying <code>InputStream</code> to
 316    * skip additional bytes if necessary.
 317    *
 318    * @param n The requested number of bytes to skip
 319    *
 320    * @return The actual number of bytes skipped.
 321    *
 322    * @exception IOException If an error occurs
 323    *
 324    * @since 1.2
 325    */
 326   public synchronized long skip(long n) throws IOException
 327   {
 328     final long origN = n;
 329
 330     if (n > 0L)
 331       {
 332         int numread = (int) Math.min((long) (buf.length - pos), n);
 333         pos += numread;
 334         n -= numread;
 335         if (n > 0)
 336           n -= super.skip(n);
 337       }
 338
 339     return origN - n;
 340   }
 341 }