datainput.java

gcc的组建

   * host byte ordering. 
   * <p>
   * As an example, if <code>byte1</code> through <code>byte8</code> represent
   * the first eight bytes read from the stream, they will be
   * transformed to an <code>long</code> in the following manner:
   * <p>
   * <code>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) + 
   * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) + 
   * ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) + 
   * ((byte7 & 0xFF) << 8) + (byte8 & 0xFF)))
   * </code>
   * <p>
   * The value returned is in the range of -9223372036854775808 to
   * 9223372036854775807.
   * <p>
   * This method can read an <code>long</code> written by an object 
   * implementing the <code>writeLong()</code> method in the 
   * <code>DataOutput</code> interface.
   *
   * @return The <code>long</code> value read
   *
   * @exception EOFException If end of file is reached before reading the long
   * @exception IOException If any other error occurs
   *
   * @see DataOutput#writeLong
   */
  long readLong() throws EOFException, IOException;

  /**
   * This method reads a Java float value from an input stream.  It operates
   * by first reading an <code>int</code> value from the stream by calling the
   * <code>readInt()</code> method in this interface, then converts that
   * <code>int</code> to a <code>float</code> using the
   * <code>intBitsToFloat</code> method in the class
   * <code>java.lang.Float</code>.
   * <p>
   * This method can read a <code>float</code> written by an object 
   * implementing
   * the <code>writeFloat()</code> method in the <code>DataOutput</code>
   * interface.
   *
   * @return The <code>float</code> value read
   *
   * @exception EOFException If end of file is reached before reading the 
   * float
   * @exception IOException If any other error occurs
   *
   * @see DataOutput#writeFloat
   * @see java.lang.Float#intBitsToFloat
   */
  float readFloat() throws EOFException, IOException;

  /**
   * This method reads a Java double value from an input stream.  It operates
   * by first reading a <code>long</code> value from the stream by calling the
   * <code>readLong()</code> method in this interface, then converts that
   * <code>long</code> to a <code>double</code> using the
   * <code>longBitsToDouble</code> method in the class
   * <code>java.lang.Double</code>.
   * <p>
   * This method can read a <code>double</code> written by an object
   * implementing the <code>writeDouble()</code> method in the
   * <code>DataOutput</code> interface.
   *
   * @return The <code>double</code> value read
   *
   * @exception EOFException If end of file is reached before reading the 
   * double
   * @exception IOException If any other error occurs
   *
   * @see DataOutput#writeDouble
   * @see java.lang.Double#longBitsToDouble
   */
  double readDouble() throws EOFException, IOException;

  /**
   * This method reads the next line of text data from an input stream.
   * It operates by reading bytes and converting those bytes to 
   * <code>char</code>
   * values by treating the byte read as the low eight bits of the
   * <code>char</code> and using 0 as the high eight bits.  Because of this,
   * it does not support the full 16-bit Unicode character set.
   * <P>
   * The reading of bytes ends when either the end of file or a line terminator
   * is encountered.  The bytes read are then returned as a 
   * <code>String</code>.
   * A line terminator is a byte sequence consisting of either 
   * <code>\r</code>, <code>\n</code> or <code>\r\n</code>.  These termination
   * charaters are discarded and are not returned as part of the string.
   * A line is also terminated by an end of file condition.
   * <p>
   *
   * @return The line read as a <code>String</code>
   *
   * @exception IOException If an error occurs
   */
  String readLine() throws IOException;

  /**
   * This method reads a <code>String</code> from an input stream that is
   * encoded in a modified UTF-8 format.  This format has a leading two byte
   * sequence that contains the remaining number of bytes to read.  
   * This two byte
   * sequence is read using the <code>readUnsignedShort()</code> method of this
   * interface.
   *
   * After the number of remaining bytes have been determined, these bytes
   * are read an transformed into <code>char</code> values.  These
   * <code>char</code> values are encoded in the stream using either a one, 
   * two, or three byte format.
   * The particular format in use can be determined by examining the first
   * byte read.  
   * <p>
   * If the first byte has a high order bit of 0, then
   * that character consists on only one byte.  This character value consists
   * of seven bits that are at positions 0 through 6 of the byte.  As an
   * example, if <code>byte1</code> is the byte read from the stream, it would
   * be converted to a <code>char</code> like so:
   * <p>
   * <code>(char)byte1</code>
   * <p>
   * If the first byte has 110 as its high order bits, then the 
   * character consists of two bytes.  The bits that make up the character
   * value are in positions 0 through 4 of the first byte and bit positions
   * 0 through 5 of the second byte.  (The second byte should have 
   * 10 as its high order bits).  These values are in most significant
   * byte first (i.e., "big endian") order.
   * <p>
   * As an example, if <code>byte1</code> and <code>byte2</code> are the first
   * two bytes read respectively, and the high order bits of them match the
   * patterns which indicate a two byte character encoding, then they would be
   * converted to a Java <code>char</code> like so:
   * <p>
   * <code>(char)(((byte1 &amp; 0x1F) &lt;&lt; 6) + (byte2 &amp; 0x3F))</code>
   * <p>
   * If the first byte has a 1110 as its high order bits, then the
   * character consists of three bytes.  The bits that make up the character
   * value are in positions 0 through 3 of the first byte and bit positions
   * 0 through 5 of the other two bytes.  (The second and third bytes should
   * have 10 as their high order bits).  These values are in most
   * significant byte first (i.e., "big endian") order.
   * <p>
   * As an example, if <code>byte1</code>, <code>byte2</code>, and
   * <code>byte3</code> are the three bytes read, and the high order bits of
   * them match the patterns which indicate a three byte character encoding,
   * then they would be converted to a Java <code>char</code> like so:
   *
   * <code>
   * (char)(((byte1 &amp; 0x0F) &lt;&lt; 12) + ((byte2 &amp; 0x3F) + (byte3 &amp; 0x3F))
   * </code>
   *
   * Note that all characters are encoded in the method that requires the
   * fewest number of bytes with the exception of the character with the
   * value of <code>\&lt;llll&gt;u0000</code> which is encoded as two bytes.  
   * This is a modification of the UTF standard used to prevent C language 
   * style <code>NUL</code> values from appearing in the byte stream.
   * <p>
   * This method can read data that was written by an object implementing the
   * <code>writeUTF()</code> method in <code>DataOutput</code>.
   * 
   * @return The <code>String</code> read
   *
   * @exception EOFException If end of file is reached before reading the 
   * String
   * @exception UTFDataFormatException If the data is not in UTF-8 format
   * @exception IOException If any other error occurs
   *
   * @see DataOutput#writeUTF
   */
  String readUTF() throws EOFException, UTFDataFormatException, IOException;

  /**
   * This method reads raw bytes into the passed array until the array is
   * full.  Note that this method blocks until the data is available and
   * throws an exception if there is not enough data left in the stream to
   * fill the buffer.  Note also that zero length buffers are permitted.
   * In this case, the method will return immediately without reading any
   * bytes from the stream.
   *
   * @param buf The buffer into which to read the data
   *
   * @exception EOFException If end of file is reached before filling the 
   * buffer
   * @exception IOException If any other error occurs
   */
  void readFully(byte[] buf) throws EOFException, IOException;

  /**
   * This method reads raw bytes into the passed array <code>buf</code> 
   * starting
   * <code>offset</code> bytes into the buffer.  The number of bytes read 
   * will be
   * exactly <code>len</code>.  Note that this method blocks until the data is 
   * available and throws an exception if there is not enough data left in 
   * the stream to read <code>len</code> bytes.  Note also that zero length
   * buffers are permitted.  In this case, the method will return immediately
   * without reading any bytes from the stream.
   *
   * @param buf The buffer into which to read the data
   * @param offset The offset into the buffer to start storing data
   * @param len The number of bytes to read into the buffer
   *
   * @exception EOFException If end of file is reached before filling the 
   * buffer
   * @exception IOException If any other error occurs
   */
  void readFully(byte[] buf, int offset, int len) 
    throws EOFException, IOException;

  /**
   * This method skips and discards the specified number of bytes in an
   * input stream.  Note that this method may skip less than the requested
   * number of bytes.  The actual number of bytes skipped is returned.
   * No bytes are skipped if a negative number is passed to this method.
   *
   * @param numBytes The number of bytes to skip
   *
   * @return The number of bytes actually skipped, which will always be
   *         <code>numBytes</code>
   *
   * @exception EOFException If end of file is reached before all bytes can be
   *                         skipped
   * @exception IOException If any other error occurs
   */
  int skipBytes(int numBytes) throws EOFException, IOException;

} // interface DataInput