JavaTM Platform
Standard Ed. 6

javax.imageio.stream
接口 ImageOutputStream

所有超级接口:
DataInput, DataOutput, ImageInputStream
所有已知实现类:
FileCacheImageOutputStream, FileImageOutputStream, ImageOutputStreamImpl, MemoryCacheImageOutputStream

public interface ImageOutputStream
extends ImageInputStream, DataOutput

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

与标准 OutputStream 不同的是,ImageOutputStream 扩展其对应方 ImageInputStream。因此它能够在对流进行写入的同时从该流进行读取。尽管处理字节定位写入操作之前非零位偏移量的语义一定不同于处理字节定位读取操作之前非零位偏移量的语义,但读取操作和写入操作使用相同的查找和刷新位置。读取字节时,任何位偏移量在读取前都被设置为 0;写入字节时,如果位偏移量不为零,则字节中的剩余位将被写入 0。然后,字节定位写入开始于下一个字节位置。

另请参见:
ImageInputStream

方法摘要
 void flushBefore(long pos)
          刷新给定位置之前所有数据的缓冲并转到底层目标(如 OutputStreamFile)。
 void write(byte[] b)
          将字节序列写入到流中的当前位置。
 void write(byte[] b, int off, int len)
          将字节序列写入到流中的当前位置。
 void write(int b)
          将单个字节写入到流中的当前位置。
 void writeBit(int bit)
          将单个位(由参数的最低有效位给定)写入到流的当前字节位置中的当前位偏移量。
 void writeBits(long bits, int numBits)
          将一个位序列(由 bits 参数的 numBits 个最低有效位按从左到右的顺序给定)写入到流的当前字节位置中的当前位偏移量。
 void writeBoolean(boolean v)
          将一个 boolean 值写入到流中。
 void writeByte(int v)
          将 v 的 8 个低位写入到流中。
 void writeBytes(String s)
          将一个字符串写入输出流。
 void writeChar(int v)
          此方法与 writeShort 同义。
 void writeChars(char[] c, int off, int len)
          将 char 序列写入到流中的当前位置。
 void writeChars(String s)
          将一个字符串写入输出流。
 void writeDouble(double v)
          将一个 double 值写入输出流,该值由四个字节组成。
 void writeDoubles(double[] d, int off, int len)
          将 double 序列写入到流中的当前位置。
 void writeFloat(float v)
          将一个 float 值(由四个字节组成)写入输出流。
 void writeFloats(float[] f, int off, int len)
          将 float 序列写入到流中的当前位置。
 void writeInt(int v)
          将 v 的 32 个位写入到流中。
 void writeInts(int[] i, int off, int len)
          将 int 序列写入到流中的当前位置。
 void writeLong(long v)
          将 v 的 64 个位写入到流中。
 void writeLongs(long[] l, int off, int len)
          将 long 序列写入到流中的当前位置。
 void writeShort(int v)
          将 v 的 16 个低位写入到流中。
 void writeShorts(short[] s, int off, int len)
          将 short 序列写入到流中的当前位置。
 void writeUTF(String s)
          将表示长度信息的两个字节按网络字节顺序写入输出流,后跟字符串 s 中每个字符的 UTF-8 修改版表示形式。
 
从接口 javax.imageio.stream.ImageInputStream 继承的方法
close, flush, getBitOffset, getByteOrder, getFlushedPosition, getStreamPosition, isCached, isCachedFile, isCachedMemory, length, mark, read, read, read, readBit, readBits, readBoolean, readByte, readBytes, readChar, readDouble, readFloat, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedShort, readUTF, reset, seek, setBitOffset, setByteOrder, skipBytes, skipBytes
 

方法详细信息

write

void write(int b)
           throws IOException
将单个字节写入到流中的当前位置。b 的 24 个高位将被忽略。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。实现方可使用 ImageOutputStreamImplflushBits 方法来保证这一点。

指定者:
接口 DataOutput 中的 write
参数:
b - 一个 int,其低 8 位将被写入。
抛出:
IOException - 如果发生 I/O 错误。

write

void write(byte[] b)
           throws IOException
将字节序列写入到流中的当前位置。如果 b.length 为 0,则不写入任何字节。首先写入字节 b[0],然后写入字节 b[1],依此类推。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 write
参数:
b - 要写入的 byte 数组。
抛出:
NullPointerException - 如果 bnull
IOException - 如果发生 I/O 错误。

write

void write(byte[] b,
           int off,
           int len)
           throws IOException
将字节序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入字节 b[off],然后写入字节 b[off + 1],依此类推。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。实现方可使用 ImageOutputStreamImplflushBits 方法来保证这一点。

指定者:
接口 DataOutput 中的 write
参数:
b - 要写入的 byte 数组。
off - 数据中的初始偏移量。
len - 要写入的 byte 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 b.length
NullPointerException - 如果 bnull
IOException - 如果发生 I/O 错误。

writeBoolean

void writeBoolean(boolean v)
                  throws IOException
将一个 boolean 值写入到流中。如果 v 为 true,则写入值 (byte)1;如果 v 为 false,则写入值 (byte)0

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeBoolean
参数:
v - 要写入的 boolean 值。
抛出:
IOException - 如果发生 I/O 错误。

writeByte

void writeByte(int v)
               throws IOException
v 的 8 个低位写入到流中。忽略 v 的 24 个高位。(这意味着 writeByte 的作用与使用整数做参数的 write 完全相同。)

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeByte
参数:
v - 一个 int,包含要写入的 byte 值。
抛出:
IOException - 如果发生 I/O 错误。

writeShort

void writeShort(int v)
                throws IOException
v 的 16 个低位写入到流中。忽略 v 的 16 个高位。如果流使用网络字节顺序,则写入的字节将依次为:
(byte)((v >> 8) & 0xff)
 (byte)(v & 0xff)
 
否则,写入的字节将为:
 (byte)(v & 0xff)
(byte)((v >> 8) & 0xff)
 

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeShort
参数:
v - 一个 int,包含要写入的 short 值。
抛出:
IOException - 如果发生 I/O 错误。

writeChar

void writeChar(int v)
               throws IOException
此方法与 writeShort 同义。

指定者:
接口 DataOutput 中的 writeChar
参数:
v - 一个 int,它包含要写入的 char(无符号 short)值。
抛出:
IOException - 如果发生 I/O 错误。
另请参见:
writeShort(int)

writeInt

void writeInt(int v)
              throws IOException
v 的 32 个位写入到流中。如果流使用网络字节顺序,则写入的字节将依次为:
(byte)((v >> 24) & 0xff)
(byte)((v >> 16) & 0xff)
(byte)((v >> 8) & 0xff)
 (byte)(v & 0xff)
 
否则,写入的字节将为:
 (byte)(v & 0xff)
(byte)((v >> 8) & 0xff)
(byte)((v >> 16) & 0xff)
(byte)((v >> 24) & 0xff)
 

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeInt
参数:
v - 一个 int,它包含要写入的值。
抛出:
IOException - 如果发生 I/O 错误。

writeLong

void writeLong(long v)
               throws IOException
v 的 64 个位写入到流中。如果流使用网络字节顺序,则写入的字节将依次为:
(byte)((v >> 56) & 0xff)
(byte)((v >> 48) & 0xff)
(byte)((v >> 40) & 0xff)
(byte)((v >> 32) & 0xff)
(byte)((v >> 24) & 0xff)
(byte)((v >> 16) & 0xff)
(byte)((v >> 8) & 0xff)
 (byte)(v & 0xff)
 
否则,写入的字节将为:
 (byte)(v & 0xff)
(byte)((v >> 8) & 0xff)
(byte)((v >> 16) & 0xff)
(byte)((v >> 24) & 0xff)
(byte)((v >> 32) & 0xff)
(byte)((v >> 40) & 0xff)
(byte)((v >> 48) & 0xff)
(byte)((v >> 56) & 0xff)
 

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeLong
参数:
v - 一个 long,它包含要写入的值。
抛出:
IOException - 如果发生 I/O 错误。

writeFloat

void writeFloat(float v)
                throws IOException
将一个 float 值(由四个字节组成)写入输出流。实现方式是:首先使用与 Float.floatToIntBits 方法完全相同的方式将此 float 值转换为一个 int 值,然后使用与 writeInt 方法完全相同的方式写入该 int 值。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeFloat
参数:
v - 一个 float,它包含要写入的值。
抛出:
IOException - 如果发生 I/O 错误。

writeDouble

void writeDouble(double v)
                 throws IOException
将一个 double 值写入输出流,该值由四个字节组成。实现这一点的方式是:首先使用与 Double.doubleToLongBits 方法相同的方式将此 double 值转换为一个 long 值,然后使用与 writeLong 方法完全相同的方式写入该 long 值。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeDouble
参数:
v - 一个 double,它包含要写入的值。
抛出:
IOException - 如果发生 I/O 错误。

writeBytes

void writeBytes(String s)
                throws IOException
将一个字符串写入输出流。字符串 s 中的每一个字符被依次写入输出流,每个字符用一个字节表示。如果 snull,则抛出 NullPointerException

如果 s.length 为零,则不写入任何字节。否则,首先写入字符 s[0],然后写入字符 s[1],依此类推;最后一个写入字符是 s[s.length-1]。对于每个字符,将使用与 writeByte 方法完全相同的方式把字符的低位写入一个低位字节。字符串中每个字符的八个高位将被忽略。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeBytes
参数:
s - 一个 String,它包含要写入的值。
抛出:
NullPointerException - 如果 snull
IOException - 如果发生 I/O 错误。

writeChars

void writeChars(String s)
                throws IOException
将一个字符串写入输出流。字符串 s 中的每个字符将根据当前字节顺序设置依次写入输出流,每个字符用两个字节表示。如果使用网络字节顺序,则首先写入高位字节;否则相反。如果 snull,则抛出 NullPointerException

如果 s.length 为零,则不写入字节。否则,首先写入字符 s[0],然后写入字符 s[1],依此类推;最后一个写入字符是 s[s.length-1]

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

指定者:
接口 DataOutput 中的 writeChars
参数:
s - 一个 String,它包含要写入的值。
抛出:
NullPointerException - 如果 snull
IOException - 如果发生 I/O 错误。

writeUTF

void writeUTF(String s)
              throws IOException
将表示长度信息的两个字节按网络字节顺序写入输出流,后跟字符串 s 中每个字符的 UTF-8 修改版表示形式。如果 snull,则抛出 NullPointerException。根据字符的值,将字符串 s 中每个字符转换成一个字节、两个字节或三个字节的字节组。

如果字符 c\u0001\u007f 的范围内,则用一个字节表示:

(byte)(b)
 

如果字符 c\u0000 或者它在 \u0080\u07ff 的范围内,则用两个字节表示,写入顺序如下:


 (byte)(0xc0 | (0x1f & (c >> 6)))
 (byte)(0x80 | (0x3f & c))
 

如果字符 c\u0800\uffff 的范围内,则用三个字节表示,写入顺序如下:


 (byte)(0xe0 | (0x0f & (c >> 12)))
 (byte)(0x80 | (0x3f & (c >> 6)))
 (byte)(0x80 | (0x3f & c))
 

首先,要计算表示 s 中所有字符所需的字节总数。如果总数大于 65535,则抛出 UTFDataFormatException。否则,使用与 writeShort 方法完全相同的方式将此长度写入输出流,然后写入字符串 s 中所有字符的 1 字节、2 字节或 3 字节表示形式。

忽略当前字节顺序设置。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

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

指定者:
接口 DataOutput 中的 writeUTF
参数:
s - 一个 String,它包含要写入的值。
抛出:
NullPointerException - 如果 snull
UTFDataFormatException - 如果 s 的 UTF-8 修改版表示形式要求的字节数大于 65536。
IOException - 如果发生 I/O 错误。

writeShorts

void writeShorts(short[] s,
                 int off,
                 int len)
                 throws IOException
将 short 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 short s[off],然后写入 short s[off + 1],依此类推。流的字节顺序用来确定写入各个字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
s - 要写入的 short 数组。
off - 数据中的初始偏移量。
len - 要写入的 short 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 s.length
NullPointerException - 如果 snull
IOException - 如果发生 I/O 错误。

writeChars

void writeChars(char[] c,
                int off,
                int len)
                throws IOException
将 char 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 char c[off],然后写入 char c[off + 1],依此类推。流的字节顺序用来确定写入个别字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
c - 要写入的 char 数组。
off - 数据中的初始偏移量。
len - 要写入的 char 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 c.length
NullPointerException - 如果 cnull
IOException - 如果发生 I/O 错误。

writeInts

void writeInts(int[] i,
               int off,
               int len)
               throws IOException
将 int 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 int i[off],然后写入 int i[off + 1],依此类推。流的字节顺序用来确定写入个别字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
i - 要写入的 int 数组。
off - 数据中的初始偏移量。
len - 要写入的 int 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 i.length
NullPointerException - 如果 inull
IOException - 如果发生 I/O 错误。

writeLongs

void writeLongs(long[] l,
                int off,
                int len)
                throws IOException
将 long 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 long l[off],然后写入 long l[off + 1],依此类推。流的字节顺序用来确定写入个别字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
l - 要写入的 long 数组。
off - 数据中的初始偏移量。
len - 要写入的 long 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 l.length
NullPointerException - 如果 lnull
IOException - 如果发生 I/O 错误。

writeFloats

void writeFloats(float[] f,
                 int off,
                 int len)
                 throws IOException
将 float 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 float f[off],然后写入 float f[off + 1],依此类推。流的字节顺序用来确定写入个别字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
f - 要写入的 float 数组。
off - 数据中的初始偏移量。
len - 要写入的 float 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 f.length
NullPointerException - 如果 fnull
IOException - 如果发生 I/O 错误。

writeDoubles

void writeDoubles(double[] d,
                  int off,
                  int len)
                  throws IOException
将 double 序列写入到流中的当前位置。如果 len 为 0,则不写入任何字节。首先写入 double d[off],然后写入 double d[off + 1],依此类推。流的字节顺序用来确定写入个别字节的顺序。

如果流中的位偏移量不为零,则首先将当前字节的余项用 0 填充并将其写出。写出后位偏移量将为 0。

参数:
d - 要写入的 double 数组。
off - 数据中的初始偏移量。
len - 要写入的 double 数。
抛出:
IndexOutOfBoundsException - 如果 off 为负、len 为负或者 off + len 大于 d.length
NullPointerException - 如果 dnull
IOException - 如果发生 I/O 错误。

writeBit

void writeBit(int bit)
              throws IOException
将单个位(由参数的最低有效位给定)写入到流的当前字节位置中的当前位偏移量。忽略参数的高 31 位。给定位将替代之前位于该位置的位。将位偏移量加 1 并将其模数减 8。

如果在刷新某个字节的缓冲并转送到目标时一直没有设置过该字节的某些位,则这些位将被自动设置为 0。

参数:
bit - 一个 int,其最低有效位将被写入到流中。
抛出:
IOException - 如果发生 I/O 错误。

writeBits

void writeBits(long bits,
               int numBits)
               throws IOException
将一个位序列(由 bits 参数的 numBits 个最低有效位按从左到右的顺序给定)写入到流的当前字节位置中的当前位偏移量。忽略参数的高 64 - numBits 位。位偏移量将加 numBits 并减少模数 8。注意,位偏移量 0 总是指示字节的最高有效位,位字节按照遇到它们的顺序依次被写入。因此以网络字节顺序进行位的写入总是有效的。忽略实际流字节顺序设置。

在调用 flushBefore 之前,位数据可以在内存中无限累积。调用时将写入刷新位置之前的所有位数据。

如果在刷新字节缓冲并转到目标时特定字节的某些位一直没有被设置,则这些位将自动设置为 0。

参数:
bits - 一个 long,它包含要写入的位(从 numBits - 1 开始下至最低有效位)。
numBits - 一个 0 到 64 之间(包括两者)的 int
抛出:
IllegalArgumentException - 如果 numBits 不在 0 到 64 之间(包括两者)。
IOException - 如果发生 I/O 错误。

flushBefore

void flushBefore(long pos)
                 throws IOException
刷新给定位置之前所有数据的缓冲并转到底层目标(如 OutputStreamFile)。试图查找流的刷新部分将导致抛出 IndexOutOfBoundsException

指定者:
接口 ImageInputStream 中的 flushBefore
参数:
pos - 一个 long,它包含可能被刷新并转到目标的流前缀的长度。
抛出:
IndexOutOfBoundsException - 如果 pos 位于流缓冲的刷新部分或当前流位置之后。
IOException - 如果发生 I/O 错误。

JavaTM Platform
Standard Ed. 6

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

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