DataInput interface provides
- * for reading bytes from a binary stream and
- * reconstructing from them data in any of
- * the Java primitive types. There is also
- * a
- * facility for reconstructing a String
- * from data in
- * modified UTF-8
- * format.
- *
- * It is generally true of all the reading
- * routines in this interface that if end of
- * file is reached before the desired number
- * of bytes has been read, an EOFException
- * (which is a kind of IOException)
- * is thrown. If any byte cannot be read for
- * any reason other than end of file, an IOException
- * other than EOFException is
- * thrown. In particular, an IOException
- * may be thrown if the input stream has been
- * closed.
- *
- *
- * Implementations of the DataInput and DataOutput interfaces represent - * Unicode strings in a format that is a slight modification of UTF-8. - * (For information regarding the standard UTF-8 format, see section - * 3.9 Unicode Encoding Forms of The Unicode Standard, Version - * 4.0). - * Note that in the following tables, the most significant bit appears in the - * far left-hand column. - *
- * All characters in the range '\u0001' to
- * '\u007F' are represented by a single byte:
- *
- *
- *- * - *- *
- *- * - *- * Bit Values - *- * - *Byte 1 - *- * - *- *
- *- * - *0 - *bits 6-0 - *
- * The null character '\u0000' and characters in the
- * range '\u0080' to '\u07FF' are
- * represented by a pair of bytes:
- *
- *
- *- * - *- *
- *- * - *- * Bit Values - *- * - *Byte 1 - *- * - *- *
- *- * - *1 - *1 - *0 - *bits 10-6 - *- * - *Byte 2 - *- * - *- *
- *- * - *1 - *0 - *bits 5-0 - *
char values in the range '\u0800' to
- * '\uFFFF' are represented by three bytes:
- *
- * - *- * - *- *
- *- * - *- * Bit Values - *- * - *Byte 1 - *- * - *- *
- *- * - *1 - *1 - *1 - *0 - *bits 15-12 - *- * - *Byte 2 - *- * - *- *
- *- * - *1 - *0 - *bits 11-6 - *- * - *Byte 3 - *- * - *- *
- *- * - *1 - *0 - *bits 5-0 - *
- * The differences between this format and the - * standard UTF-8 format are the following: - *
'\u0000' is encoded in 2-byte format
- * rather than 1-byte, so that the encoded strings never have
- * embedded nulls.
- * b. The number of bytes
- * read is equal
- * to the length of b.
- * - * This method blocks until one of the - * following conditions occurs:
- *
b.length
- * bytes of input data are available, in which
- * case a normal return is made.
- *
- * EOFException
- * is thrown.
- *
- * IOException other
- * than EOFException is thrown.
- *
- * If b is null,
- * a NullPointerException is thrown.
- * If b.length is zero, then
- * no bytes are read. Otherwise, the first
- * byte read is stored into element b[0],
- * the next one into b[1], and
- * so on.
- * If an exception is thrown from
- * this method, then it may be that some but
- * not all bytes of b have been
- * updated with data from the input stream.
- *
- * @param b the buffer into which the data is read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- void readFully(byte b[]) throws IOException;
-
- /**
- *
- * Reads len
- * bytes from
- * an input stream.
- *
- * This method - * blocks until one of the following conditions - * occurs:
- *
len bytes
- * of input data are available, in which case
- * a normal return is made.
- *
- * EOFException
- * is thrown.
- *
- * IOException other
- * than EOFException is thrown.
- *
- * If b is null,
- * a NullPointerException is thrown.
- * If off is negative, or len
- * is negative, or off+len is
- * greater than the length of the array b,
- * then an IndexOutOfBoundsException
- * is thrown.
- * If len is zero,
- * then no bytes are read. Otherwise, the first
- * byte read is stored into element b[off],
- * the next one into b[off+1],
- * and so on. The number of bytes read is,
- * at most, equal to len.
- *
- * @param b the buffer into which the data is read.
- * @param off an int specifying the offset into the data.
- * @param len an int specifying the number of bytes to read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- void readFully(byte b[], int off, int len) throws IOException;
-
- /**
- * Makes an attempt to skip over
- * n bytes
- * of data from the input
- * stream, discarding the skipped bytes. However,
- * it may skip
- * over some smaller number of
- * bytes, possibly zero. This may result from
- * any of a
- * number of conditions; reaching
- * end of file before n bytes
- * have been skipped is
- * only one possibility.
- * This method never throws an EOFException.
- * The actual
- * number of bytes skipped is returned.
- *
- * @param n the number of bytes to be skipped.
- * @return the number of bytes actually skipped.
- * @exception IOException if an I/O error occurs.
- */
- int skipBytes(int n) throws IOException;
-
- /**
- * Reads one input byte and returns
- * true if that byte is nonzero,
- * false if that byte is zero.
- * This method is suitable for reading
- * the byte written by the writeBoolean
- * method of interface DataOutput.
- *
- * @return the boolean value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- boolean readBoolean() throws IOException;
-
- /**
- * Reads and returns one input byte.
- * The byte is treated as a signed value in
- * the range -128 through 127,
- * inclusive.
- * This method is suitable for
- * reading the byte written by the writeByte
- * method of interface DataOutput.
- *
- * @return the 8-bit value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- byte readByte() throws IOException;
-
- /**
- * Reads one input byte, zero-extends
- * it to type int, and returns
- * the result, which is therefore in the range
- * 0
- * through 255.
- * This method is suitable for reading
- * the byte written by the writeByte
- * method of interface DataOutput
- * if the argument to writeByte
- * was intended to be a value in the range
- * 0 through 255.
- *
- * @return the unsigned 8-bit value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- int readUnsignedByte() throws IOException;
-
- /**
- * Reads two input bytes and returns
- * a short value. Let a
- * be the first byte read and b
- * be the second byte. The value
- * returned
- * is:
- *
(short)((a << 8) | (b & 0xff))
- * writeShort method of
- * interface DataOutput.
- *
- * @return the 16-bit value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- short readShort() throws IOException;
-
- /**
- * Reads two input bytes and returns
- * an int value in the range 0
- * through 65535. Let a
- * be the first byte read and
- * b
- * be the second byte. The value returned is:
- * (((a & 0xff) << 8) | (b & 0xff))
- * writeShort method
- * of interface DataOutput if
- * the argument to writeShort
- * was intended to be a value in the range
- * 0 through 65535.
- *
- * @return the unsigned 16-bit value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- int readUnsignedShort() throws IOException;
-
- /**
- * Reads two input bytes and returns a char value.
- * Let a
- * be the first byte read and b
- * be the second byte. The value
- * returned is:
- * (char)((a << 8) | (b & 0xff))
- * writeChar method of interface
- * DataOutput.
- *
- * @return the char value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- char readChar() throws IOException;
-
- /**
- * Reads four input bytes and returns an
- * int value. Let a-d
- * be the first through fourth bytes read. The value returned is:
- *
- *
- * (((a & 0xff) << 24) | ((b & 0xff) << 16) |
- * ((c & 0xff) << 8) | (d & 0xff))
- *
- * This method is suitable
- * for reading bytes written by the writeInt
- * method of interface DataOutput.
- *
- * @return the int value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- int readInt() throws IOException;
-
- /**
- * Reads eight input bytes and returns
- * a long value. Let a-h
- * be the first through eighth bytes read.
- * The value returned is:
- *
- * (((long)(a & 0xff) << 56) |
- * ((long)(b & 0xff) << 48) |
- * ((long)(c & 0xff) << 40) |
- * ((long)(d & 0xff) << 32) |
- * ((long)(e & 0xff) << 24) |
- * ((long)(f & 0xff) << 16) |
- * ((long)(g & 0xff) << 8) |
- * ((long)(h & 0xff)))
- *
- *
- * This method is suitable
- * for reading bytes written by the writeLong
- * method of interface DataOutput.
- *
- * @return the long value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- long readLong() throws IOException;
-
- /**
- * Reads four input bytes and returns
- * a float value. It does this
- * by first constructing an int
- * value in exactly the manner
- * of the readInt
- * method, then converting this int
- * value to a float in
- * exactly the manner of the method Float.intBitsToFloat.
- * This method is suitable for reading
- * bytes written by the writeFloat
- * method of interface DataOutput.
- *
- * @return the float value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- float readFloat() throws IOException;
-
- /**
- * Reads eight input bytes and returns
- * a double value. It does this
- * by first constructing a long
- * value in exactly the manner
- * of the readlong
- * method, then converting this long
- * value to a double in exactly
- * the manner of the method Double.longBitsToDouble.
- * This method is suitable for reading
- * bytes written by the writeDouble
- * method of interface DataOutput.
- *
- * @return the double value read.
- * @exception EOFException if this stream reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
- */
- double readDouble() throws IOException;
-
- /**
- * Reads the next line of text from the input stream.
- * It reads successive bytes, converting
- * each byte separately into a character,
- * until it encounters a line terminator or
- * end of
- * file; the characters read are then
- * returned as a String. Note
- * that because this
- * method processes bytes,
- * it does not support input of the full Unicode
- * character set.
- *
- * If end of file is encountered
- * before even one byte can be read, then null
- * is returned. Otherwise, each byte that is
- * read is converted to type char
- * by zero-extension. If the character '\n'
- * is encountered, it is discarded and reading
- * ceases. If the character '\r'
- * is encountered, it is discarded and, if
- * the following byte converts to the
- * character '\n', then that is
- * discarded also; reading then ceases. If
- * end of file is encountered before either
- * of the characters '\n' and
- * '\r' is encountered, reading
- * ceases. Once reading has ceased, a String
- * is returned that contains all the characters
- * read and not discarded, taken in order.
- * Note that every character in this string
- * will have a value less than \u0100,
- * that is, (char)256.
- *
- * @return the next line of text from the input stream,
- * or null if the end of file is
- * encountered before a byte can be read.
- * @exception IOException if an I/O error occurs.
- */
- String readLine() throws IOException;
-
- /**
- * Reads in a string that has been encoded using a
- * modified UTF-8
- * format.
- * The general contract of readUTF
- * is that it reads a representation of a Unicode
- * character string encoded in modified
- * UTF-8 format; this string of characters
- * is then returned as a String.
- *
- * First, two bytes are read and used to
- * construct an unsigned 16-bit integer in
- * exactly the manner of the readUnsignedShort
- * method . This integer value is called the
- * UTF length and specifies the number
- * of additional bytes to be read. These bytes
- * are then converted to characters by considering
- * them in groups. The length of each group
- * is computed from the value of the first
- * byte of the group. The byte following a
- * group, if any, is the first byte of the
- * next group.
- *
- * If the first byte of a group
- * matches the bit pattern 0xxxxxxx
- * (where x means "may be 0
- * or 1"), then the group consists
- * of just that byte. The byte is zero-extended
- * to form a character.
- *
- * If the first byte
- * of a group matches the bit pattern 110xxxxx,
- * then the group consists of that byte a
- * and a second byte b. If there
- * is no byte b (because byte
- * a was the last of the bytes
- * to be read), or if byte b does
- * not match the bit pattern 10xxxxxx,
- * then a UTFDataFormatException
- * is thrown. Otherwise, the group is converted
- * to the character:
- *
(char)(((a& 0x1F) << 6) | (b & 0x3F))
- * 1110xxxx,
- * then the group consists of that byte a
- * and two more bytes b and c.
- * If there is no byte c (because
- * byte a was one of the last
- * two of the bytes to be read), or either
- * byte b or byte c
- * does not match the bit pattern 10xxxxxx,
- * then a UTFDataFormatException
- * is thrown. Otherwise, the group is converted
- * to the character:- *
- * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
- * 1111xxxx or the pattern
- * 10xxxxxx, then a UTFDataFormatException
- * is thrown.
- *
- * If end of file is encountered
- * at any time during this entire process,
- * then an EOFException is thrown.
- *
- * After every group has been converted to
- * a character by this process, the characters
- * are gathered, in the same order in which
- * their corresponding groups were read from
- * the input stream, to form a String,
- * which is returned.
- *
- * The writeUTF
- * method of interface DataOutput
- * may be used to write data that is suitable
- * for reading by this method.
- * @return a Unicode string.
- * @exception EOFException if this stream reaches the end
- * before reading all the bytes.
- * @exception IOException if an I/O error occurs.
- * @exception UTFDataFormatException if the bytes do not represent a
- * valid modified UTF-8 encoding of a string.
- */
- String readUTF() throws IOException;
-}