javax.imageio
类 ImageIO

java.lang.Object
  javax.imageio.ImageIO

public final class ImageIO
extends Object

该类包含一些用来查找 ImageReader 和 ImageWriter 以及执行简单编码和解码的静态便捷方法。

scanForPlugins

public static void scanForPlugins()

扫描应用程序类路径上的插件，加载其服务提供者类，并使用 IIORegistry 为每一个找到的插件注册一个服务提供者实例。

需要此方法是因为应用程序类路径在理论上是可以更改的，或者说附加的插件可以变得可用。不需要每次调用 API 时都重新扫描类路径，可以只在第一次调用时自动扫描。客户端可以调用此方法来启动重新扫描。因此，只有在运行时使新插件动态可用的复杂应用程序才需要调用此方法。

上下文 ClassLoader 的 getResources 方法被用来沿应用程序类路径查找包含名为 META-INF/services/javax.imageio.spi.classname 的文件的 JAR 文件，其中 classname 是 ImageReaderSpi、ImageWriterSpi、ImageTranscoderSpi、ImageInputStreamSpi 或 ImageOutputStreamSpi 之一。

所查找文件的内容表示实际实现类的名称，这些类实现上述服务提供者接口；然后可以使用默认类加载器加载每个类并实例化每个类的实例，然后将其放入注册表中供以后获取。

确切的搜索位置集合取决于 Java 运行时环境的实现。

另请参见：

ClassLoader.getResources(java.lang.String)

setUseCache

public static void setUseCache(boolean useCache)

设置一个标记，指示在创建 ImageInputStream 和 ImageOutputStream 时是否应该使用基于磁盘的缓存文件。

在从标准 InputStream 中读取数据时，有必要在缓存中保存以前读取的信息，因为底层流不允许重新读取数据。类似地，在将数据写入标准 OutputStream 时，可以使用某一缓存来允许以前写入的值在被刷新并转到最终目标前可以被更改。

该缓存可以驻留在主存或磁盘上。如果将此标记设置为 false，则不允许将磁盘用于将来的流，这在使用小图像时很有利，因为可以免除创建和销毁文件所带来的开销。

在启动时，该值被设置为 true。

参数：

useCache - 指示是否应使用缓存文件（在可选的情况下）的 boolean。

另请参见：

getUseCache()

getUseCache

public static boolean getUseCache()

返回由 setUseCache 设置的当前值；如果没有显式设置该值，则返回 true。

返回：

如果可以将基于磁盘的缓存用于 ImageInputStream 和 ImageOutputStream，则返回 true。

另请参见：

setUseCache(boolean)

setCacheDirectory

public static void setCacheDirectory(File cacheDirectory)

设置将在其中创建缓存文件的目录。值为 null 表示将使用与系统有关的默认临时文件目录。如果 getUseCache 返回 false，则忽略此值。

参数：

cacheDirectory - 指定目录的 File。

抛出：

SecurityException - 如果安全管理器拒绝对该目录的访问。

IllegalArgumentException - 如果 cacheDir 为非 null 但它不是一个目录。

另请参见：

File.createTempFile(String, String, File), getCacheDirectory()

getCacheDirectory

public static File getCacheDirectory()

返回由 setCacheDirectory 设置的当前值；如果没有显式设置该值，则返回 null。

返回：

一个 File，表示将在其中创建缓存文件的目录；null 指示与系统有关的默认临时文件目录。

另请参见：

setCacheDirectory(java.io.File)

createImageInputStream

public static ImageInputStream createImageInputStream(Object input)
                                               throws IOException

返回一个 ImageInputStream，它将从给定 Object 中获取输入。查询使用 IIORegistry 类注册的 ImageInputStreamSpi 集合，能够从所提供的对象中获取输入的第一个 ImageInputStreamSpi 将被用来创建返回的 ImageInputStream。如果没有合适的 ImageInputStreamSpi 存在，则返回 null。

getUseCache 和 getCacheDirectory 返回的当前缓存设置将被用来控制缓存。

参数：

input - 用作输入源的 Object，比如 File、可读取的 RandomAccessFile 或 InputStream。

返回：

一个 ImageInputStream 或 null。

抛出：

IllegalArgumentException - 如果 input 为 null。

IOException - 如果需要缓存文件但无法创建。

另请参见：

ImageInputStreamSpi

createImageOutputStream

public static ImageOutputStream createImageOutputStream(Object output)
                                                 throws IOException

返回一个 ImageOutputStream，它将其输出发送到给定 Object。查询使用 IIORegistry 类注册的 ImageOutputStreamSpi 集合，能够从所提供的对象发送输出的第一个 ImageOutputStreamSpi 将被用来创建返回的 ImageOutputStream。如果没有合适的 ImageOutputStreamSpi 存在，则返回 null。

getUseCache 和 getCacheDirectory 返回的当前缓存设置将被用来控制缓存。

参数：

output - 用作输出目标的 Object，比如 File、可写入的 RandomAccessFile 或 OutputStream。

返回：

一个 ImageOutputStream 或 null。

抛出：

IllegalArgumentException - 如果 output 为 null。

IOException - 如果需要缓存文件但无法创建。

另请参见：

ImageOutputStreamSpi

getReaderFormatNames

public static String[] getReaderFormatNames()

返回一个 String 数组，该数组列出被当前已注册 reader 集合所理解的所有非正式格式名称。

返回：

String 数组。

getReaderMIMETypes

public static String[] getReaderMIMETypes()

返回一个 String 数组，该数组列出被当前已注册 reader 集合所理解的所有 MIME 类型。

返回：

String 数组。

getReaderFileSuffixes

public static String[] getReaderFileSuffixes()

返回一个 String 数组，该数组列出与当前已注册 reader 集合所理解的格式关联的所有文件后缀。

返回：

String 数组。

从以下版本开始：

1.6

getImageReaders

public static Iterator<ImageReader> getImageReaders(Object input)

返回包含所有当前已注册 ImageReader 的 Iterator，这些 ImageReader 声称能够解码所提供的 Object（通常是一个 ImageInputStream）。

在从此方法退出时，该流的位置仍然是它以前的位置。

参数：

input - ImageInputStream 或包含解码图像数据的其他 Object。

返回：

包含 ImageReader 的 Iterator。

抛出：

IllegalArgumentException - 如果 input 为 null。

另请参见：

ImageReaderSpi.canDecodeInput(java.lang.Object)

getImageReadersByFormatName

public static Iterator<ImageReader> getImageReadersByFormatName(String formatName)

返回包含所有当前已注册 ImageReader 的 Iterator，这些 ImageReader 声称能够解码指定格式。

参数：

formatName - 包含非正式格式名称的 String（例如 "jpeg" 或 "tiff"）。

返回：

包含 ImageReader 的 Iterator。

抛出：

IllegalArgumentException - 如果 formatName 为 null。

另请参见：

ImageReaderWriterSpi.getFormatNames()

getImageReadersBySuffix

public static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix)

返回包含所有当前已注册 ImageReader 的 Iterator，这些 ImageReader 声称能够解码具有给定后缀的文件。

参数：

fileSuffix - 包含文件后缀的 String（例如 "jpg" 或 "tiff"）。

返回：

包含 ImageReader 的 Iterator。

抛出：

IllegalArgumentException - 如果 fileSuffix 为 null。

另请参见：

ImageReaderWriterSpi.getFileSuffixes()

getImageReadersByMIMEType

public static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType)

返回包含所有当前已注册 ImageReader 的 Iterator，这些 ImageReader 声称能够解码具有给定 MIME 类型的文件。

参数：

MIMEType - 包含文件后缀的 String（例如 "image/jpeg" 或 "image/x-bmp"）。

返回：

包含 ImageReader 的 Iterator。

抛出：

IllegalArgumentException - 如果 MIMEType 为 null。

另请参见：

ImageReaderWriterSpi.getMIMETypes()

getWriterFormatNames

public static String[] getWriterFormatNames()

返回一个 String 数组，该数组列出当前已注册 writer 集合所理解的所有非正式格式名称。

返回：

String 数组。

getWriterMIMETypes

public static String[] getWriterMIMETypes()

返回一个 String 数组，该数组列出当前已注册 writer 集合所理解的所有 MIME 类型。

返回：

String 数组。

getWriterFileSuffixes

public static String[] getWriterFileSuffixes()

返回一个 String 数组，该数组列出与当前已注册 writer 集合所理解的格式关联的所有文件后缀。

返回：

String 数组。

从以下版本开始：

1.6

getImageWritersByFormatName

public static Iterator<ImageWriter> getImageWritersByFormatName(String formatName)

返回包含所有当前已注册 ImageWriter 的 Iterator，这些 ImageReader 声称能够编码指定格式。

参数：

formatName - 包含非正式格式名称的 String（例如 "jpeg" 或 "tiff"）。

返回：

包含 ImageWriter 的 Iterator。

抛出：

IllegalArgumentException - 如果 formatName 为 null。

另请参见：

ImageReaderWriterSpi.getFormatNames()

getImageWritersBySuffix

public static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix)

返回包含所有当前已注册 ImageWriter 的 Iterator，这些 ImageReader 声称能够编码具有给定后缀的文件。

参数：

fileSuffix - 包含文件后缀的 String（例如 "jpg" 或 "tiff"）。

返回：

包含 ImageWriter 的 Iterator。

抛出：

IllegalArgumentException - 如果 fileSuffix 为 null。

另请参见：

ImageReaderWriterSpi.getFileSuffixes()

getImageWritersByMIMEType

public static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType)

返回包含所有当前已注册 ImageWriter 的 Iterator，这些 ImageReader 声称能够编码具有给定 MIME 类型的文件。

参数：

MIMEType - 包含文件后缀的 String（例如 "image/jpeg" 或 "image/x-bmp"）。

返回：

包含 ImageWriter 的 Iterator。

抛出：

IllegalArgumentException - 如果 MIMEType 为 null。

另请参见：

ImageReaderWriterSpi.getMIMETypes()

getImageWriter

public static ImageWriter getImageWriter(ImageReader reader)

返回对应于给定 ImageReader 的 ImageWriter（如果有）；如果此 ImageReader 的插件没有指定相应的 ImageWriter，或者给定的 ImageReader 没有注册，则返回 null。可以使用此机制获取一个 ImageWriter，它将理解由 ImageReader 生成的非像素元数据（由 IIOMetadata 对象编码）的内部结构。通过从 ImageReader 获取此数据并将其传给使用此方法获取的 ImageWriter，客户端程序可以读取图像，以某种方式修改图像，然后将其写回，并保留所有的元数据，而不需要理解有关元数据结构甚至图像格式的任何信息。注意，此方法返回“首选”writer，它是 javax.imageio.spi.ImageReaderSpi.getImageWriterSpiNames() 返回的列表中列出的第一个 writer。

参数：

reader - 已注册 ImageReader 的实例。

返回：

一个 ImageWriter 或 null。

抛出：

IllegalArgumentException - 如果 reader 为 null。

另请参见：

getImageReader(ImageWriter), ImageReaderSpi.getImageWriterSpiNames()

getImageReader

public static ImageReader getImageReader(ImageWriter writer)

返回对应于给定 ImageWriter 的 ImageReader（如果有）；如果此 ImageWriter 的插件没有指定相应的 ImageReader，或者给定 ImageWriter 没有注册，则返回 null。提供此方法主要是为了与 getImageWriter(ImageReader) 对称。注意，此方法返回“首选”reader，它是 javax.imageio.spi.ImageWriterSpi.getImageReaderSpiNames() 返回的列表中列出的第一个 reader。

参数：

writer - 已注册 ImageWriter 的实例。

返回：

一个 ImageReader 或 null。

抛出：

IllegalArgumentException - 如果 writer 为 null。

另请参见：

getImageWriter(ImageReader), ImageWriterSpi.getImageReaderSpiNames()

getImageWriters

public static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type,
                                                    String formatName)

返回包含所有当前已注册 ImageWriter 的 Iterator，这些 ImageWriter 声称能够编码使用给定格式的、具有给定布局（使用 ImageTypeSpecifier 指定）的图像。

参数：

type - 指示将写入的图像布局的 ImageTypeSpecifier。

formatName - format 的非正式名称。

返回：

包含 ImageWriter 的 Iterator。

抛出：

IllegalArgumentException - 如果任何参数为 null。

另请参见：

ImageWriterSpi.canEncodeImage(ImageTypeSpecifier)

getImageTranscoders

public static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader,
                                                            ImageWriter writer)

返回包含所有当前已注册 ImageTranscoder 的 Iterator，这些 ImageTranscoder 声称能够在给定 ImageReader 和 ImageWriter 的元数据之间进行代码转换。

参数：

reader - 一个 ImageReader。

writer - 一个 ImageWriter。

返回：

包含 ImageTranscoder 的 Iterator。

抛出：

IllegalArgumentException - 如果 reader 或 writer 为 null。

read

public static BufferedImage read(File input)
                          throws IOException

返回一个 BufferedImage，作为使用 ImageReader（它是从当前已注册 ImageReader 中自动选择的）解码所提供 File 的结果。该 File 被包装在一个 ImageInputStream 中。如果没有已注册的 ImageReader 声称能够读取得到的流，则返回 null。

使用 getUseCache 和 getCacheDirectory 返回的当前缓存设置控制所创建的 ImageInputStream 中的缓存。

注意，不存在将 String 形式的文件名作为参数的 read 方法；在根据文件名创建 File 之后使用此方法代替。

此方法不会试图查找可以直接从 File 中读取的 ImageReader；这可以使用 IIORegistry 和 ImageReaderSpi 来完成。

参数：

input - 将从中读取数据的 File。

返回：

包含解码的输入内容的 BufferedImage，或者返回 null。

抛出：

IllegalArgumentException - 如果 input 为 null。

IOException - 如果在读取过程中发生错误。

read

public static BufferedImage read(InputStream input)
                          throws IOException

返回一个 BufferedImage，作为使用 ImageReader（它是从当前已注册 ImageReader 中自动选择的）解码所提供 InputStream 的结果。该 InputStream 被包装在一个 ImageInputStream 中。如果没有已注册的 ImageReader 声称能够读取得到的流，则返回 null。

使用 getUseCache 和 getCacheDirectory 返回的当前缓存设置控制所创建的 ImageInputStream 中的缓存。

此方法不会试图查找可以直接从 InputStream 中读取的 ImageReader；这可以使用 IIORegistry 和 ImageReaderSpi 来完成。

此方法在读取操作完成后不会 关闭提供的 InputStream；如果需要，调用者负责关闭该流。

参数：

input - 将从中读取数据的 InputStream。

返回：

包含解码的输入内容的 BufferedImage，或者返回 null。

抛出：

IllegalArgumentException - 如果 input 为 null。

IOException - 如果在读取过程中发生错误。

read

public static BufferedImage read(URL input)
                          throws IOException

返回一个 BufferedImage，作为使用 ImageReader（它是从当前已注册 ImageReader 中自动选择的）解码所提供 URL 的结果。InputStream 是从 URL 中获得的，它被包装在 ImageInputStream 中。如果没有已注册的 ImageReader 声称能够读取得到的流，则返回 null。

使用 getUseCache 和 getCacheDirectory 返回的当前缓存设置控制所创建的 ImageInputStream 中的缓存。

此方法不会试图查找可以直接从 URL 中读取的 ImageReader；这可以使用 IIORegistry 和 ImageReaderSpi 来完成。

参数：

input - 将从中读取数据的 URL。

返回：

包含解码的输入内容的 BufferedImage，或者返回 null。

抛出：

IllegalArgumentException - 如果 input 为 null。

IOException - 如果在读取过程中发生错误。

read

public static BufferedImage read(ImageInputStream stream)
                          throws IOException

返回一个 BufferedImage，作为使用 ImageReader（它是从当前已注册 ImageReader 中自动选择的）解码所提供 ImageInputStream 的结果。如果没有已注册的 ImageReader 声称能够读取该流，则返回 null。

与此类中大多数其他方法不同，此方法在读取操作完成后会 关闭提供的 ImageInputStream，除非返回 null，在这种情况下，此方法不会 关闭该流。

参数：

stream - 将从中读取数据的 ImageInputStream。

返回：

包含解码的输入内容的 BufferedImage，或者返回 null。

抛出：

IllegalArgumentException - 如果 stream 为 null。

IOException - 如果在读取过程中发生错误。

write

public static boolean write(RenderedImage im,
                            String formatName,
                            ImageOutputStream output)
                     throws IOException

使用支持给定格式的任意 ImageWriter 将一个图像写入 ImageOutputStream。从当前流指针开始将图像写入 ImageOutputStream，并覆盖该点之后的现有流数据（如果有）。

此方法在写入操作完成后不会 关闭提供的 ImageOutputStream；如果需要，调用者负责关闭该流。

参数：

im - 要写入的 RenderedImage。

formatName - 包含格式非正式名称的 String。

output - 将在其中写入数据的 ImageOutputStream。

返回：

如果没有找到合适的 writer，则返回 false。

抛出：

IllegalArgumentException - 如果任何参数为 null。

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

write

public static boolean write(RenderedImage im,
                            String formatName,
                            File output)
                     throws IOException

使用支持给定格式的任意 ImageWriter 将一个图像写入 File。如果已经有一个 File 存在，则丢弃其内容。

参数：

im - 要写入的 RenderedImage。

formatName - 包含格式非正式名称的 String。

output - 将在其中写入数据的 File。

返回：

如果没有找到合适的 writer，则返回 false。

抛出：

IllegalArgumentException - 如果任何参数为 null。

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

write

public static boolean write(RenderedImage im,
                            String formatName,
                            OutputStream output)
                     throws IOException

使用支持给定格式的任意 ImageWriter 将一个图像写入 OutputStream。

此方法在写入操作完成后不会 关闭提供的 OutputStream；如果需要，调用者负责关闭该流。

getUseCache 和 getCacheDirectory 返回的当前缓存设置将被用来控制缓存。

参数：

im - 要写入的 RenderedImage。

formatName - 包含格式非正式名称的 String。

output - 将在其中写入数据的 OutputStream。

返回：

如果没有找到合适的 writer，则返回 false。

抛出：

IllegalArgumentException - 如果任何参数为 null。

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

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