Source for java.io.ObjectInput

   1: /* ObjectInput.java -- Read object data from a stream
   2:    Copyright (C) 1998,2003 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 interface extends the <code>DataInput</code> interface to provide a
  43:   * facility to read objects as well as primitive types from a stream.  It
  44:   * also has methods that allow input to be done in a manner similar to
  45:   * <code>InputStream</code>
  46:   *
  47:   * @author Aaron M. Renn (arenn@urbanophile.com)
  48:   *
  49:   * @see DataInput
  50:   */
  51: public interface ObjectInput extends DataInput
  52: {
  53:   /**
  54:     * This method returns the number of bytes that can be read without
  55:     * blocking.
  56:     *
  57:     * @return The number of bytes available before blocking
  58:     *
  59:     * @exception IOException If an error occurs
  60:     */
  61:   int available() throws IOException;
  62: 
  63:   /**
  64:     * This method reading a byte of data from a stream.  It returns that byte
  65:     * as an <code>int</code>.  This method blocks if no data is available 
  66:     * to be read.
  67:     * 
  68:     * @return The byte of data read
  69:     *
  70:     * @exception IOException If an error occurs
  71:     */
  72:   int read() throws IOException;
  73: 
  74:   /**
  75:     * This method reads raw bytes and stores them them a byte array buffer.
  76:     * Note that this method will block if no data is available.  However, 
  77:     * it will not necessarily block until it fills the entire buffer.  That is,
  78:     * a "short count" is possible.
  79:     *
  80:     * @param buf The byte array to receive the data read
  81:     *
  82:     * @return The actual number of bytes read or -1 if end of stream
  83:     *
  84:     * @exception IOException If an error occurs
  85:     */
  86:   int read(byte[] buf) throws IOException;
  87: 
  88:   /**
  89:     * This method reads raw bytes and stores them in a byte array buffer
  90:     * <code>buf</code> starting at position <code>offset</code> into the 
  91:     * buffer.  A 
  92:     * maximum of <code>len</code> bytes will be read.  Note that this method
  93:     * blocks if no data is available, but will not necessarily block until
  94:     * it can read <code>len</code> bytes of data.  That is, a "short count" is
  95:     * possible.
  96:     *
  97:     * @param buf The byte array to receive the data read
  98:     * @param offset The offset into <code>buf</code> to start storing data
  99:     * @param len The maximum number of bytes to read
 100:     *
 101:     * @return The actual number of bytes read or -1 if end of stream
 102:     *
 103:     * @exception IOException If an error occurs
 104:     */
 105:   int read(byte[] buf, int offset, int len) throws IOException;
 106: 
 107:   /**
 108:     * Reads an object instance and returns it.  If the class for the object
 109:     * being read cannot be found, then a <code>ClassNotFoundException</code>
 110:     * will be thrown.
 111:     *
 112:     * @return The object instance that was read
 113:     *
 114:     * @exception ClassNotFoundException If a class for the object cannot be 
 115:     * found
 116:     * @exception IOException If any other error occurs
 117:     */
 118:   Object readObject() 
 119:     throws ClassNotFoundException, IOException;
 120: 
 121:   /**
 122:     * This method causes the specified number of bytes to be read and
 123:     * discarded.  It is possible that fewer than the requested number of bytes
 124:     * will actually be skipped.
 125:     *
 126:     * @param numBytes The number of bytes to skip
 127:     *
 128:     * @return The actual number of bytes skipped
 129:     *
 130:     * @exception IOException If an error occurs
 131:     */
 132:   long skip(long numBytes) throws IOException;
 133: 
 134:   /**
 135:     * This method closes the input source
 136:     *
 137:     * @exception IOException If an error occurs
 138:     */
 139:   void close() throws IOException;
 140: }