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: *

Modified UTF-8

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: * jtulach@146: * jtulach@146: *
Bit Values
Byte 1 jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
0
jtulach@146: *
bits 6-0
jtulach@146: *
jtulach@146: *
jtulach@146: *
jtulach@146: * 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: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
Bit Values
Byte 1 jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
1
jtulach@146: *
1
jtulach@146: *
0
jtulach@146: *
bits 10-6
jtulach@146: *
jtulach@146: *
Byte 2 jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
1
jtulach@146: *
0
jtulach@146: *
bits 5-0
jtulach@146: *
jtulach@146: *
jtulach@146: *
jtulach@146: * jtulach@146: *
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: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
Bit Values
Byte 1 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: *
Byte 2 jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
1
jtulach@146: *
0
jtulach@146: *
bits 11-6
jtulach@146: *
jtulach@146: *
Byte 3 jtulach@146: * jtulach@146: * jtulach@146: * jtulach@146: *
1
jtulach@146: *
0
jtulach@146: *
bits 5-0
jtulach@146: *
jtulach@146: *
jtulach@146: *
jtulach@146: * jtulach@146: *

jtulach@146: * The differences between this format and the jtulach@146: * standard UTF-8 format are the following: jtulach@146: *

jtulach@146: * @author Frank Yellin jtulach@146: * @see java.io.DataInputStream jtulach@146: * @see java.io.DataOutput jtulach@146: * @since JDK1.0 jtulach@146: */ jtulach@146: public jtulach@146: interface DataInput { jtulach@146: /** jtulach@146: * Reads some bytes from an input jtulach@146: * stream and stores them into the buffer jtulach@146: * array 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: *

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: *

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: }