Being Code Expert: DataInput interface in Java

java.io.DataInput

The DataInput interface provides for reading bytes from a binary stream and reconstructing from the data in any of the Java primitive types. There is also a facility for reconstructing a String from data that is modified in UTF-8 format.

It is generally true of all the reading routines in this interface that if the end of the file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown.

The differences between this format and the standard UTF-8 format are the

following:

1. The null byte '\u005Cu0000' is encoded in 2-byte format rather than 1-byte, so that the encoded strings never have embedded nulls.

2. Only the 1-byte, 2-byte, and 3-byte formats are used.

3. Supplementary characters are represented in the form of surrogate pairs.

Sub interfaces:

ImageInputStream, ImageOutputStream, ObjectInput

Implementing Classes:

DataInputStream, FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream, ObjectInputStream, RandomAccessFile

Declaration

public interface DataInput {

        void readFully(byte b[]) throws IOException;

        void readFully(byte b[], int off, int len) throws IOException;

        int skipBytes(int n) throws IOException;

        boolean readBoolean() throws IOException;

        byte readByte() throws IOException;

        int readUnsignedByte() throws IOException;

        short readShort() throws IOException;

        int readUnsignedShort() throws IOException;

        char readChar() throws IOException;

        int readInt() throws IOException;

        long readLong() throws IOException;

        float readFloat() throws IOException;

        double readDouble() throws IOException;

        String readLine() throws IOException;

        String readUTF() throws IOException;
}

Methods of DataInput Interface.

1. readFully(byte[] b):

void java.io.DataInput.readFully(byte[] b) throws IOException

Reads some bytes from an input stream and stores them into the buffer array b. The number of bytes reads is equal to the length of b.

This method blocks until one of the following conditions occurs:

1. b.lengthbytes of input data are available, in which case a normal return is made.

2. End of file is detected, in which case an EOFException is thrown.

3. An I/O error occurs, in which case an IOException other than EOFException is thrown.

Parameters: b the buffer into which the data is read

Throws:

NullPointerException - if b is null.

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

2. readFully(byte[] b, int off, int len)

void java.io.DataInput.readFully(byte[] b, int off, int len) throws IOException

Reads len bytes from an input stream.

This method blocks until one of the following conditions occurs:

1. len bytes of input data are available, in which case a normal return is made.

2. End of file is detected, in which case an EOFException is thrown.

3. An I/O error occurs, in which case an IOException other than EOFException is thrown.

Parameters:

b: the buffer into which the data is read.

off: an int specifying the offset in the data array b.

len: an int specifying the number of bytes to read.

Throws:

NullPointerException - if b is null.

IndexOutOfBoundsException - if off is negative, len is negative, or len is greater than b.length - off.

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

3. skipBytes(int n)

int java.io.DataInput.skipBytes(int n) throws IOException

Makes an attempt to skip over n bytes of data from the input stream, discarding the skipped bytes.

Parameters:

n: the number of bytes to be skipped.

Returns: the number of bytes actually skipped.

Throws:

IOException - if an I/O error occurs.

4. readBoolean()

boolean java.io.DataInput.readBoolean() throws IOException

Reads one input byte and returns true if that byte is non-zero, and false if that byte is zero.

Returns: the boolean value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

5. readByte()

byte java.io.DataInput.readByte() throws IOException

Reads and returns one input byte. The byte is treated as a signed value in the range -128 through 127, inclusive.

Returns: the 8-bit value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

6. readUnsignedByte()

int java.io.DataInput.readUnsignedByte() throws IOException

Reads one input byte, zero-extends it to type int, and returns the result, which is therefore in the range 0through 255.

Returns: the unsigned 8-bit value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

7. readShort()

short java.io.DataInput.readShort() 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)).

Returns: the 16-bit value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

8. readUnsignedShort()

int java.io.DataInput.readUnsignedShort() throws IOException

Reads two input bytes and returns an int value in the range 0through 65535.

Let a be the first-byte read and b be the second byte.

The value returned is: (((a & 0xff) << 8) | (b & 0xff)).

Returns: the unsigned 16-bit value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

9. readChar()

char java.io.DataInput.readChar() 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))

Returns: the char value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

10. readInt()

int java.io.DataInput.readInt() 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)).

Returns: the int value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

11. readLong()

long java.io.DataInput.readLong() throws IOException

Reads eight input bytes and returns a long value. Let a-h be the first through eighth bytes read.

Returns: the long value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

12. readFloat()

float java.io.DataInput.readFloat() throws IOException

Reads four input bytes and returns a float value.

Returns: the float value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

13. readDouble()

double java.io.DataInput.readDouble() throws IOException

Reads eight input bytes and returns a double value.

Returns: the double value read.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

14. readLine()

String java.io.DataInput.readLine() 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 a file; the characters read are then returned as a String.

Returns: the next line of text from the input stream, or null if the end of the file is encountered before a byte can be read.

Throws:

IOException - if an I/O error occurs.

15. readUTF()

String java.io.DataInput.readUTF() 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.

Returns: a Unicode string.

Throws:

EOFException - if this stream reaches the end before reading all the bytes.

IOException - if an I/O error occurs.

UTFDataFormatException - if the bytes do not represent a valid modified UTF-8 encoding of a string.

Closeable interface in java

Externalizable interface in Java

Flushable interface in Java

FilenameFilter interface in Java

FileFilter interface in Java

DataInput interface in Java

Serializable interface in Java