Source for java.io.InputStream

   1: /* InputStream.java -- Base class for input
   2:    Copyright (C) 1998, 1999, 2001, 2004, 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:  
  39: package java.io;
  40: 
  41: /**
  42:   * This abstract class forms the base of the hierarchy of classes that read
  43:   * input as a stream of bytes.  It provides a common set of methods for
  44:   * reading bytes from streams.  Subclasses implement and extend these
  45:   * methods to read bytes from a particular input source such as a file
  46:   * or network connection.
  47:   *
  48:   * @author Aaron M. Renn (arenn@urbanophile.com)
  49:   * @author Warren Levy (warrenl@cygnus.com)
  50:   */
  51: public abstract class InputStream implements Closeable
  52: {
  53:   /**
  54:    * Default, no-arg, public constructor
  55:    */
  56:   public InputStream()
  57:   {
  58:   }
  59: 
  60:   /**
  61:    * This method returns the number of bytes that can be read from this
  62:    * stream before a read can block.  A return of 0 indicates that blocking
  63:    * might (or might not) occur on the very next read attempt.
  64:    * <p>
  65:    * This method always returns 0 in this class
  66:    *
  67:    * @return The number of bytes that can be read before blocking could occur
  68:    *
  69:    * @exception IOException If an error occurs
  70:    */
  71:   public int available() throws IOException
  72:   {
  73:     return 0;
  74:   }
  75: 
  76:   /**
  77:    * This method closes the stream.  Any futher attempts to read from the
  78:    * stream may generate an <code>IOException</code>
  79:    * <p>
  80:    * This method does nothing in this class, but subclasses may override
  81:    * this method in order to provide additional functionality.
  82:    *
  83:    * @exception IOException If an error occurs, which can only happen
  84:    * in a subclass
  85:    */
  86:   public void close() throws IOException
  87:   {
  88:     // Do nothing
  89:   }
  90: 
  91:   /**
  92:    * This method marks a position in the input to which the stream can
  93:    * be "reset" by calling the <code>reset()</code> method.  The
  94:    * parameter @code{readlimit} is the number of bytes that can be read
  95:    * from the stream after setting the mark before the mark becomes
  96:    * invalid.  For example, if <code>mark()</code> is called with a
  97:    * read limit of 10, then when 11 bytes of data are read from the
  98:    * stream before the <code>reset()</code> method is called, then the
  99:    * mark is invalid and the stream object instance is not required to
 100:    * remember the mark.
 101:    * <p>
 102:    * This method does nothing in this class, but subclasses may override it
 103:    * to provide mark/reset functionality.
 104:    *
 105:    * @param readLimit The number of bytes that can be read before the
 106:    *                  mark becomes invalid
 107:    */
 108:   public void mark(int readLimit)
 109:   {
 110:     // Do nothing
 111:   }
 112: 
 113:   /**
 114:    * This method returns a boolean that indicates whether the mark/reset
 115:    * methods are supported in this class.  Those methods can be used to
 116:    * remember a specific point in the stream and reset the stream to that
 117:    * point.
 118:    * <p>
 119:    * This method always returns <code>false</code> in this class, but
 120:    * subclasses can override this method to return <code>true</code>
 121:    * if they support mark/reset functionality.
 122:    *
 123:    * @return <code>true</code> if mark/reset functionality is
 124:    * supported, <code>false</code> otherwise 
 125:    */
 126:   public boolean markSupported()
 127:   {
 128:     return false;
 129:   }
 130: 
 131:   /**
 132:    * This method reads an unsigned byte from the input stream and returns it
 133:    * as an int in the range of 0-255.  This method also will return -1 if
 134:    * the end of the stream has been reached.
 135:    * <p>
 136:    * This method will block until the byte can be read.
 137:    *
 138:    * @return The byte read or -1 if end of stream
 139:    *
 140:    * @exception IOException If an error occurs
 141:    */
 142:   public abstract int read() throws IOException;
 143: 
 144:   /**
 145:    * This method reads bytes from a stream and stores them into a caller
 146:    * supplied buffer.  This method attempts to completely fill the buffer,
 147:    * but can return before doing so.  The actual number of bytes read is
 148:    * returned as an int.  A -1 is returned to indicate the end of the stream.
 149:    * <p>
 150:    * This method will block until some data can be read.
 151:    * <p>
 152:    * This method operates by calling an overloaded read method like so:
 153:    * <code>read(b, 0, b.length)</code>
 154:    *
 155:    * @param b The buffer into which the bytes read will be stored.
 156:    *
 157:    * @return The number of bytes read or -1 if end of stream.
 158:    *
 159:    * @exception IOException If an error occurs.
 160:    */
 161:   public int read(byte[] b) throws IOException
 162:   {
 163:     return read(b, 0, b.length);
 164:   }
 165: 
 166:   /**
 167:    * This method read bytes from a stream and stores them into a
 168:    * caller supplied buffer.  It starts storing the data at index
 169:    * <code>off</code> into the buffer and attempts to read
 170:    * <code>len</code> bytes.  This method can return before reading the
 171:    * number of bytes requested.  The actual number of bytes read is
 172:    * returned as an int.  A -1 is returned to indicate the end of the
 173:    * stream.
 174:    *  <p>
 175:    * This method will block until some data can be read.
 176:    * <p>
 177:    * This method operates by calling the single byte <code>read()</code> method
 178:    * in a loop until the desired number of bytes are read.  The read loop
 179:    * stops short if the end of the stream is encountered or if an IOException
 180:    * is encountered on any read operation except the first.  If the first
 181:    * attempt to read a bytes fails, the IOException is allowed to propagate
 182:    * upward.  And subsequent IOException is caught and treated identically
 183:    * to an end of stream condition.  Subclasses can (and should if possible)
 184:    * override this method to provide a more efficient implementation.
 185:    *
 186:    * @param b The array into which the bytes read should be stored
 187:    * @param off The offset into the array to start storing bytes
 188:    * @param len The requested number of bytes to read
 189:    *
 190:    * @return The actual number of bytes read, or -1 if end of stream.
 191:    *
 192:    * @exception IOException If an error occurs.
 193:    */
 194:   public int read(byte[] b, int off, int len) throws IOException
 195:   {
 196:     if (off < 0 || len < 0 || b.length - off < len)
 197:       throw new IndexOutOfBoundsException();
 198: 
 199:     int i, ch;
 200: 
 201:     for (i = 0; i < len; ++i)
 202:       try
 203:     {
 204:       if ((ch = read()) < 0)
 205:         return i == 0 ? -1 : i;        // EOF
 206:       b[off + i] = (byte) ch;
 207:     }
 208:       catch (IOException ex)
 209:     {
 210:       // Only reading the first byte should cause an IOException.
 211:       if (i == 0)
 212:         throw ex;
 213:       return i;
 214:     }
 215: 
 216:     return i;
 217:   }
 218: 
 219:   /**
 220:    * This method resets a stream to the point where the
 221:    * <code>mark()</code> method was called.  Any bytes that were read
 222:    * after the mark point was set will be re-read during subsequent
 223:    * reads.
 224:    * <p>
 225:    * This method always throws an IOException in this class, but subclasses
 226:    * can override this method if they provide mark/reset functionality.
 227:    *
 228:    * @exception IOException Always thrown for this class
 229:    */
 230:   public void reset() throws IOException
 231:   {
 232:     throw new IOException("mark/reset not supported");
 233:   }
 234: 
 235:   /**
 236:    * This method skips the specified number of bytes in the stream.  It
 237:    * returns the actual number of bytes skipped, which may be less than the
 238:    * requested amount.
 239:    * <p>
 240:    * This method reads and discards bytes into a byte array until the
 241:    * specified number of bytes were skipped or until either the end of stream
 242:    * is reached or a read attempt returns a short count.  Subclasses can
 243:    * override this metho to provide a more efficient implementation where
 244:    * one exists.
 245:    *
 246:    * @param n The requested number of bytes to skip
 247:    *
 248:    * @return The actual number of bytes skipped.
 249:    *
 250:    * @exception IOException If an error occurs
 251:    */
 252:   public long skip(long n) throws IOException
 253:   {
 254:     // Throw away n bytes by reading them into a temp byte[].
 255:     // Limit the temp array to 2Kb so we don't grab too much memory.
 256:     final int buflen = n > 2048 ? 2048 : (int) n;
 257:     byte[] tmpbuf = new byte[buflen];
 258:     final long origN = n;
 259: 
 260:     while (n > 0L)
 261:       {
 262:     int numread = read(tmpbuf, 0, n > buflen ? buflen : (int) n);
 263:     if (numread <= 0)
 264:       break;
 265:     n -= numread;
 266:       }
 267: 
 268:     return origN - n;
 269:   }
 270: }