javax.imageio
类 ImageWriter

java.lang.Object
  javax.imageio.ImageWriter

所有已实现的接口：

ImageTranscoder

public abstract class ImageWriter
extends Object
implements ImageTranscoder

用来编码和写入图像的抽象超类。此类必须由在 Java Image I/O 框架的上下文中写出图像的类为其创建子类。

通常由特定格式的服务提供者类对 ImageWriter 对象进行实例化。服务提供者类在 IIORegistry 中注册，后者使用前者进行格式识别和表示可用格式 reader 和 writer。

另请参见：

ImageReader, ImageWriteParam, IIORegistry, ImageWriterSpi

originatingProvider

protected ImageWriterSpi originatingProvider

实例化此对象的 ImageWriterSpi，如果 ImageWriterSpi 的标识是未知的或不存在，则将此对象实例化为 null。默认情况下，将此对象实例化为 null。

output

protected Object output

由 setOutput 设置并由 getOutput 获取的 ImageOutputStream 或其他 Object。默认情况下，将此对象实例化为 null。

availableLocales

protected Locale[] availableLocales

可以用来本地化警告消息和压缩设置值的 Locale 组成的数组，如果本地化不受支持，则将它们初始化为 null。默认情况下，将它们初始化为 null。

locale

protected Locale locale

用于本地化的当前 Locale，如果没有设置 Locale，则将它初始化为 null。默认情况下，将 Locale 初始化为 null。

warningListeners

protected List<IIOWriteWarningListener> warningListeners

当前已注册 IIOWriteWarningListener 的 List，默认情况下将它初始化为 null，它与空 List 同义。

warningLocales

protected List<Locale> warningLocales

Locale 的 List，warningListeners 的每个元素都有一个 Locale 列表，默认情况下该列表被初始化为 null，它与空 List 同义。

progressListeners

protected List<IIOWriteProgressListener> progressListeners

当前已注册 IIOWriteProgressListener 的 List，默认情况下将它初始化为 null，它与空 List 同义。

ImageWriter

protected ImageWriter(ImageWriterSpi originatingProvider)

构造一个 ImageWriter，并将其 originatingProvider 实例变量设置为所提供的值。

为了获取扩展对象，利用扩展的子类应该为构造方法提供签名 (ImageWriterSpi, Object)。如果扩展对象不合适，则将抛出 IllegalArgumentException。

参数：

originatingProvider - 构造此对象的 ImageWriterSpi，或者为 null。

getOriginatingProvider

public ImageWriterSpi getOriginatingProvider()

返回创建此 ImageWriter 的 ImageWriterSpi 对象，如果此对象不是通过 IIORegistry 创建的，则返回 null。

默认的实现返回 originatingProvider 实例变量的值。

返回：

一个 ImageWriterSpi 或 null。

另请参见：

ImageWriterSpi

setOutput

public void setOutput(Object output)

将目标设置为给定 ImageOutputStream 或其他 Object。假定目标已准备接受数据，并将在结束每次写入时关闭。这允许受干扰的图像处理应用程序通过单独的网络连接传输一系列图像。如果 output 为 null，则将移除所有当前已设置的输出。

如果 output 是一个 ImageOutputStream，则调用 write、writeToSequence 和 prepareWriteEmpty/endWriteEmpty 方法将保留流的现有内容。其他写入方法，比如 writeInsert、replaceStreamMetadata、replaceImageMetadata、replacePixels、prepareInsertEmpty/endInsertEmpty 和 endWriteSequence，要求可读取和写入该流的全部内容，并且可以更改该流的任何部分。

对于直接与输出设备或图像协议交互的 writer，打算使用一般的 Object，而不是使用 ImageOutputStream。合法类集是由 writer 的服务提供者的 getOutputTypes 方法公开的。大多数 writer 将返回一个单个元素组成的数组，该数组只包含指示它们只接受 ImageOutputStream 的 ImageOutputStream.class。

在根据原始提供者（如果有）公开的类集合检查 output 之后，默认实现将 output 实例变量设置为 output 的值。

参数：

output - 用于以后的写入的 ImageOutputStream 或其他 Object。

抛出：

IllegalArgumentException - 如果 output 不是原始服务提供者的 getOutputTypes 方法返回的某个类的实例。

另请参见：

getOutput()

getOutput

public Object getOutput()

返回 ImageOutputStream 或最近一次调用 setOutput 方法设置的其他 Object如果没有设置目标，则返回 null。

默认实现返回 output 实例变量的值。

返回：

使用 setOutput 指定的 Object，或者返回 null。

另请参见：

setOutput(java.lang.Object)

getAvailableLocales

public Locale[] getAvailableLocales()

返回可用来初始化警告侦听器和压缩设置的 Locale 组成的数组。返回 null 值指示初始化不受支持。

如果 availableLocales 实例变量是非 null 的，则默认实现返回该变量的副本，否则返回 null。

返回：

可能用作 setLocale 的参数的 Locale 组成的数组，或者返回 null。

setLocale

public void setLocale(Locale locale)

将此 ImageWriter 的当前 Locale 设置为给定值。值为 null 则移除所有以前的设置，并指示 writer 应该根据需要对其进行初始化。

默认实现根据 getAvailableLocales 返回的值检查 locale，并设置 locale 实例变量（如果查找到的话）。如果 locale 为 null，则将该实例变量设置为 null，不必执行任何检查。

参数：

locale - 所需的 Locale，或者为 null。

抛出：

IllegalArgumentException - 如果 locale 为非 null，但它不是 getAvailableLocales 返回的值之一。

另请参见：

getLocale()

getLocale

public Locale getLocale()

返回当前设置的 Locale，如果没有设置 Locale，则返回 null。

默认实现返回 locale 实例变量的值。

返回：

当前 Locale 或 null。

另请参见：

setLocale(java.util.Locale)

getDefaultWriteParam

public ImageWriteParam getDefaultWriteParam()

返回适用于此文件格式的适当类型的新 ImageWriteParam 对象，该对象包含默认值，即那些将在没有指定 ImageWriteParam 对象时使用的值。将此作为只调整少数几个参数并不管默认设置的起点很有用。

默认设置构造并返回一个新的 ImageWriteParam 对象，该对象不允许平铺、逐步编码或压缩，并且将针对当前 Locale（即 通过调用 new ImageWriteParam(getLocale()) 获得的 Locale）对该对象进行本地化。

个别插件可能在启用额外可选特性的情况下返回 ImageWriteParam 的实例，或者它们可以返回 ImageWriteParam 的特定于插件的子类的实例。

返回：

包含默认值的新的 ImageWriteParam 对象。

getDefaultStreamMetadata

public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)

返回包含用来对图像流进行编码的默认值的 IIOMetadata 对象。该对象的内容可以使用由 IIOMetadata.getAsTree 方法返回的 XML 树型结构（一个 IIOMetadataController 对象）来操作，或者通过特定于插件的接口以及提供给某一带有流元数据参数的 write 方法的所得数据来操作。

可以对可能影响流元数据结构的情况提供一个可选的 ImageWriteParam。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

不使用流元数据的 writer（例如 用于单一图像格式的 writer）应该返回 null。

参数：

param - 将用于对图像进行编码的 ImageWriteParam，或者为 null。

返回：

IIOMetadata 对象。

getDefaultImageMetadata

public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                                    ImageWriteParam param)

返回包含用来编码给定类型图像的默认值的 IIOMetadata 对象。该对象的内容可以使用由 IIOMetadata.getAsTree 方法返回的 XML 树型结构（一个 IIOMetadataController 对象）来操作，或者通过特定于插件的接口以及提供给某一带有流元数据参数的 write 方法的所得数据来操作。

可以对可能影响图像元数据结构的情况提供一个可选的 ImageWriteParam。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

参数：

imageType - 指示稍后将写入的图像格式的 ImageTypeSpecifier。

param - 将用于对图像进行编码的 ImageWriteParam，或者为 null。

返回：

IIOMetadata 对象。

convertStreamMetadata

public abstract IIOMetadata convertStreamMetadata(IIOMetadata inData,
                                                  ImageWriteParam param)

从接口 ImageTranscoder 复制的描述

返回一个 IIOMetadata 对象，该对象可用于编码，并且可以使用其文档接口或特定于将用于编码的 writer 插件的其他接口有选择地对其进行修改。

可以提供一个可选的 ImageWriteParam，用于其能影响流元数据的结构的情况。

如果所提供的 ImageWriteParam 包含可选的、不被此 writer 或 transcoder 理解的设置值，则忽略这些值。

指定者：

接口 ImageTranscoder 中的 convertStreamMetadata

参数：

inData - 表示流元数据的 IIOMetadata 对象，用于初始化所返回对象的状态。

param - 将用于对图像进行编码的 ImageWriteParam，或者为 null。

返回：

一个 IIOMetadata 对象，如果插件没有提供元数据编码功能，则返回 null。

convertImageMetadata

public abstract IIOMetadata convertImageMetadata(IIOMetadata inData,
                                                 ImageTypeSpecifier imageType,
                                                 ImageWriteParam param)

从接口 ImageTranscoder 复制的描述

返回一个 IIOMetadata 对象，该对象可用于编码，并且可以使用其文档接口或特定于将用于编码的 writer 插件的其他接口有选择地对其进行修改。

可以提供一个可选的 ImageWriteParam，用于其能影响图像元数据的结构的情况。

如果所提供的 ImageWriteParam 包含可选的、不被此 writer 或 transcoder 理解的设置值，则忽略这些值。

指定者：

接口 ImageTranscoder 中的 convertImageMetadata

参数：

inData - 表示图像元数据的 IIOMetadata 对象，用于初始化所返回对象的状态。

imageType - 指示将与元数据关联的图像的布局和颜色信息的 ImageTypeSpecifier。

param - 将用于对图像进行编码的 ImageWriteParam，或者为 null。

返回：

一个 IIOMetadata 对象，如果插件没有提供元数据编码功能，则返回 null。

getNumThumbnailsSupported

public int getNumThumbnailsSupported(ImageTypeSpecifier imageType,
                                     ImageWriteParam param,
                                     IIOMetadata streamMetadata,
                                     IIOMetadata imageMetadata)

返回受将写入的格式、给定图像类型和任何其他 write 参数支持的缩略图，以及将在编码期间使用的元数据对象。返回 -1 值指示可用信息不足。

可以对可能影响缩略图处理的情况有选择地提供 ImageWriteParam。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

默认实现返回 0。

参数：

imageType - 指示将写入的图像类型的 ImageTypeSpecifier，或者该参数为 null。

param - 将用于写入操作的 ImageWriteParam，或者为 null。

streamMetadata - 将用于写入操作的 IIOMetadata 对象，或者为 null。

imageMetadata - 将用于写入操作的 IIOMetadata 对象，或者为 null。

返回：

可能在已知所提供参数的情况下写入的缩略图数，如果可用信息不足，则返回 -1。

getPreferredThumbnailSizes

public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
                                              ImageWriteParam param,
                                              IIOMetadata streamMetadata,
                                              IIOMetadata imageMetadata)

返回一个 Dimension 数组，指示在输出文件或流中进行编码时合法的缩略图大小范围。此信息只是建议性的；writer 将根据需要重新调整所提供缩略图的大小。

信息是作为 pair 的集合返回的；pair 的第一个元素包含最小宽度和高度，第二个元素包含最大宽度和高度。同时，每个 pair 定义一个有效大小范围。要定义固定大小，将对两个元素显示相同的宽度和高度。返回值为 null 指示大小是任意的或未知的。

可以对可能影响缩略图处理的情况有选择地提供 ImageWriteParam。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

默认实现返回 null。

参数：

imageType - 指示将写入的图像类型的 ImageTypeSpecifier，或者该参数为 null。

param - 将用于写入操作的 ImageWriteParam，或者为 null。

streamMetadata - 将用于写入操作的 IIOMetadata 对象，或者为 null。

imageMetadata - 将用于写入操作的 IIOMetadata 对象，或者为 null。

返回：

平均长度至少为 2 的 Dimension 组成的数组，或者返回 null。

canWriteRasters

public boolean canWriteRasters()

如果采用 IIOImage 参数的方法能够处理 Raster（相对于 RenderedImage）源图像，则返回 true。如果此方法返回 false，则这些方法将在包含 Raster 的 IIOImage 中抛出一个 UnsupportedOperationException（如果提供）。

默认实现返回 false。

返回：

如果 Raster 源受支持，则返回 true。

write

public abstract void write(IIOMetadata streamMetadata,
                           IIOImage image,
                           ImageWriteParam param)
                    throws IOException

添加一个完整的图像流，该图像流包含一幅图像、相关的流、图像元数据和要输出的缩略图。还包括任何必要的头信息。如果输出是一个 ImageOutputStream，则位于当前寻找位置之前的现有内容不受影响，并且这些内容不必是可读或可写的。

必须使用 setOutput 方法提前设置输出。

流元数据可以有选择地提供；如果它为 null，则使用默认元数据。

如果 canWriteRasters 返回 true，则 IIOImage 可以包含一个 Raster 源。否则，它必须包含一个 RenderedImage 源。

所提供的缩略图将被重新调整大小（如果需要），并且超过所支持数量的所有缩略图都将被忽略。如果该格式需要没有提供的额外缩略图，则 writer 应该在内部生成这些缩略图。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

参数：

streamMetadata - 表示流元数据的 IIOMetadata 对象，或者为 null，表示使用默认值。

image - 包含要写入的图像、缩略图和元数据的 IIOImage 对象。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 image 包含一个 Raster，并且 canWriteRasters 返回 false。

IllegalArgumentException - 如果 image 为 null。

IOException - 如果在写入过程中发生错误。

write

public void write(IIOImage image)
           throws IOException

将包含带有默认元数据和缩略图的单个图像的完整图像流添加到输出中。此方法是 write(null, image, null) 的简略表达方式。

参数：

image - 包含要写入的图像、缩略图和元数据的 IIOImage 对象。

抛出：

IllegalStateException - 如果尚未设置输出。

IllegalArgumentException - 如果 image 为 null。

UnsupportedOperationException - 如果 image 包含一个 Raster，并且 canWriteRasters 返回 false。

IOException - 如果在写入过程中发生错误。

write

public void write(RenderedImage image)
           throws IOException

将由带有默认元数据和缩略图的单个图像组成的完整图像流添加到输出中。此方法是 write(null, new IIOImage(image, null, null), null) 的简略表达方式。

参数：

image - 要写入的 RenderedImage。

抛出：

IllegalStateException - 如果尚未设置输出。

IllegalArgumentException - 如果 image 为 null。

IOException - 如果在写入过程中发生错误。

canWriteSequence

public boolean canWriteSequence()

如果 writer 能够将图像添加到已经包含头信息和可能的以前图像的图像流中，则返回 true。

如果 canWriteSequence 返回 false，writeToSequence 和 endWriteSequence 将抛出 UnsupportedOperationException。

默认实现返回 false。

返回：

如果可以按顺序添加图像，则返回 true。

prepareWriteSequence

public void prepareWriteSequence(IIOMetadata streamMetadata)
                          throws IOException

使用提供的流元数据对象准备一个流，以接受一系列的后续 writeToSequence 调用。如果应该先于图像数据，则应该将元数据写入流中。如果该参数为 null，则使用默认流元数据。

如果输出是一个 ImageOutputStream，则不刷新位于当前寻找位置之前的输出的现有内容，并且这些内容不必是可读或可写的。如果该格式要求 endWriteSequence 能够重新修补头信息，比如用于单个 TIFF 文件中的一系列图像的头信息，则此方法写入的元数据必须仍然位于流的可写部分中。其他格式可以在此方法之后和每幅图像之后刷新流。

如果 canWriteSequence 返回 false，则此方法将抛出 UnsupportedOperationException。

必须使用 setOutput 方法提前设置输出。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

streamMetadata - 一个流元数据对象，或者为 null。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canWriteSequence 返回 false。

IOException - 如果在写入流元数据过程中发生错误。

writeToSequence

public void writeToSequence(IIOImage image,
                            ImageWriteParam param)
                     throws IOException

将单幅图像、可能相关的元数据和缩略图添加到输出中。如果输出是 ImageOutputStream，则可能刷新当前寻找位置之前的输出的现有内容，并且这些内容不必是可读的或可写的，除非插件必须能够在调用 endWriteSequence 时修补头信息（例如 TIFF）。

如果 canWriteSequence 返回 false，则此方法将抛出 UnsupportedOperationException。

必须使用 setOutput 方法提前设置输出。

prepareWriteSequence 必须提前调用，否则将抛出 IllegalStateException。

如果 canWriteRasters 返回 true，则 IIOImage 可以包含一个 Raster 源。否则，它必须包含一个 RenderedImage 源。

所提供的缩略图将被重新调整大小（如果需要），并且超过所支持数量的所有缩略图都将被忽略。如果该格式需要没有提供的其他缩略图，则 writer 将在内部生成这些缩略图。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

image - 包含要写入的图像、缩略图和元数据的 IIOImage 对象。

param - 一个 ImageWriteParam；或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果没有设置输出，或者没有调用 prepareWriteSequence。

UnsupportedOperationException - 如果 canWriteSequence 返回 false。

IllegalArgumentException - 如果 image 为 null。

UnsupportedOperationException - 如果 image 包含一个 Raster，并且 canWriteRasters 返回 false。

IOException - 如果写入过程中发生错误。

endWriteSequence

public void endWriteSequence()
                      throws IOException

完成以 prepareWriteSequence 开头的一系列图像的写入。应该出现在这一系列图像的末尾的所有流元数据都被写出，如果需要，可修补位于该序列的开始处的任何头信息。如果输出是 ImageOutputStream，则一直到序列末尾处的流元数据的那些数据将被刷新，它们不必是可读的或可写的。

如果 canWriteSequence 返回 false，则此方法将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

抛出：

IllegalStateException - 如果没有设置输出，或者没有调用 prepareWriteSequence。

UnsupportedOperationException - 如果 canWriteSequence 返回 false。

IOException - 如果在写入过程中发生错误。

canReplaceStreamMetadata

public boolean canReplaceStreamMetadata()
                                 throws IOException

如果有可能替换已存在于输出中的流元数据，则返回 true。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false。

返回：

如果允许替换流元数据，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IOException - 如果在查询期间发生 I/O 错误。

replaceStreamMetadata

public void replaceStreamMetadata(IIOMetadata streamMetadata)
                           throws IOException

使用新信息替换输出中的流元数据。如果输出为 ImageOutputStream，则检查该流以前的内容，并且可能对它们进行编辑，为新的数据腾出空间。该输出以前的所有内容必须可用于读取和写入。

如果 canReplaceStreamMetadata 返回 false，则将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

streamMetadata - 表示流元数据的 IIOMetadata 对象；或者为 null，表示使用默认值。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplaceStreamMetadata 返回 false。模式不包括在内

IOException - 如果写入期间发生错误。

canReplaceImageMetadata

public boolean canReplaceImageMetadata(int imageIndex)
                                throws IOException

如果有可能使用索引 imageIndex 替换与现有图像有关的图像元数据，则返回 true。如果此方法返回 false，那么调用 replaceImageMetadata(imageIndex) 将抛出 UnsupportedOperationException。

不支持任何图像元数据替换的 writer 可以返回 false，而不必对索引执行范围检查。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false，而不必检查 imageIndex 的值。

参数：

imageIndex - 其元数据将被替换的图像的索引。

返回：

如果可以替换给定图像的图像元数据，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IndexOutOfBoundsException - 如果 writer 在一般情况下支持图像元数据替换，但 imageIndex 小于 0 或大于最大可用索引。

IOException - 如果在查询期间发生 I/O 错误。

replaceImageMetadata

public void replaceImageMetadata(int imageIndex,
                                 IIOMetadata imageMetadata)
                          throws IOException

替换与现有图像有关的图像元数据。

如果 canReplaceImageMetadata(imageIndex) 返回 false，则将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

imageIndex - 其元数据将被替换的图像的索引。

imageMetadata - 表示图像元数据的 IIOMetadata 对象，或者为 null。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplaceImageMetadata 返回 false。

IndexOutOfBoundsException - 如果 imageIndex 小于 0 或大于最大可用索引。

IOException - 如果在写入过程中发生错误。

canInsertImage

public boolean canInsertImage(int imageIndex)
                       throws IOException

如果 writer 支持在给定索引处插入新图像，则返回 true。索引等于或大于插入索引的现有图像会将其索引加 1。值为 -1 的 imageIndex 可用于表示大于当前最大索引的索引。

不支持任何图像插入的 writer 可以返回 false，而不必对索引执行范围检查。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false，而不必检查 imageIndex 的值。

参数：

imageIndex - 将在其所在位置处插入图像的索引。

返回：

如果可以在给定索引处插入图像，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IndexOutOfBoundsException - 如果 writer 在一般情况下支持图像插入，但 imageIndex 小于 -1 或大于最大可用索引。

IOException - 如果在查询期间发生 I/O 错误。

writeInsert

public void writeInsert(int imageIndex,
                        IIOImage image,
                        ImageWriteParam param)
                 throws IOException

将新的图像插入现有图像流。索引大于 imageIndex 的现有图像被保留，其索引均被加 1。为 -1 的 imageIndex 值可用于表示大于以前最大索引的索引；也就是说，它将导致图像按逻辑添加到序列的末尾。如果输出是一个 ImageOutputStream，则整个流都必须是可读并且可写的。

如果 canInsertImage(imageIndex) 返回 false，则将抛出 UnsupportedOperationException。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

imageIndex - 将在其所在位置处写入图像的索引。

image - 包含要写入的图像、缩略图和元数据的 IIOImage 对象。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canInsertImage(imageIndex) 返回 false。

IllegalArgumentException - 如果 image 为 null。

IndexOutOfBoundsException - 如果 imageIndex 小于 -1 或大于最大可用索引。

UnsupportedOperationException - 如果 image 包含一个 Raster，并且 canWriteRasters 返回 false。

IOException - 如果在写入过程中发生错误。

canRemoveImage

public boolean canRemoveImage(int imageIndex)
                       throws IOException

如果 writer 支持在给定索引处移除现有图像，则返回 true。对于索引大于插入索引的图像，其索引将增加 1。

不支持任何图像移除的 writer 可以返回 false，而不必对索引执行范围检查。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false，而不必检查 imageIndex 的值。

参数：

imageIndex - 要移除的图像的索引。

返回：

如果能够移除给定图像，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IndexOutOfBoundsException - 如果 writer 在一般情况下支持图像移除，但 imageIndex 小于 0 或大于最大可用索引。

IOException - 如果在查询期间发生 I/O 错误。

removeImage

public void removeImage(int imageIndex)
                 throws IOException

从流中移除图像。

如果 canRemoveImage(imageIndex) 返回 false，则将抛出 UnsupportedOperationException。

移除可能导致实际文件大小减小，也可能不会。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

imageIndex - 要移除的图像的索引。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canRemoveImage(imageIndex) 返回 false。

IndexOutOfBoundsException - 如果 imageIndex 小于 0 或大于最大可用索引。

IOException - 如果在移除期间发生 I/O 错误。

canWriteEmpty

public boolean canWriteEmpty()
                      throws IOException

如果 writer 支持写入由单个图像组成的完整图像流，则返回 true，这些对象带有要输出的不确定像素值、有关元数据和缩略图。像素值可通过以后调用 replacePixels 方法来确定。如果输出是一个 ImageOutputStream，则位于当前寻找位置之前的现有内容不受影响，并且这些内容不必是可读或可写的。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false。

返回：

如果写入内容以后再定义的完整图像流是受支持的，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IOException - 如果在查询期间发生 I/O 错误。

prepareWriteEmpty

public void prepareWriteEmpty(IIOMetadata streamMetadata,
                              ImageTypeSpecifier imageType,
                              int width,
                              int height,
                              IIOMetadata imageMetadata,
                              List<? extends BufferedImage> thumbnails,
                              ImageWriteParam param)
                       throws IOException

从写入完整图像流开始，该图像流由带有要输出的不确定像素值、有关元数据和缩略图的单个图像组成。像素值可通过以后调用 replacePixels 方法来确定。如果输出是一个 ImageOutputStream，则位于当前寻找位置之前的现有内容不受影响，并且这些内容不必是可读或可写的。

直到调用 endWriteEmpty 才完成写入操作。调用 prepareReplacePixels、replacePixels 和 endReplacePixels 可能发生在调用 prepareWriteEmpty 和 endWriteEmpty 之间。不过，调用 prepareWriteEmpty 是不可嵌套的，调用 prepareWriteEmpty 和 prepareInsertEmpty 不能被散置。

如果 canWriteEmpty 返回 false，则将抛出 UnsupportedOperationException。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

streamMetadata - 表示流元数据的 IIOMetadata 对象；或者为 null，表示使用默认值。

imageType - 描述图像布局的 ImageTypeSpecifier。

width - 图像的宽度。

height - 图像的高度。

imageMetadata - 表示图像元数据的 IIOMetadata 对象，或者为 null。

thumbnails - 此图像的 BufferedImage 缩略图的 List，或者为 null。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canWriteEmpty 返回 false。

IllegalStateException - 如果以前已经调用 prepareWriteEmpty，但没有相应地调用 endWriteEmpty。

IllegalStateException - 如果以前已经调用 prepareInsertEmpty，但没有相应地调用 endInsertEmpty。

IllegalArgumentException - 如果 imageType 为 null，或者 thumbnails 包含 null 引用或对象，而不是 BufferedImage。

IllegalArgumentException - 如果宽度或高度小于 1。

IOException - 如果在写期间发生 I/O 错误。

endWriteEmpty

public void endWriteEmpty()
                   throws IOException

完成对新图像的写入，该操作是从优先调用 prepareWriteEmpty 开始的。

如果 canWriteEmpty() 返回 false，则将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canWriteEmpty(imageIndex) 返回 false。

IllegalStateException - 如果以前已经调用 prepareWriteEmpty，但没有相应地调用 endWriteEmpty。

IllegalStateException - 如果以前已经调用 prepareInsertEmpty，但没有相应地调用 endInsertEmpty。

IllegalStateException - 如果以前已经调用 prepareReiplacePixels，但没有相应地调用 endReplacePixels。

IOException - 如果在写入期间发生 I/O 错误。

canInsertEmpty

public boolean canInsertEmpty(int imageIndex)
                       throws IOException

如果 writer 支持在给定索引处插入新的空图像，则返回 true。图像的像素值是不确定的，并且可以使用 replacePixels 方法各个部分地指定它们。索引等于或大于插入索引的现有图像会将其索引加 1。值为 -1 的 imageIndex 可用于表示大于当前最大索引的索引。

不支持插入空图像的 writer 可以返回 false，而不必对索引执行范围检查。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false，而不必检查 imageIndex 的值。

参数：

imageIndex - 将在其所在位置处插入图像的索引。

返回：

如果可以在给定索引处插入空图像，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IndexOutOfBoundsException - 如果 writer 在一般情况下支持插入空图像，但 imageIndex 小于 -1 或大于最大可用索引。

IOException - 如果在查询期间发生 I/O 错误。

prepareInsertEmpty

public void prepareInsertEmpty(int imageIndex,
                               ImageTypeSpecifier imageType,
                               int width,
                               int height,
                               IIOMetadata imageMetadata,
                               List<? extends BufferedImage> thumbnails,
                               ImageWriteParam param)
                        throws IOException

从将带有不确定像素值的新图像插入现有图像流中开始。索引大于 imageIndex 的现有图像被保留，其索引均被加 1。为 -1 的 imageIndex 值可用于表示大于以前最大索引的索引；也就是说，它将导致图像按逻辑添加到序列的末尾。如果输出是一个 ImageOutputStream，则整个流都必须是可读并且可写的。

图像内容可由稍后使用的 replacePixels 方法提供。直到调用 endInsertEmpty 才完成插入操作。调用 prepareReplacePixels、replacePixels 和 endReplacePixels 可能发生在调用 prepareInsertEmpty 和 endInsertEmpty 之间。不过，调用 prepareInsertEmpty 是不可嵌套的，调用 prepareWriteEmpty 和 prepareInsertEmpty 不能被散置。

如果 canInsertEmpty(imageIndex) 返回 false，则将抛出 UnsupportedOperationException。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

imageIndex - 将在其所在位置处写入图像的索引。

imageType - 描述图像布局的 ImageTypeSpecifier。

width - 图像的宽度。

height - 图像的高度。

imageMetadata - 表示图像元数据的 IIOMetadata 对象，或者为 null。

thumbnails - 此图像的 BufferedImage 缩略图的 List，或者为 null。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canInsertEmpty(imageIndex) 返回 false。

IndexOutOfBoundsException - 如果 imageIndex 小于 -1 或大于最大可用索引。

IllegalStateException - 如果以前已经调用 prepareInsertEmpty，但没有相应地调用 endInsertEmpty。

IllegalStateException - 如果以前已经调用 prepareWriteEmpty，但没有相应地调用 endWriteEmpty。

IllegalArgumentException - 如果 imageType 为 null，或者 thumbnails 包含 null 引用或对象，而不是 BufferedImage。

IllegalArgumentException - 如果宽度或高度小于 1。

IOException - 如果在写期间发生 I/O 错误。

endInsertEmpty

public void endInsertEmpty()
                    throws IOException

完成对新图像的插入，该操作是从以前调用 prepareInsertEmpty 开始的。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canInsertEmpty(imageIndex) 返回 false。

IllegalStateException - 如果以前已经调用 prepareInsertEmpty，但没有相应地调用 endInsertEmpty。

IllegalStateException - 如果以前已经调用 prepareWriteEmpty，但没有相应地调用 endWriteEmpty。

IllegalStateException - 如果以前已经调用 prepareReplacePixels，但没有相应地调用 endReplacePixels。

IOException - 如果在写入期间发生 I/O 错误。

canReplacePixels

public boolean canReplacePixels(int imageIndex)
                         throws IOException

如果 writer 允许使用 replacePixels 方法替换给定图像的索引，则返回 true。

不支持任何像素替换的 writer 可以返回 false，而不必对索引执行范围检查。

如果输出为 null，则默认实现抛出 IllegalStateException，否则返回 false，而不必检查 imageIndex 的值。

参数：

imageIndex - 其像素将被替换的图像的索引。

返回：

如果可以替换给定图像的像素，则返回 true。

抛出：

IllegalStateException - 如果尚未设置输出。

IndexOutOfBoundsException - 如果 writer 在一般情况下支持像素替换，但 imageIndex 小于 0 或大于最大可用索引。

IOException - 如果在查询期间发生 I/O 错误。

prepareReplacePixels

public void prepareReplacePixels(int imageIndex,
                                 Rectangle region)
                          throws IOException

准备好 writer，处理一系列对 replacePixels 方法的调用。将根据所提供的数据来剪切受影响的像素区域。

如果 canReplacePixels 返回 false，则将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

imageIndex - 其像素将被替换的图像的索引。

region - 将用来剪切将来的像素区域的 Rectangle。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplacePixels(imageIndex) 返回 false。

IndexOutOfBoundsException - 如果 imageIndex 小于 0 或大于最大可用索引。

IllegalStateException - 如果以前调用了 prepareReplacePixels 但没有相应地调用 endReplacePixels（也就是说 不允许进行嵌套）。

IllegalArgumentException - 如果 region 为 null 或者宽度或高度小于 1。

IOException - 如果在准备期间发生 I/O 错误。

replacePixels

public void replacePixels(RenderedImage image,
                          ImageWriteParam param)
                   throws IOException

用给定图像部分替换已出现在输出中的图像部分。图像数据必须匹配，或者可转化为现有图像布局。

目标区域是在 param 参数中指定的，并且将被剪切成图像边界和提供给 prepareReplacePixels 的区域。至少有一个源像素不能剪切，否则抛出一个异常。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

此方法只能在调用 prepareReplacePixels 之后调用，否则将抛出 IllegalStateException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

image - 一个包含源像素的 RenderedImage。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplacePixels(imageIndex) 返回 false。

IllegalStateException - 如果在以前调用 prepareReplacePixels 时没有相应地调用 endReplacePixels。

IllegalArgumentException - 如果以下任意一项为 true：

• image 为 null。
• param 为 null。
• 相交区域并没有包含至少一个像素。
• image 的布局与现有图像布局不匹配，或者此 writer 无法将它转换成现有图像布局。

IOException - 如果在写入期间发生 I/O 错误。

replacePixels

public void replacePixels(Raster raster,
                          ImageWriteParam param)
                   throws IOException

用给定 Raster 部分替换已出现在输出中的图像部分。图像数据必须匹配，或者可转化为现有图像布局。

可以有选择地提供 ImageWriteParam 来控制写入过程。如果 param 为 null，则将使用默认 write 参数。

目标区域是在 param 参数中指定的，并且将被剪切成图像边界和提供给 prepareReplacePixels 的区域。至少有一个源像素不能剪切，否则抛出一个异常。

如果所提供的 ImageWriteParam 包含不受此 writer 支持的可选设置值（例如 逐步编码或任何特定于格式的设置），则将忽略这些设置。

此方法只能在调用 prepareReplacePixels 之后调用，否则将抛出 IllegalStateException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

参数：

raster - 一个包含源像素的 Raster。

param - 一个 ImageWriteParam，或者为 null，表示使用默认 ImageWriteParam。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplacePixels(imageIndex) 返回 false。

IllegalStateException - 如果在以前调用 prepareReplacePixels 时没有相应地调用 endReplacePixels。

UnsupportedOperationException - 如果 canWriteRasters 返回 false。

IllegalArgumentException - 如果以下任意一项为 true：

• raster 为 null。
• param 为 null。
• 相交区域并没有包含至少一个像素。
• raster 的布局与现有图像布局不匹配，或者此 writer 无法将它转换成现有图像布局。

IOException - 如果在写入期间发生 I/O 错误。

endReplacePixels

public void endReplacePixels()
                      throws IOException

终止调用 replacePixels 的序列。

如果 canReplacePixels 返回 false，则将抛出 UnsupportedOperationException。

如果输出为 null，则默认实现抛出 IllegalStateException，否则抛出 UnsupportedOperationException。

抛出：

IllegalStateException - 如果尚未设置输出。

UnsupportedOperationException - 如果 canReplacePixels(imageIndex) 返回 false。

IllegalStateException - 如果在以前调用 prepareReplacePixels 时没有相应地调用 endReplacePixels。

IOException - 如果在写入期间发生 I/O 错误。

abort

public void abort()

请求中止任何当前写入操作。将中止的输出的内容是不确定的。

weader 应该在开始每个写入操作时调用 clearAbortRequest，并在写入期间定期轮询 abortRequested 的值。

abortRequested

protected boolean abortRequested()

如果自从 writer 被实例化或 clearAbortRequest 被调用开始，已经发出中止当前写入操作的请求，则返回 true。

返回：

如果应该中止当前写入操作，则返回 true。

另请参见：

abort(), clearAbortRequest()

clearAbortRequest

protected void clearAbortRequest()

清除任何以前的中止请求。在已调用此方法之后，abortRequested 将返回 false。

另请参见：

abort(), abortRequested()

addIIOWriteWarningListener

public void addIIOWriteWarningListener(IIOWriteWarningListener listener)

将 IIOWriteWarningListener 添加到已注册的警告侦听器的列表中。如果 listener 为 null，则不会抛出异常并且不执行操作。发送到给定侦听器的消息将被初始化，如果有可能，会将该消息与当前 Locale 匹配。如果没有设置 Locale，则可将警告消息初始化为 writer 认为合适的形式。

参数：

listener - 要注册的 IIOWriteWarningListener。

另请参见：

removeIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener)

removeIIOWriteWarningListener

public void removeIIOWriteWarningListener(IIOWriteWarningListener listener)

从已注册的警告侦听器列表中移除 IIOWriteWarningListener。如果以前没有注册侦听器，或者 listener 为 null，则不会抛出异常并且不执行操作。

参数：

listener - 要取消注册的 IIOWriteWarningListener。

另请参见：

addIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener)

removeAllIIOWriteWarningListeners

public void removeAllIIOWriteWarningListeners()

移除所有当前已注册的 IIOWriteWarningListener 对象。

默认实现将 warningListeners 和 warningLocales 实例变量设置为 null。

addIIOWriteProgressListener

public void addIIOWriteProgressListener(IIOWriteProgressListener listener)

将 IIOWriteProgressListener 添加到已注册的进度侦听器列表中。如果 listener 为 null，则不会抛出异常并且不执行操作。

参数：

listener - 要注册的 IIOWriteProgressListener。

另请参见：

removeIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener)

removeIIOWriteProgressListener

public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)

从已注册的进度侦听器列表中移除 IIOWriteProgressListener。如果以前没有注册侦听器，或者 listener 为 null，则不会抛出异常并且不执行操作。

参数：

listener - 要取消注册的 IIOWriteProgressListener。

另请参见：

addIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener)

removeAllIIOWriteProgressListeners

public void removeAllIIOWriteProgressListeners()

移除所有当前已注册的 IIOWriteProgressListener 对象。

默认实现将 progressListeners 实例变量设置为 null。

processImageStarted

protected void processImageStarted(int imageIndex)

通过调用 imageStarted 方法向所有已注册 IIOWriteProgressListener 广播开始写入图像的起始处。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 即将写入的图像的索引。

processImageProgress

protected void processImageProgress(float percentageDone)

通过调用 imageProgress 方法向所有已注册 IIOWriteProgressListener 广播图像完成的当前百分比。子类可以将此方法用作一个便捷方法。

参数：

percentageDone - float 值形式的当前完整的百分比。

processImageComplete

protected void processImageComplete()

通过调用 imageComplete 方法向所有已注册 IIOWriteProgressListener 广播图像写入的完成。子类可以将此方法用作一个便捷方法。

processThumbnailStarted

protected void processThumbnailStarted(int imageIndex,
                                       int thumbnailIndex)

通过调用 thumbnailStarted 方法向所有已注册 IIOWriteProgressListener 广播缩略图写入的起始处。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 与该缩略图有关的图像的索引。

thumbnailIndex - 缩略图的索引。

processThumbnailProgress

protected void processThumbnailProgress(float percentageDone)

通过调用 thumbnailProgress 方法向所有已注册 IIOWriteProgressListener 广播缩略图完成的当前百分比。子类可以将此方法用作一个便捷方法。

参数：

percentageDone - float 值形式的当前完整的百分比。

processThumbnailComplete

protected void processThumbnailComplete()

通过调用 thumbnailComplete 方法向所有已注册 IIOWriteProgressListener 广播缩略图写入的完成。子类可以将此方法用作一个便捷方法。

processWriteAborted

protected void processWriteAborted()

通过调用 readAborted 方法向对所有已注册 IIOWriteProgressListener 广播写入已经中止。子类可以将此方法用作一个便捷方法。

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                                      String warning)

通过调用 warningOccurred 方法向所有已注册 IIOWriteWarningListener 广播一条警告消息。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 与发生的警告有关的图像的索引。

warning - 警告消息。

抛出：

IllegalArgumentException - 如果 warning 为 null。

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                                      String baseName,
                                      String keyword)

通过使用取自 ResourceBundle 的字符串调用 warningOccurred 方法来向所有已注册 IIOWriteWarningListener 广播一条本地化警告消息。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 与发生的警告有关的图像的索引。

baseName - 一组包含本地化警告消息的 ResourceBundle 的基本名称。

keyword - 用来为 ResourceBundle 集合中的警告消息建立索引的关键字。

抛出：

IllegalArgumentException - 如果 baseName 为 null。

IllegalArgumentException - 如果 keyword 为 null。

IllegalArgumentException - 如果无法找到合适的 ResourceBundle。

IllegalArgumentException - 如果在定位的 ResourceBundle 中无法找到指定的资源。

IllegalArgumentException - 如果从 ResourceBundle 中获取的对象不是一个 String。

reset

public void reset()

将 ImageWriter 恢复到其初始状态。

默认实现调用 setOutput(null)、setLocale(null)、removeAllIIOWriteWarningListeners()、removeAllIIOWriteProgressListeners() 和 clearAbortRequest。

dispose

public void dispose()

允许释放此对象保存的所有资源。调用其他任何方法（而不是 finalize）以及对此方法的后续调用的结果都是不确定的。

对应用程序而言，在知道它们不再使用此 ImageWriter 时，调用此方法非常重要。否则，writer 可能继续无限期地保存这些资源。

在超类中，此方法的默认实现不执行任何操作。子类实现应该确保所有资源（特别是本机资源）被释放。

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