    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class java.io.DataInputStream

    java.lang.Object
       |
       +----java.io.InputStream
               |
               +----java.io.FilterInputStream
                       |
                       +----java.io.DataInputStream

public class DataInputStream
extends FilterInputStream
implements DataInput

A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. An application uses a data output stream to write data that can later be read by a data input stream.

Data input streams and data output streams represent Unicode strings in a format that is a slight modification of UTF-8. (For more information, see X/Open Company Ltd., "File System Safe UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification, Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.)

All characters in the range `'\u0001'` to `'\u007F'` are represented by a single byte:

0 | bits 0-7

The null character `'\u0000'` and characters in the range `'\u0080'` to `'\u07FF'` are represented by a pair of bytes:

1 | 1 | 0 | bits 6-10
1 | 0 | bits 0-5

Characters in the range `'\u0800'` to `'\uFFFF'` are represented by three bytes:

1 | 1 | 1 | 0 | bits 12-15
1 | 0 | bits 6-11
1 | 0 | bits 0-5

The two differences between this format and the "standard" UTF-8 format are the following:

- The null byte `'\u0000'` is encoded in 2-byte format rather than 1-byte, so that the encoded strings never have embedded nulls.
- Only the 1-byte, 2-byte, and 3-byte formats are used.

See Also:
  DataOutputStream

##

DataInputStream(InputStream)
  Creates a new data input stream to read data from the specified input stream.

##

read(byte[])
  Reads up to `byte.length` bytes of data from this data input stream into an array of bytes.
read(byte[], int, int)
  Reads up to `len` bytes of data from this data input stream into an array of bytes.
readBoolean()
  Reads a `boolean` from this data input stream.
readByte()
  Reads a signed 8-bit value from this data input stream.
readChar()
  Reads a Unicode character from this data input stream.
readDouble()
  Reads a `double` from this data input stream.
readFloat()
  Reads a `float` from this data input stream.
readFully(byte[])
  Reads `b.length` bytes from this data input stream into the byte array.
readFully(byte[], int, int)
  Reads exactly `len` bytes from this data input stream into the byte array.
readInt()
  Reads a signed 32-bit integer from this data input stream.
readLine()
  Reads the next line of text from this data input stream. Deprecated.
readLong()
  Reads a signed 64-bit integer from this data input stream.
readShort()
  Reads a signed 16-bit number from this data input stream.
readUnsignedByte()
  Reads an unsigned 8-bit number from this data input stream.
readUnsignedShort()
  Reads an unsigned 16-bit number from this data input stream.
readUTF()
  Reads in a string that has been encoded using a modified UTF-8 format from this data input stream.
readUTF(DataInput)
  Reads in a string from the specified data input stream.
skipBytes(int)
  Skips exactly `n` bytes of input in the underlying input stream.

##

DataInputStream

     public DataInputStream(InputStream in)

  Creates a new data input stream to read data from the specified input stream.

  Parameters:
    in - the input stream.

##

read

     public final int read(byte b[]) throws IOException

  Reads up to `byte.length` bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.

  The `read` method of `DataInputStream` calls the `read` method of its underlying input stream with the three arguments `b`, `0`, and `b.length` and returns whatever value that method returns.

  Parameters:
    b - the buffer into which the data is read.
  Returns:
    the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the stream has been reached.
  Throws: IOException
    if an I/O error occurs.
  Overrides:
    read in class FilterInputStream
  See Also:
    in, read

read

     public final int read(byte b[],
                           int off,
                           int len) throws IOException

  Reads up to `len` bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.

  The `read` method of `DataInputStream` calls the `read` method of its underlying input stream with the same arguments and returns whatever value that method returns.

  Parameters:
    b - the buffer into which the data is read.
    off - the start offset of the data.
    len - the maximum number of bytes read.
  Returns:
    the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the stream has been reached.
  Throws: IOException
    if an I/O error occurs.
  Overrides:
    read in class FilterInputStream
  See Also:
    in, read

readFully

     public final void readFully(byte b[]) throws IOException

  Reads `b.length` bytes from this data input stream into the byte array. This method reads repeatedly from the underlying stream until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

  Parameters:
    b - the buffer into which the data is read.
  Throws: EOFException
    if this input stream reaches the end before reading all the bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readFully

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

  Reads exactly `len` bytes from this data input stream into the byte array. This method reads repeatedly from the underlying stream until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

  Parameters:
    b - the buffer into which the data is read.
    off - the start offset of the data.
    len - the number of bytes to read.
  Throws: EOFException
    if this input stream reaches the end before reading all the bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

skipBytes

     public final int skipBytes(int n) throws IOException

  Skips exactly `n` bytes of input in the underlying input stream. This method blocks until all the bytes are skipped, the end of the stream is detected, or an exception is thrown.

  Parameters:
    n - the number of bytes to be skipped.
  Returns:
    the number of bytes skipped, which is always `n`.
  Throws: EOFException
    if this input stream reaches the end before skipping all the bytes.
  Throws: IOException
    if an I/O error occurs.

readBoolean

     public final boolean readBoolean() throws IOException

  Reads a `boolean` from this data input stream. This method reads a single byte from the underlying input stream. A value of `0` represents `false`. Any other value represents `true`. This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the `boolean` value read.
  Throws: EOFException
    if this input stream has reached the end.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readByte

     public final byte readByte() throws IOException

  Reads a signed 8-bit value from this data input stream. This method reads a byte from the underlying input stream. If the byte read is `b`, where 0 <= `b` <= 255, then the result is:
  `(byte)(b)`

  This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next byte of this input stream as a signed 8-bit `byte`.
  Throws: EOFException
    if this input stream has reached the end.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readUnsignedByte

     public final int readUnsignedByte() throws IOException

  Reads an unsigned 8-bit number from this data input stream. This method reads a byte from this data input stream's underlying input stream and returns that byte. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next byte of this input stream, interpreted as an unsigned 8-bit number.
  Throws: EOFException
    if this input stream has reached the end.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readShort

     public final short readShort() throws IOException

  Reads a signed 16-bit number from this data input stream. The method reads two bytes from the underlying input stream. If the two bytes read, in order, are `b1` and `b2`, where each of the two values is between `0` and `255`, inclusive, then the result is equal to:
  `(short)((b1 << 8) | b2)`

  This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next two bytes of this input stream, interpreted as a signed 16-bit number.
  Throws: EOFException
    if this input stream reaches the end before reading two bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readUnsignedShort

     public final int readUnsignedShort() throws IOException

  Reads an unsigned 16-bit number from this data input stream. This method reads two bytes from the underlying input stream. If the bytes read, in order, are `b1` and `b2`, where `0 <= b1`, `b2 <= 255`, then the result is equal to:
  `(b1 << 8) | b2`

  This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next two bytes of this input stream, interpreted as an unsigned 16-bit integer.
  Throws: EOFException
    if this input stream reaches the end before reading two bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readChar

     public final char readChar() throws IOException

  Reads a Unicode character from this data input stream. This method reads two bytes from the underlying input stream. If the bytes read, in order, are `b1` and `b2`, where 0 <= `b1`, `b1` <= 255, then the result is equal to:
  `(char)((b1 << 8) | b2)`

  This method blocks until either the two bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next two bytes of this input stream as a Unicode character.
  Throws: EOFException
    if this input stream reaches the end before reading two bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readInt

     public final int readInt() throws IOException

  Reads a signed 32-bit integer from this data input stream. This method reads four bytes from the underlying input stream. If the bytes read, in order, are `b1`, `b2`, `b3`, and `b4`, where 0 <= `b1`, `b2`, `b3`, `b4` <= 255, then the result is equal to:
  `(b1 << 24) | (b2 << 16) + (b3 << 8) +b4`

  This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next four bytes of this input stream, interpreted as an `int`.
  Throws: EOFException
    if this input stream reaches the end before reading four bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readLong

     public final long readLong() throws IOException

  Reads a signed 64-bit integer from this data input stream. This method reads eight bytes from the underlying input stream. If the bytes read, in order, are `b1`, `b2`, `b3`, `b4`, `b5`, `b6`, `b7`, and `b8`, where
  `0 <= b1, b2, b3, b4, b5, b6, b7, b8 <= 255,`

  then the result is equal to:

  >          ((long)b1 << 56) + ((long)b2 << 48) +
  >             ((long)b3 << 40) + ((long)b4 << 32) +
  >             ((long)b5 << 24) + (b6 << 16) +
  >             (b7 << 8) + b8

  This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next eight bytes of this input stream, interpreted as a `long`.
  Throws: EOFException
    if this input stream reaches the end before reading eight bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    in

readFloat

     public final float readFloat() throws IOException

  Reads a `float` from this data input stream. This method reads an `int` value as if by the `readInt` method and then converts that `int` to a `float` using the `intBitsToFloat` method in class `Float`. This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next four bytes of this input stream, interpreted as a `float`.
  Throws: EOFException
    if this input stream reaches the end before reading four bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    readInt, intBitsToFloat

readDouble

     public final double readDouble() throws IOException

  Reads a `double` from this data input stream. This method reads a `long` value as if by the `readLong` method and then converts that `long` to a `double` using the `longBitsToDouble` method in class `Double`.

  This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    the next eight bytes of this input stream, interpreted as a `double`.
  Throws: EOFException
    if this input stream reaches the end before reading eight bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    readLong, longBitsToDouble

readLine

     public final String readLine() throws IOException

  Note: readLine() is deprecated. This method does not properly convert bytes to characters. As of JDK 1.1, the preferred way to read lines of text is via the `BufferedReader.readLine()` method. Programs that use the `DataInputStream` class to read lines can be converted to use the `BufferedReader` class by replacing code of the form
  `DataInputStream d = new DataInputStream(in);`
  with
  `BufferedReader d = new BufferedReader(new InputStreamReader(in));`

  Reads the next line of text from this data input stream. This method successively reads bytes from the underlying input stream until it reaches the end of a line of text.

  A line of text is terminated by a carriage return character (`'\r'`), a newline character (`'\n'`), a carriage return character immediately followed by a newline character, or the end of the input stream. The line-terminating character(s), if any, are not returned as part of the string that is returned.

  This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is detected, or an exception is thrown.

  Returns:
    the next line of text from this input stream, or `null` if no bytes are read before end-of-file is reached.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    readLine, in

readUTF

     public final String readUTF() throws IOException

  Reads in a string that has been encoded using a modified UTF-8 format from this data input stream. This method calls `readUTF(this)`. See `readUTF(java.io.DataInput)` for a more complete description of the format.

  This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

  Returns:
    a Unicode string.
  Throws: EOFException
    if this input stream reaches the end before reading all the bytes.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    readUTF

readUTF

     public static final String readUTF(DataInput in) throws IOException

  Reads in a string from the specified data input stream. The string has been encoded using a modified UTF-8 format.

  The first two bytes are read as if by `readUnsignedShort`. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

  This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

  Parameters:
    in - a data input stream.
  Returns:
    a Unicode string.
  Throws: EOFException
    if the input stream reaches the end before all the bytes.
  Throws: IOException
    if an I/O error occurs.
  Throws: UTFDataFormatException
    if the bytes do not represent a valid UTF-8 encoding of a Unicode string.
  See Also:
    readUnsignedShort

    All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature - Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.