libjava/java/io/ObjectInput.java

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