JavaTM Platform
Standard Ed. 6

java.io
接口 DataInput

所有已知子接口:
ImageInputStream, ImageOutputStream, ObjectInput
所有已知实现类:
DataInputStream, FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream, ObjectInputStream, RandomAccessFile

public interface DataInput

DataInput 接口用于从二进制流中读取字节,并根据所有 Java 基本类型数据进行重构。同时还提供根据 UTF-8 修改版格式的数据重构 String 的工具。

对于此接口中的所有数据读取例程来说,如果在读取所需字节数之前已经到达文件末尾 (end of file),则将抛出 EOFExceptionIOException 的一种)。如果因为到达文件末尾以外的其他原因无法读取字节,则将抛出 IOException 而不是 EOFException。尤其是,在输入流已关闭的情况下,将抛出 IOException

UTF-8 修改版

DataInput 和 DataOutput 接口的实现表示稍作改版的 UTF-8 格式的 Unicode 字符串。(关于标准 UTF-8 格式的信息,请参阅 The Unicode Standard, Version 4.03.9 Unicode Encoding Forms 节)。注意,在下表中,最高有效位显示在最左边的列中。

'\u0001''\u007F' 范围内的所有字符都是用单个字节表示的:

位值
字节 1
0
位 6-0

null 字符 '\u0000' 以及从 '\u0080''\u07FF' 的范围内的字符用两个字节表示:

位值
字节 1
1
1
0
位 10-6
字节 2
1
0
位 5-0

'\u0800''\uFFFF' 范围内的 char 值用三个字节表示:
位值
字节 1
1
1
1
0
位 15-12
字节 2
1
0
位 11-6
字节 3
1
0
位 5-0

这种格式与标准 UTF-8 格式之间的不同如下:

从以下版本开始:
JDK1.0
另请参见:
DataInputStream, DataOutput

方法摘要
 boolean readBoolean()
          读取一个输入字节,如果该字节不是零,则返回 true,如果是零,则返回 false
 byte readByte()
          读取并返回一个输入字节。
 char readChar()
          读取两个输入字节并返回一个 char 值。
 double readDouble()
          读取八个输入字节并返回一个 double 值。
 float readFloat()
          读取四个输入字节并返回一个 float 值。
 void readFully(byte[] b)
          从输入流中读取一些字节,并将它们存储在缓冲区数组 b 中。
 void readFully(byte[] b, int off, int len)
          从输入流中读取 len 个字节。
 int readInt()
          读取四个输入字节并返回一个 int 值。
 String readLine()
          从输入流中读取下一文本行。
 long readLong()
          读取八个输入字节并返回一个 long 值。
 short readShort()
          读取两个输入字节并返回一个 short 值。
 int readUnsignedByte()
          读取一个输入字节,将它左侧补零 (zero-extend) 转变为 int 类型,并返回结果,所以结果的范围是 0255
 int readUnsignedShort()
          读取两个输入字节,并返回 065535 范围内的一个 int 值。
 String readUTF()
          读入一个已使用 UTF-8 修改版格式编码的字符串。
 int skipBytes(int n)
          试图在输入流中跳过数据的 n 个字节,并丢弃跳过的字节。
 

方法详细信息

readFully

void readFully(byte[] b)
               throws IOException
从输入流中读取一些字节,并将它们存储在缓冲区数组 b 中。读取的字节数等于 b 的长度。

在出现以下条件之一以前,此方法将一直阻塞:

如果 bnull,则抛出 NullPointerException。如果 b.length 为零,则不读取字节。否则,将读取的第一个字节存储到元素 b[0] 中,下一个字节存储到 b[1] 中,依此类推。如果此方法抛出异常,则可能是因为已经用输入流中的数据更新了 b 的某些(但非全部)字节。

参数:
b - 存储读取数据的缓冲区。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(byte[] b,
               int off,
               int len)
               throws IOException
从输入流中读取 len 个字节。

在出现以下条件之一以前,此方法将一直阻塞:

如果 bnull,则抛出 NullPointerException。如果 off 为负,或 len 为负,或者 off+len 大于数组 b 的长度,则抛出 IndexOutOfBoundsException。如果 len 为零,则不读取字节。否则,将读取的第一个字节存储到元素 b[off] 中,下一个字节存储到 b[off+1] 中,依此类推。读取的字节数至多等于 b[0]

参数:
b - 存储读取数据的缓冲区。
off - 指定数据中的偏移量的 int 值。
len - 指定读取的字节数的 int 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

skipBytes

int skipBytes(int n)
              throws IOException
试图在输入流中跳过数据的 n 个字节,并丢弃跳过的字节。不过,可以跳过更少的字节数,该字节数甚至可以为零。这可能由很多情况引起;在已经跳过 n 个字节前到达文件末尾只是其中的一种可能。此方法从不抛出 EOFException。返回实际跳过的字节数。

参数:
n - 要跳过的字节数。
返回:
实际跳过的字节数。
抛出:
IOException - 如果发生 I/O 错误。

readBoolean

boolean readBoolean()
                    throws IOException
读取一个输入字节,如果该字节不是零,则返回 true,如果是零,则返回 false。此方法适用于读取用接口 DataOutputwriteBoolean 方法写入的字节。

返回:
读取的 boolean 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readByte

byte readByte()
              throws IOException
读取并返回一个输入字节。该字节被看作是 -128127(包含)范围内的一个有符号值。此方法适用于读取用接口 DataOutputwriteByte 方法写入的字节。

返回:
读取的 8 位值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readUnsignedByte

int readUnsignedByte()
                     throws IOException
读取一个输入字节,将它左侧补零 (zero-extend) 转变为 int 类型,并返回结果,所以结果的范围是 0255。如果接口 DataOutputwriteByte 方法的参数是 0255 之间的值,则此方法适用于读取用 writeByte 写入的字节。

返回:
读取的无符号 8 位值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readShort

short readShort()
                throws IOException
读取两个输入字节并返回一个 short 值。设 a 为第一个读取字节,b 为第二个读取字节。返回的值是:

(short)((a << 8) | (b & 0xff))
 
此方法适用于读取用接口 DataOutputwriteShort 方法写入的字节。

返回:
读取的 16 位值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readUnsignedShort

int readUnsignedShort()
                      throws IOException
读取两个输入字节,并返回 065535 范围内的一个 int 值。设 a 为第一个读取字节,b 为第二个读取字节。返回的值是:

(((a & 0xff) << 8) | (b & 0xff))
 
如果接口 DataOutputwriteShort 方法的参数是 065535 范围内的值,则此方法适用于读取用 writeShort 写入的字节。

返回:
读取的无符号 16 位值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readChar

char readChar()
              throws IOException
读取两个输入字节并返回一个 char 值。设 a 为第一个读取字节,b 为第二个读取字节。返回的值是:

(char)((a << 8) | (b & 0xff))
 
此方法适用于读取用接口 DataOutputwriteChar 方法写入的字节。

返回:
读取的 char 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readInt

int readInt()
            throws IOException
读取四个输入字节并返回一个 int 值。设 a-d 为四个读取字节中的第一个字节。返回的值是:

 
 (((a & 0xff) << 24) | ((b & 0xff) << 16) |
  ((c & 0xff) << 8) | (d & 0xff))
 
此方法适用于读取用接口 DataOutputwriteInt 方法写入的字节。

返回:
读取的 int 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readLong

long readLong()
              throws IOException
读取八个输入字节并返回一个 long 值。设 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)))
 

此方法适用于读取用接口 DataOutputwriteLong 方法写入的字节。

返回:
读取的 long 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFloat

float readFloat()
                throws IOException
读取四个输入字节并返回一个 float 值。实现这一点的方法是:先使用与 readInt 方法完全相同的方式构造一个 int 值,然后使用与 Float.intBitsToFloat 方法完全相同的方式将此 int 值转换成一个 float 值。此方法适用于读取用接口 DataOutputwriteFloat 方法写入的字节。

返回:
读取的 float 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readDouble

double readDouble()
                  throws IOException
读取八个输入字节并返回一个 double 值。实现这一点的方法是:先使用与 readlong 方法完全相同的方式构造一个 long 值,然后使用与 Double.longBitsToDouble 方法完全相同的方式将此 long 值转换成一个 double 值。此方法适用于读取用接口 DataOutputwriteDouble 方法写入的字节。

返回:
读取的 double 值。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readLine

String readLine()
                throws IOException
从输入流中读取下一文本行。该方法读取连续的字节,将每个字节分别转换成一个字符,直到遇到行结尾符或到达末尾;然后以 String 形式返回读取的字符。注意,因为此方法用于处理字符,所以它不支持整个 Unicode 字符集的输入。

如果在一个字节都没有读取的时候就到达文件末尾,则返回 null。否则,通过左侧补零将读取的每个字节转换成 char 类型的值。如果遇到字符 '\n',则丢弃它并且停止读取。如果遇到字符 '\r' 则丢弃它,如果后续字节转变成字符 '\n',则同样丢弃它并停止读取。如果在遇到字符 '\n''\r' 之一前到达文件末尾,则停止读取。一旦已停止读取,则返回一个 String,它按顺序包含所有已读取且未丢弃的字符。注意,此字符串中的每个字符的值都将小于 \u0100(即 (char)256)的值。

返回:
输入流中文本的下一行,如果还没有读取一个字节就到达文件末尾,则返回 null
抛出:
IOException - 如果发生 I/O 错误。

readUTF

String readUTF()
               throws IOException
读入一个已使用 UTF-8 修改版格式编码的字符串。readUTF 的常规协定是:该方法读取使用 UTF-8 修改版格式编码的 Unicode 字符串的表示形式;然后以 String 的形式返回此字符串。

首先读取两个字节,并使用它们构造一个无符号 16 位整数,构造方式与 readUnsignedShort 方法的方式完全相同。该整数值被称为 UTF 长度,它指定要读取的额外字节数。然后成组地将这些字节转换为字符。每组的长度根据该组第一个字节的值计算。紧跟在某个组后面的字节(如果有)是下一组的第一个字节。

如果组的第一个字节与位模式 0xxxxxxx(其中 x 表示“可能为 01”)匹配,则该组只有这一个字节。该字节被左侧补零,转换成一个字符。

如果组的第一个字节与位模式 110xxxxx 匹配,则该组只由字节 a 和另一个字节 b 组成。如果没有字节 b(因为字节 a 是要读取的最后一个字节),或者字节 b 与位模式 10xxxxxx 不匹配,则抛出 UTFDataFormatException。否则,将该组转换成字符:

(char)(((a& 0x1F) << 6) | (b & 0x3F))
 
如果组的第一个字节与位模式 1110xxxx 匹配,则该组由字节 a 和另外两个字节 bc 组成。如果没有字节 c(因为字节 a 是要读取的最后两个字节之一),或者字节 b 或字节 c 与位模式 10xxxxxx 不匹配,则抛出 UTFDataFormatException。否则,将该组转换成字符:


 (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
 
如果组的第一个字节与模式 1111xxxx 或模式 10xxxxxx 匹配,则抛出 UTFDataFormatException

如果在执行整个过程中的任意时间到达文件末尾,则抛出 EOFException

在通过此过程将每个组转换成字符后,按照从输入流中读取相应组的顺序,将这些字符收集在一起,形成一个 String,然后该字符串将被返回。

可以使用 DataOutput 接口的 writeUTF 方法写入适合此方法读取的数据。

返回:
一个 Unicode 字符串。
抛出:
EOFException - 如果此流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
UTFDataFormatException - 如果这些字节不表示一个有效的、UTF-8 修改版编码的字符串。

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策