JDK8 API——java.io.DataInput

[java]  view plain  copy

1. java.io  

public interface DataInput

子接口：

ImageInputStream, ImageOutputStream, ObjectInput

实现该接口的类 :

DataInputStream, FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, 

ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream, ObjectInputStream,

RandomAccessFile

     DataInput接口提供了从二进制流读字节数据并重建数据为任何Java原始类型的功能，也提供了修改utf8格式编码

的数据为String类型。

     事实上，对于这个接口中所有的读程序，如果在所需的字节数据读完之前结束文件操作，会抛出EOFException异

常（这是一种IOException）。如果有任何字节不能被读是因为除了文件结束以外的任何原因，则会抛出IOException异

常。特别地，如果输入流被关闭了，也会抛出IOException异常。

Modified UTF-8

	DataInput和DataOutput接口的实现代表着Unicode字符串的格式比UTF-8格式略微有改进（有关标准的UTF-8

格式，见3.9 Unicode编码的Unicode的标准，4.0版）。请注意，在下表中，最重要的一点出现在远左列中。

这种格式和标准的UTF-8格式的区别如下：

• 空字节的 '\u0000'编码为2个字节格式而不是1个字节，因此编码的字符串不会赋予空值。
• 只使用一个字节、2个字节和3个字节格式。
• 扩展字符以代理对（surrogate pairs）的形式表示。

Since:

JDK1.0

See Also:

DataInputStream,  DataOutput

Method Summary

All Methods Instance Methods Abstract Methods

Modifier and Type	Method and Description
boolean	readBoolean() Reads one input byte and returns  true if that byte is nonzero,  false if that byte is zero.
byte	readByte() Reads and returns one input byte.
char	readChar() Reads two input bytes and returns a  char value.
double	readDouble() Reads eight input bytes and returns a  double value.
float	readFloat() Reads four input bytes and returns a  float value.
void	readFully(byte[] b) Reads some bytes from an input stream and stores them into the buffer array  b.
void	readFully(byte[] b, int off, int len) Reads  len bytes from an input stream.
int	readInt() Reads four input bytes and returns an  int value.
String	readLine() Reads the next line of text from the input stream.
long	readLong() Reads eight input bytes and returns a  long value.
short	readShort() Reads two input bytes and returns a  short value.
int	readUnsignedByte() Reads one input byte, zero-extends it to type  int, and returns the result, which is therefore in the range  0 through  255.
int	readUnsignedShort() Reads two input bytes and returns an  int value in the range  0 through  65535.
String	readUTF() Reads in a string that has been encoded using a  modified UTF-8 format.
int	skipBytes(int n) Makes an attempt to skip over  n bytes of data from the input stream, discarding the skipped bytes.

Method Detail

• readFully

void readFully(byte[] b)
        throws IOException

从输入流中读取一些字节，并将它们存储到缓冲区数组b。读取的字节数等于b的长度。

此方法阻塞，直到下列条件之一发生：

• b.length字节的输入数据是可用的，在这种情况下，可以保证正常的返回数据。
  
• 文件结束是被检测的，在这种情况下，EOFException会被抛出。
• I/O错误发生，在这种情况下，IOException会被抛出。 

 如果b数组为空，会抛出NullPointerException异常。如果b.length是零，那么没有字节被读。否则，第一个字节读取存储到元素b[ 0 ]，下一个存储到b[ 1 ]，等等。如果从这个方法中抛出一个异常，那么它可能是一些，但不是所有的b数组从输入流读的字节数据都被更新。

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

readFully

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

从输入流读取len个字节。

此方法阻塞，直到下列条件之一发生：

• len字节的输入数据是可用的，在这种情况下，可以保证正常的返回数据。
  
• 文件结束是被检测的，在这种情况下，EOFException会被抛出。
• I/O错误发生，在这种情况下，IOException会被抛出。 

如果b数组为空，会抛出NullPointerException异常。如果是off负数，或len为负，或off+len长度大于数组b的长度，则会抛出indexOutOfBoundsException异常。如果len长度为0，那么没有字节可读。否则，第一个字节读取存储到元素b[off]，下一个到b[off+ 1 ]，等等。读取的字节数，最多等于len。

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

skipBytes

int skipBytes(int n)
       throws IOException

试图跳过从输入流中的n个字节，丢弃跳过的n个字节。然而，它可能跳过较小的字节数，可能为零。这可能导致很多的状 况 ，在n个字节被跳过之前达到 文件 结束只有一个可能性。这个方法从未抛   EOFException异常 。 返回实际 跳过的字节数。

Parameters:
n - the number of bytes to be skipped.
Returns:
the number of bytes actually skipped.
Throws:
IOException - if an I/O error occurs.

readBoolean

boolean readBoolean()
             throws IOException

读取一个输入字节，如果该字节为非零，则返回true，如果该字节为零，则返回false。这个方法适用于读取DataOutput接口的writeBoolean方法所写的字节数据。

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.

readByte

byte readByte()
       throws IOException

读取并返回一个输入字节。字节被视为一个范围在- 128至127的有符号值。这个方法适用于读取DataOutput接口的writeByte方法所写的字节数据。

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.

readUnsignedByte

int readUnsignedByte()
              throws IOException

读取一个输入的字节，zero-extends到int类型，并返回范围在0到255的结果。这个方法适用于读取DataOutput接口的writeByte方法所写的字节数据，如果writeByte方法的参数值的范围在0到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.

readShort

short readShort()
         throws IOException

读取两个输入字节，并返回一个short类型的值。假如a一个是的读取第一个字节，b是读取的第二个字节，则返回的值是：

	(short)((a << 8) | (b & 0xff))

这个方法适用于读取DataOutput接口的writeShort方法所写的字节数据。

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.

readChar

char readChar()
       throws IOException

读取两个输入字节，并返回一个char类型的值。假如a一个是的读取第一个字节，b是读取的第二个字节，则返回的值是：

	(char)((a << 8) | (b & 0xff))

这个方法适用于读取DataOutput接口的writeShort方法所写的字节数据。

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.

readInt

int readInt()
     throws IOException

读取四个输入字节，并返回一个int类型的值。假如a到d是读取第一到第四个字节，则返回的值是：

	
	(((a & 0xff) << 24) | ((b & 0xff) << 16) |
  	((c & 0xff) <<  8) | (d & 0xff))

这个方法适用于读取DataOutput接口的writeInt方法所写的字节数据。

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.

readLong

long readLong()
       throws IOException

读取八个输入字节，并返回一个int类型的值。假如a到h是读取第一到第八个字节，则返回的值是：

	
	
	 (((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)))

这个方法适用于读取DataOutput接口的writeLong方法所写的字节数据。

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.

readFloat

float readFloat()
         throws IOException

读取四个输入字节，并返回一个float类型的值。这是首先通过readInt方法方式准确构建一个int值，然后使用Float.intBitsToFloat方法转换int值为float类型的值。这个方法适用于读取DataOutput接口的writeFloat方法所写的字节数据。

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.

readDouble

double readDouble()
           throws IOException

读取八个输入字节，并返回一个double类型的值。这是首先通过readLong方法方式准确构建一个Long类型值，然后使用Double.longBitsToDouble方法转换long值为double类型的值。这个方法适用于读取DataOutput接口的writeDouble方法所写的字节数据。

Returns:
the next line of text from the input stream, or null if the end of file is encountered before a byte can be read.
Throws:
IOException - if an I/O error occurs.

readUTF

String readUTF()
        throws IOException

读取一个已经由utf8格式编码的字符串。readUTF数据缩小是因为它读取改进后的UTF-8编码格式编码的Unicode字符串的表示；这个字符串是作为String.Eturned字符串返回。

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))
 

If the first byte of a group matches the bit pattern  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))
 

If the first byte of a group matches the pattern  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.

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.