JavaTM Platform
Standard Ed. 6

javax.imageio.stream
接口 ImageInputStream

所有超级接口:
DataInput
所有已知子接口:
ImageOutputStream
所有已知实现类:
FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream

public interface ImageInputStream
extends DataInput

ImageReader 使用的可查找输入流接口。各种输入源(如 InputStreamFile 以及将来的快速 I/O 源)都可以通过此接口的恰当实现进行“包装”,供 Image I/O API 使用。

另请参见:
ImageInputStreamImpl, FileImageInputStream, FileCacheImageInputStream, MemoryCacheImageInputStream

方法摘要
 void close()
          关闭流。
 void flush()
          丢弃当前流位置之前的流初始部分。
 void flushBefore(long pos)
          丢弃所指示位置之前的流初始部分。
 int getBitOffset()
          以整数的形式返回当前位偏移量,该整数在 0 到 7 之间(包含两者)。
 ByteOrder getByteOrder()
          以 java.nio.ByteOrder 枚举实例的形式返回从此流中读取数据值时所使用的字节顺序。
 long getFlushedPosition()
          返回流中可以执行查找的最早位置。
 long getStreamPosition()
          返回流的当前字节位置。
 boolean isCached()
          如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,则返回 true
 boolean isCachedFile()
          如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,并且将其保存在临时文件中,则返回 true
 boolean isCachedMemory()
          如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,并将其保存在主存中,则返回 true
 long length()
          返回流的总长度(如果已知)。
 void mark()
          标记流中某个位置,供后续调用 reset 时返回。
 int read()
          从流中读取单个字节,并以整数(0 到 255 之间)形式返回该字节。
 int read(byte[] b)
          从流中读取至多 b.length 个字节,并将其存储到 b 中(从索引 0 开始)。
 int read(byte[] b, int off, int len)
          从流中读取至多 len 个字节,并将其存储到 b 中(从索引 off 开始)。
 int readBit()
          从流中读取单个字节,并以 int01)的形式返回该字节。
 long readBits(int numBits)
          从流中读取位串 (bitstring) 并以 long 的形式返回,使第一个读取的位成为输出的最高有效位。
 boolean readBoolean()
          从流中读取一个字节,如果其不为 0,则返回 booleantrue;如果为 0,则返回 false
 byte readByte()
          从流中读取一个字节,并以 byte 值的形式返回该字节。
 void readBytes(IIOByteBuffer buf, int len)
          从流中读取至多 len 个字节,并修改提供的 IIOByteBuffer 以指示可以找到数据的 byte 数组、偏移量和长度。
 char readChar()
          与 readUnsignedShort 等效,唯一的不同在于它的结果使用 char 数据类型返回。
 double readDouble()
          从流中读取 8 个字节,根据当前字节顺序将其连接(概念上),然后以 double 值的形式返回结果。
 float readFloat()
          从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),然后以 float 值的形式返回结果。
 void readFully(byte[] b)
          从流中读取 b.length 个字节,并将其存储到 b 中(从索引 0 开始)。
 void readFully(byte[] b, int off, int len)
          从流中读取 len 个字节,并将其存储到 b 中(从索引 off 开始)。
 void readFully(char[] c, int off, int len)
          根据当前字节顺序从流中读取 len 个 char(无符号 16 位整数),并将其存储到 c 中(从索引 off 开始)。
 void readFully(double[] d, int off, int len)
          根据当前字节顺序从流中读取 len 个 double(64 位 IEEE 双精度浮点值),并将其存储到 d 中(从索引 off 开始)。
 void readFully(float[] f, int off, int len)
          根据当前字节顺序从流中读取 len 个 float(32 位 IEEE 单精度浮点值),并将其存储到 f 中(从索引 off 开始)。
 void readFully(int[] i, int off, int len)
          根据当前字节顺序从流中读取 len 个 int(有符号 32 位整数),并将其存储到 i 中(从索引 off 开始)。
 void readFully(long[] l, int off, int len)
          根据当前字节顺序从流中读取 len 个 long(有符号 64 位整数),并将其存储到 l 中(从索引 off 开始)。
 void readFully(short[] s, int off, int len)
          根据当前字节顺序从流中读取 len 个 short(有符号 16 位整数),并将其存储到 s 中(从索引 off 开始)。
 int readInt()
          从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),然后以 int 值的形式返回结果。
 String readLine()
          从输入流中读取文本的下一行。
 long readLong()
          从流中读取 8 个字节,根据当前字节顺序将其连接(概念上),然后以 long 值的形式返回结果。
 short readShort()
          从流中读取两个字节,根据当前字节顺序将其连接(概念上),然后以 short 值的形式返回结果。
 int readUnsignedByte()
          从流中读取一个字节,将其转换为 int(概念上),使用 0xff 屏蔽以便去掉所有符号扩展位,然后以 byte 值的形式返回。
 long readUnsignedInt()
          从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),将得到的值转换为 long,使用 0xffffffffL 屏蔽以便去掉所有符号扩展位,然后以无符号 long 值的形式返回结果。
 int readUnsignedShort()
          从流中读取两个字节,根据当前字节顺序将其连接(概念上),将得到的值转换为 int,使用 0xffff 屏蔽以便去掉所有符号扩展位,然后以无符号 int 值的形式返回结果。
 String readUTF()
          读入一个已使用 UTF-8 修改版格式编码的字符串。
 void reset()
          返回在最近一次非匹配地调用 mark 时指向上一个位置(包括位偏移量)的流指针。
 void seek(long pos)
          将当前流位置设置为所需的位置。
 void setBitOffset(int bitOffset)
          将位偏移量设置为 0 到 7 之间(包含两者)的整数。
 void setByteOrder(ByteOrder byteOrder)
          设置希望以后从此流中读取数据值时使用的字节顺序。
 int skipBytes(int n)
          将流位置向前移动给定的字节数。
 long skipBytes(long n)
          将流位置向前移动给定的字节数。
 

方法详细信息

setByteOrder

void setByteOrder(ByteOrder byteOrder)
设置希望以后从此流中读取数据值时使用的字节顺序。例如,如果以 4 字节整数形式读取字节序列 '0x01 0x02 0x03 0x04',则使用网络字节顺序时结果为值 '0x01020304',使用逆向字节顺序时为值 '0x04030201'。

枚举类 java.nio.ByteOrder 用于指定字节顺序。值 ByteOrder.BIG_ENDIAN 指定所谓的 big-endian 或网络字节顺序,该顺序中高位字节在前。Motorola 和 Sparc 处理器用此格式存储数据,而 Intel 处理器使用与之相反的 ByteOrder.LITTLE_ENDIAN 顺序存储数据。

字节顺序对 readBits 方法返回的结果(或 ImageOutputStream.writeBits 写入的值)没有任何影响。

参数:
byteOrder - ByteOrder.BIG_ENDIANjava.nio.ByteOrder.LITTLE_ENDIAN,指示以后读取时是使用网络顺序还是使用与之相反的顺序。
另请参见:
ByteOrder, getByteOrder(), readBits(int)

getByteOrder

ByteOrder getByteOrder()
java.nio.ByteOrder 枚举实例的形式返回从此流中读取数据值时所使用的字节顺序。

返回:
ByteOrder.BIG_ENDIANByteOrder.LITTLE_ENDIAN,指示要使用的字节顺序。
另请参见:
ByteOrder, setByteOrder(java.nio.ByteOrder)

read

int read()
         throws IOException
从流中读取单个字节,并以整数(0 到 255 之间)形式返回该字节。如果到达流末尾,则返回 -1。

在进行读取前,流中的位偏移量被重置为 0。

返回:
流中 int 形式的字节值;或者返回 -1,指示 EOF(文件结束标记)。
抛出:
IOException - 如果发生 I/O 错误。

read

int read(byte[] b)
         throws IOException
从流中读取至多 b.length 个字节,并将其存储到 b 中(从索引 0 开始)。返回读取的字节数。如果因到达流末尾而无法读取任何字节,则返回 -1。

在进行读取前,流中的位偏移量被重置为 0。

参数:
b - 用来接收写入的 byte 数组。
返回:
实际读取的字节数;或者返回 -1,指示 EOF。
抛出:
NullPointerException - 如果 bnull
IOException - 如果发生 I/O 错误。

read

int read(byte[] b,
         int off,
         int len)
         throws IOException
从流中读取至多 len 个字节,并将其存储到 b 中(从索引 off 开始)。返回读取的字节数。如果因到达流末尾而无法读取任何字节,则返回 -1

在进行读取前,流中的位偏移量被重置为 0。

参数:
b - 用来接收写入的 byte 数组。
off - 向 b 进行写入的开始位置。
len - 要读取的最大 byte 数。
返回:
实际读取的字节数;或者返回 -1,指示 EOF。
抛出:
NullPointerException - 如果 bnull
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 b.length
IOException - 如果发生 I/O 错误。

readBytes

void readBytes(IIOByteBuffer buf,
               int len)
               throws IOException
从流中读取至多 len 个字节,并修改提供的 IIOByteBuffer 以指示可以找到数据的 byte 数组、偏移量和长度。调用者不应该试图修改 IIOByteBuffer 中找到的数据。

在进行读取前,流中的位偏移量被重置为 0。

参数:
buf - 要修改的 IIOByteBuffer 对象。
len - 要读取的最大 byte 数。
抛出:
IndexOutOfBoundsException - 如果 len 为负。
NullPointerException - 如果 bufnull
IOException - 如果发生 I/O 错误。

readBoolean

boolean readBoolean()
                    throws IOException
从流中读取一个字节,如果其不为 0,则返回 booleantrue;如果为 0,则返回 false

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readBoolean
返回:
取自流的 boolean 值。
抛出:
EOFException - 如果到达流末尾。
IOException - 如果发生 I/O 错误。

readByte

byte readByte()
              throws IOException
从流中读取一个字节,并以 byte 值的形式返回该字节。0x000x7f 之间的字节值表示 0127 之间的整数值。0x800xff 之间的字节值表示 -128-1 之间的负整数值。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readByte
返回:
取自流的单个字节值。
抛出:
EOFException - 如果到达流末尾。
IOException - 如果发生 I/O 错误。

readUnsignedByte

int readUnsignedByte()
                     throws IOException
从流中读取一个字节,将其转换为 int(概念上),使用 0xff 屏蔽以便去掉所有符号扩展位,然后以 byte 值的形式返回。

于是,0x000x7f 之间的字节值便作为 0127 之间的整数值返回。0x800xff 之间的字节值通常表示为负的 byte 值,它们将被映射成 128255 之间的正整数。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readUnsignedByte
返回:
取自流的无符号 byte 值。
抛出:
EOFException - 如果到达流末尾。
IOException - 如果发生 I/O 错误。

readShort

short readShort()
                throws IOException
从流中读取两个字节,根据当前字节顺序将其连接(概念上),然后以 short 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readShort
返回:
取自流的有符号 short 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readUnsignedShort

int readUnsignedShort()
                      throws IOException
从流中读取两个字节,根据当前字节顺序将其连接(概念上),将得到的值转换为 int,使用 0xffff 屏蔽以便去掉所有符号扩展位,然后以无符号 int 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readUnsignedShort
返回:
取自流的无符号 short 值(int 形式)。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readChar

char readChar()
              throws IOException
readUnsignedShort 等效,唯一的不同在于它的结果使用 char 数据类型返回。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readChar
返回:
取自流的无符号 char 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
readUnsignedShort()

readInt

int readInt()
            throws IOException
从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),然后以 int 值的形式返回结果。

忽略流中的位偏移量,将其视为 0。

指定者:
接口 DataInput 中的 readInt
返回:
取自流的有符号 int 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readUnsignedInt

long readUnsignedInt()
                     throws IOException
从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),将得到的值转换为 long,使用 0xffffffffL 屏蔽以便去掉所有符号扩展位,然后以无符号 long 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

返回:
取自流的无符号 int 值(long 形式)。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readLong

long readLong()
              throws IOException
从流中读取 8 个字节,根据当前字节顺序将其连接(概念上),然后以 long 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readLong
返回:
取自流的有符号 long 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readFloat

float readFloat()
                throws IOException
从流中读取 4 个字节,根据当前字节顺序将其连接(概念上),然后以 float 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readFloat
返回:
取自流的 float 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readDouble

double readDouble()
                  throws IOException
从流中读取 8 个字节,根据当前字节顺序将其连接(概念上),然后以 double 值的形式返回结果。

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readDouble
返回:
取自流的 double 值。
抛出:
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。
另请参见:
getByteOrder()

readLine

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

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

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readLine
返回:
一个 String,它包含取自流的一行文本。
抛出:
IOException - 如果发生 I/O 错误。

readUTF

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

首先,读取两个字节并按 readUnsignedShort 方法的方式使用这两个字节构造一个无符号 16 位整数,使用的是网络字节顺序(无论当前设置的是哪种字节顺序)。该整数值被称为 UTF 长度,它指定要读取的额外字节数。然后成组地将这些字节转换为字符。每组的长度根据该组第一个字节的值计算。紧跟在某个组后面的字节(如果有)是下一组的第一个字节。

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

如果组的第一个字节与位模式 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,然后该字符串将被返回。

忽略当前设置的字节顺序。

在进行读取前,流中的位偏移量被重置为 0。

注:在使用标准 UTF-8 图像格式的实现中不应该使用此方法,因为此处使用的 UTF-8 修改版与标准 UTF-8 不兼容。

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

readFully

void readFully(byte[] b,
               int off,
               int len)
               throws IOException
从流中读取 len 个字节,并将其存储到 b 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readFully
参数:
b - 用来接收写入的 byte 数组。
off - 向 b 进行写入的开始位置。
len - 要读取的最大 byte 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 b.length
NullPointerException - 如果 bnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(byte[] b)
               throws IOException
从流中读取 b.length 个字节,并将其存储到 b 中(从索引 0 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

指定者:
接口 DataInput 中的 readFully
参数:
b - 一个 byte 数组。
抛出:
NullPointerException - 如果 bnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(short[] s,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 short(有符号 16 位整数),并将其存储到 s 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
s - 用来接收写入的 short 数组。
off - 向 s 进行写入的开始位置。
len - 要读取的最大 short 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 s.length
NullPointerException - 如果 snull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(char[] c,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 char(无符号 16 位整数),并将其存储到 c 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
c - 用来接收写入的 char 数组。
off - 向 c 进行写入的开始位置。
len - 要读取的最大 char 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 c.length
NullPointerException - 如果 cnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(int[] i,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 int(有符号 32 位整数),并将其存储到 i 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
i - 用来接收写入的 int 数组。
off - 向 i 进行写入的开始位置。
len - 要读取的最大 int 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 i.length
NullPointerException - 如果 inull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(long[] l,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 long(有符号 64 位整数),并将其存储到 l 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
l - 用来接收写入的 long 数组。
off - 向 l 进行写入的开始位置。
len - 要读取的最大 long 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 l.length
NullPointerException - 如果 lnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(float[] f,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 float(32 位 IEEE 单精度浮点值),并将其存储到 f 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
f - 用来接收写入的 float 数组。
off - 向 f 进行写入的开始位置。
len - 要读取的最大 float 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 f.length
NullPointerException - 如果 fnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

readFully

void readFully(double[] d,
               int off,
               int len)
               throws IOException
根据当前字节顺序从流中读取 len 个 double(64 位 IEEE 双精度浮点值),并将其存储到 d 中(从索引 off 开始)。如果到达流末尾,则将抛出 EOFException

在进行读取前,流中的位偏移量被重置为 0。

参数:
d - 用来接收写入的 double 数组。
off - 向 d 进行写入的开始位置。
len - 要读取的最大 double 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 d.length
NullPointerException - 如果 dnull
EOFException - 如果该流在读取所有字节之前到达末尾。
IOException - 如果发生 I/O 错误。

getStreamPosition

long getStreamPosition()
                       throws IOException
返回流的当前字节位置。下一次读取将从此偏移量开始。

返回:
一个包含流位置 long 值。
抛出:
IOException - 如果发生 I/O 错误。

getBitOffset

int getBitOffset()
                 throws IOException
以整数的形式返回当前位偏移量,该整数在 0 到 7 之间(包含两者)。位偏移量通过调用 readBits 方法隐式地更新。值 0 表示所读取字节的最高有效位,值 7 表示所读取字节的最低有效位。

第一次打开流时位偏移量被设置为 0,以后可以通过调用 seekskipBytes、或者任何 readreadFully 方法将其重置为 0。

返回:
一个 int,包含 0 到 7 之间(包含两者)的位偏移量。
抛出:
IOException - 如果发生 I/O 错误。
另请参见:
setBitOffset(int)

setBitOffset

void setBitOffset(int bitOffset)
                  throws IOException
将位偏移量设置为 0 到 7 之间(包含两者)的整数。不改变流中由 getStreamPosition 返回的位偏移量。值 0 表示所读取字节的最高有效位,值 7 表示所读取字节的最低有效位。

参数:
bitOffset - 所需的偏移量,为 0 到 7 之间(包括两者)的 int 的形式。
抛出:
IllegalArgumentException - 如果 bitOffset 不在 0 和 7(包括两者)之间。
IOException - 如果发生 I/O 错误。
另请参见:
getBitOffset()

readBit

int readBit()
            throws IOException
从流中读取单个字节,并以 int01)的形式返回该字节。位偏移量将加 1,模数将减 8。

返回:
一个 int,包含 01
抛出:
EOFException - 如果该流在读取所有位之前到达末尾。
IOException - 如果发生 I/O 错误。

readBits

long readBits(int numBits)
              throws IOException
从流中读取位串 (bitstring) 并以 long 的形式返回,使第一个读取的位成为输出的最高有效位。在 getStreamPosition 指示的字节中从 getBitOffset 给定的位开始读取。位偏移量将增加 numBits,模数将减 8。

流的字节顺序对此方法没有任何影响。此方法返回值的构造方式相当于每次读取一个位,然后将其移到返回值的右边。如以下伪代码所示:

 long accum = 0L;
 for (int i = 0; i < numBits; i++) {
   accum <<= 1; // Shift left one bit to make room
   accum |= readBit();
 }
 
注意,如果使用了与网络字节顺序相反的顺序(即 getByteOrder() == false),那么 readBits(32) 的结果可能因此而不等于 readInt() 的结果。

如果在读取了所有位前遇到流末尾,则抛出 EOFException

参数:
numBits - 要读取的位数,为 0 到 64 之间(包含两者)的 int 形式。
返回:
long 形式的位串,最后读取的位存储在最低有效位中。
抛出:
IllegalArgumentException - 如果 numBits 不在 0 和 64 之间(包括两者)。
EOFException - 如果该流在读取所有位之前到达末尾。
IOException - 如果发生 I/O 错误。

length

long length()
            throws IOException
返回流的总长度(如果已知)。否则,返回 -1

返回:
一个 long,包含流的长度(如果已知);否则返回 -1
抛出:
IOException - 如果发生 I/O 错误。

skipBytes

int skipBytes(int n)
              throws IOException
将流位置向前移动给定的字节数。此方法向前跳过的字节数可能小于所请求的字节数,例如,在到达流末尾时。无论如何,将返回实际跳过的字节数。在推进位置前,位偏移量被设置为 0。

指定者:
接口 DataInput 中的 skipBytes
参数:
n - 一个 int,它包含要跳过的字节数。
返回:
一个 int,表示跳过的字节数。
抛出:
IOException - 如果发生 I/O 错误。

skipBytes

long skipBytes(long n)
               throws IOException
将流位置向前移动给定的字节数。此方法等同于 skipBytes(int),唯一的不同在于它允许更大的跳跃距离。

参数:
n - 一个 long,它包含要跳过的字节数。
返回:
表示跳过的字节数的 long
抛出:
IOException - 如果发生 I/O 错误。

seek

void seek(long pos)
          throws IOException
将当前流位置设置为所需的位置。下一次读取将在此位置上进行。位偏移量被设置为 0。

如果 pos 小于刷新位置(由 getflushedPosition 返回),那么将抛出 IndexOutOfBoundsException

查找文件结束标记的后面是合法的,只有在该处执行读取时才抛出 EOFException

参数:
pos - 一个 long,它包含所需的文件指针位置。
抛出:
IndexOutOfBoundsException - 如果 pos 小于刷新位置。
IOException - 如果发生任何 I/O 错误。

mark

void mark()
标记流中某个位置,供后续调用 reset 时返回。与标准 InputStream 不同的是,所有的 ImageInputStream 都支持标记操作。此外,还可以随意嵌套对 markreset 的调用。

ReaderInputStream 接口声明的 mark 方法不同,此方法不使用任何 readLimit 参数。调用 mark 后可以读取任意数量的数据。

readBits 方法使用的位位置可通过每次调用 markreset 来保存和恢复。

注意,ImageReader 调用 flushBefore 作为读取操作的一部分是有效的。因此,如果应用程序向 ImageReader 传递该流前调用 mark,则应用程序不应该假定标记位置在读取操作完成后仍保持有效。


reset

void reset()
           throws IOException
返回在最近一次非匹配地调用 mark 时指向上一个位置(包括位偏移量)的流指针。

调用 reset 而没有相应地调用 mark 没有任何效果。

如果上一个标记位置位于流的丢弃部分,则抛出 IOException

抛出:
IOException - 如果发生 I/O 错误。

flushBefore

void flushBefore(long pos)
                 throws IOException
丢弃所指示位置之前的流初始部分。试图查找流的刷新部分中的偏移量将导致抛出 IndexOutOfBoundsException

调用 flushBefore 可允许实现此接口的类释放存储流中的数据所使用的资源,如内存和磁盘空间。

参数:
pos - 一个 long,它包含要刷新的流前缀的长度。
抛出:
IndexOutOfBoundsException - 如果 pos 位于流的刷新部分或当前流位置的后面。
IOException - 如果发生 I/O 错误。

flush

void flush()
           throws IOException
丢弃当前流位置之前的流初始部分。等效于 flushBefore(getStreamPosition())

抛出:
IOException - 如果发生 I/O 错误。

getFlushedPosition

long getFlushedPosition()
返回流中可以执行查找的最早位置。返回值将是所有传入 flushBefore 上一次调用的值中的最大值。

返回:
用于查找的最早的合法位置(long 形式)。

isCached

boolean isCached()
如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,则返回 true。应用程序可以根据此方法来决定刷新的频率以及是否刷新以保留缓存资源。

返回:
如果此 ImageInputStream 缓存数据,则返回 true
另请参见:
isCachedMemory(), isCachedFile()

isCachedMemory

boolean isCachedMemory()
如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,并将其保存在主存中,则返回 true。应用程序可以根据此方法来决定刷新的频率以及是否刷新以保留缓存资源。

返回:
如果此 ImageInputStream 在主存中缓存数据,则返回 true
另请参见:
isCached(), isCachedFile()

isCachedFile

boolean isCachedFile()
如果此 ImageInputStream 本身为了允许逆向查找而缓存了数据,并且将其保存在临时文件中,则返回 true。应用程序可以根据此方法来决定刷新的频率以及是否刷新以保留缓存资源。

返回:
如果此 ImageInputStream 在临时文件中缓存数据,则返回 true
另请参见:
isCached(), isCachedMemory()

close

void close()
           throws IOException
关闭流。试图访问已经关闭的流将导致 IOException 或错误行为。调用此方法可允许实现此接口的类释放与流关联的资源,如内存、磁盘空间或文件描述符。

抛出:
IOException - 如果发生 I/O 错误。

JavaTM Platform
Standard Ed. 6

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

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