len bytes and
* will start storing them at position off into the buffer.
* This method can return a short count if there is insufficient data
* remaining to be read to complete the desired read length.
*
* @param b The buffer into which bytes will be read.
* @param off The offset into the buffer to start storing bytes.
* @param len The requested number of bytes to read.
*
* @return The actual number of bytes read, or -1 if end of stream reached
* before reading any bytes.
*
* @exception IOException If an error occurs.
*/
int read(byte[] b, int off, int len)
throws IOException;
/**
* This method reads a Java boolean value from an input stream. It does
* so by reading a single byte of data. If that byte is zero, then the
* value returned is false. If the byte is non-zero, then
* the value returned is true.
*
* This method can read a boolean written by an object
* implementing the writeBoolean() method in the
* DataOutput interface.
*
* @return The boolean value read
*
* @exception EOFException If end of file is reached before reading
* the boolean
* @exception IOException If any other error occurs
*
* @see DataOutput#writeBoolean
*/
boolean readBoolean()
throws IOException;
/**
* This method reads a Java byte value from an input stream. The value
* is in the range of -128 to 127.
*
* This method can read a byte written by an object
* implementing the writeByte() method in the
* DataOutput interface.
*
* @return The byte value read
*
* @exception EOFException If end of file is reached before reading the byte
* @exception IOException If any other error occurs
*
* @see DataOutput#writeByte
*/
byte readByte()
throws IOException;
/**
* This method reads a Java char value from an input stream.
* It operates by reading two bytes from the stream and converting them to
* a single 16-bit Java char. The two bytes are stored most
* significant byte first (i.e., "big endian") regardless of the native
* host byte ordering.
*
* As an example, if byte1 and byte2
* represent the first and second byte read from the stream
* respectively, they will be transformed to a char in
* the following manner:
*
* (char)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)
*
* This method can read a char written by an object
* implementing the writeChar() method in the
* DataOutput interface.
*
* @return The char value read
*
* @exception EOFException If end of file is reached before reading the char
* @exception IOException If any other error occurs
*
* @see DataOutput#writeChar
*/
char readChar()
throws IOException;
/**
* This method reads a Java double value from an input stream. It operates
* by first reading a long value from the stream by calling the
* readLong() method in this interface, then converts
* that long to a double using the
* longBitsToDouble method in the class
* java.lang.Double
*
* This method can read a double written by an object
* implementing the writeDouble() method in the
* DataOutput interface.
*
* @return The double 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 IOException;
/**
* This method reads a Java float value from an input stream. It
* operates by first reading an int value from the
* stream by calling the readInt() method in this
* interface, then converts that int to a
* float using the intBitsToFloat method
* in the class java.lang.Float
*
* This method can read a float written by an object
* implementing the writeFloat() method in the
* DataOutput interface.
*
* @return The float 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 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 b 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[] b)
throws IOException;
/**
* This method reads a Java int value from an input stream
* It operates by reading four bytes from the stream and converting them to
* a single Java int. The bytes are stored most
* significant byte first (i.e., "big endian") regardless of the native
* host byte ordering.
*
* As an example, if byte1 through byte4 represent
* the first four bytes read from the stream, they will be
* transformed to an int in the following manner:
*
* (int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +
* ((byte3 & 0xFF)<< 8) + (byte4 & 0xFF)))
*
* The value returned is in the range of -2147483648 to 2147483647. *
* This method can read an int written by an object
* implementing the writeInt() method in the
* DataOutput interface.
*
* @return The int value read
*
* @exception EOFException If end of file is reached before reading the int
* @exception IOException If any other error occurs
*
* @see DataOutput#writeInt
*/
int readInt()
throws IOException;
/**
* This method reads a Java long value from an input stream
* It operates by reading eight bytes from the stream and converting them to
* a single Java long. The bytes are stored most
* significant byte first (i.e., "big endian") regardless of the native
* host byte ordering.
*
* As an example, if byte1 through byte8 represent
* the first eight bytes read from the stream, they will be
* transformed to an long in the following manner:
*
* (long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) +
* ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) +
* ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) +
* ((byte7 & 0xFF) << 8) + (byte8 & 0xFF)))
*
*
* The value returned is in the range of -9223372036854775808 to * 9223372036854775807. *
* This method can read an long written by an object
* implementing the writeLong() method in the
* DataOutput interface.
*
* @return The long 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 IOException;
/**
* This method reads a signed 16-bit value into a Java in from the
* stream. It operates by reading two bytes from the stream and
* converting them to a single 16-bit Java short. The
* two bytes are stored most significant byte first (i.e., "big
* endian") regardless of the native host byte ordering.
*
* As an example, if byte1 and byte2
* represent the first and second byte read from the stream
* respectively, they will be transformed to a short. in
* the following manner:
*
* (short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF))
*
* The value returned is in the range of -32768 to 32767. *
* This method can read a short written by an object
* implementing the writeShort() method in the
* DataOutput interface.
*
* @return The short value read
*
* @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs
*
* @see DataOutput#writeShort
*/
short readShort()
throws IOException;
/**
* This method reads 8 unsigned bits into a Java int
* value from the stream. The value returned is in the range of 0 to
* 255.
*
* This method can read an unsigned byte written by an object
* implementing the writeUnsignedByte() method in the
* DataOutput interface.
*
* @return The unsigned bytes value read as a Java int.
*
* @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs
*
* @see DataOutput#writeByte
*/
int readUnsignedByte()
throws IOException;
/**
* This method reads 16 unsigned bits into a Java int value from the stream.
* It operates by reading two bytes from the stream and converting them to
* a single Java int The two bytes are stored most
* significant byte first (i.e., "big endian") regardless of the native
* host byte ordering.
*
* As an example, if byte1 and byte2
* represent the first and second byte read from the stream
* respectively, they will be transformed to an int in
* the following manner:
*
* (int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))
*
* The value returned is in the range of 0 to 65535. *
* This method can read an unsigned short written by an object
* implementing the writeUnsignedShort() method in the
* DataOutput interface.
*
* @return The unsigned short value read as a Java int
*
* @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs
*
* @see DataOutput#writeShort
*/
int readUnsignedShort()
throws IOException;
/**
* Read a single byte.
*
* @return a byte, extracted from the stream or -1 if
* EOF has been reached.
* @throws IOException
*/
public int read()
throws IOException;
/**
* This method attempts to skip and discard the specified number of bytes
* in the input stream. It may actually skip fewer bytes than requested.
* This method will not skip any bytes if passed a negative number of bytes
* to skip.
*
* @param n The requested number of bytes to skip.
*
* @return The requested number of bytes to skip.
*
* @exception IOException If an error occurs.
* @specnote The JDK docs claim that this returns the number of bytes
* actually skipped. The JCL claims that this method can throw an
* EOFException. Neither of these appear to be true in the JDK 1.3's
* implementation. This tries to implement the actual JDK behaviour.
*/
int skipBytes(int n)
throws IOException;
}