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