JavaTM Platform
Standard Ed. 6

javax.imageio
类 ImageIO

java.lang.Object
  继承者 javax.imageio.ImageIO

public final class ImageIO
     
extends Object

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


方法摘要
static ImageInputStream createImageInputStream(Object input)
          返回一个 ImageInputStream,它将从给定 Object 中获取输入。
static ImageOutputStream createImageOutputStream(Object output)
          返回一个 ImageOutputStream,它将其输出发送到给定 Object
static File getCacheDirectory()
          返回由 setCacheDirectory 设置的当前值;如果没有显式设置该值,则返回 null
static ImageReader getImageReader(ImageWriter writer)
          返回对应于给定 ImageWriterImageReader(如果有);如果此 ImageWriter 的插件没有指定相应的 ImageReader,或者给定 ImageWriter 没有注册,则返回 null
static Iterator<ImageReader> getImageReaders(Object input)
          返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码所提供的 Object(通常是一个 ImageInputStream)。
static Iterator<ImageReader> getImageReadersByFormatName(String formatName)
          返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码指定格式。
static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType)
          返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码具有给定 MIME 类型的文件。
static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix)
          返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码具有给定后缀的文件。
static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader, ImageWriter writer)
          返回包含所有当前已注册 ImageTranscoderIterator,这些 ImageTranscoder 声称能够在给定 ImageReaderImageWriter 的元数据之间进行代码转换。
static ImageWriter getImageWriter(ImageReader reader)
          返回对应于给定 ImageReaderImageWriter(如果有);如果此 ImageReader 的插件没有指定相应的 ImageWriter,或者给定的 ImageReader 没有注册,则返回 null
static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type, String formatName)
          返回包含所有当前已注册 ImageWriterIterator,这些 ImageWriter 声称能够编码使用给定格式的、具有给定布局(使用 ImageTypeSpecifier 指定)的图像。
static Iterator<ImageWriter> getImageWritersByFormatName(String formatName)
          返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码指定格式。
static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType)
          返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码具有给定 MIME 类型的文件。
static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix)
          返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码具有给定后缀的文件。
static String[] getReaderFileSuffixes()
          返回一个 String 数组,该数组列出与当前已注册 reader 集合所理解的格式关联的所有文件后缀。
static String[] getReaderFormatNames()
          返回一个 String 数组,该数组列出被当前已注册 reader 集合所理解的所有非正式格式名称。
static String[] getReaderMIMETypes()
          返回一个 String 数组,该数组列出被当前已注册 reader 集合所理解的所有 MIME 类型。
static boolean getUseCache()
          返回由 setUseCache 设置的当前值;如果没有显式设置该值,则返回 true
static String[] getWriterFileSuffixes()
          返回一个 String 数组,该数组列出与当前已注册 writer 集合所理解的格式关联的所有文件后缀。
static String[] getWriterFormatNames()
          返回一个 String 数组,该数组列出当前已注册 writer 集合所理解的所有非正式格式名称。
static String[] getWriterMIMETypes()
          返回一个 String 数组,该数组列出当前已注册 writer 集合所理解的所有 MIME 类型。
static BufferedImage read(File input)
          返回一个 BufferedImage,作为使用 ImageReader(它是从当前已注册 ImageReader 中自动选择的)解码所提供 File 的结果。
static BufferedImage read(ImageInputStream stream)
          返回一个 BufferedImage,作为使用 ImageReader(它是从当前已注册 ImageReader 中自动选择的)解码所提供 ImageInputStream 的结果。
static BufferedImage read(InputStream input)
          返回一个 BufferedImage,作为使用 ImageReader(它是从当前已注册 ImageReader 中自动选择的)解码所提供 InputStream 的结果。
static BufferedImage read(URL input)
          返回一个 BufferedImage,作为使用 ImageReader(它是从当前已注册 ImageReader 中自动选择的)解码所提供 URL 的结果。
static void scanForPlugins()
          扫描应用程序类路径上的插件,加载其服务提供者类,并使用 IIORegistry 为每一个找到的插件注册一个服务提供者实例。
static void setCacheDirectory(File cacheDirectory)
          设置将在其中创建缓存文件的目录。
static void setUseCache(boolean useCache)
          设置一个标记,指示在创建 ImageInputStreamImageOutputStream 时是否应该使用基于磁盘的缓存文件。
static boolean write(RenderedImage im, String formatName, File output)
          使用支持给定格式的任意 ImageWriter 将一个图像写入 File
static boolean write(RenderedImage im, String formatName, ImageOutputStream output)
          使用支持给定格式的任意 ImageWriter 将一个图像写入 ImageOutputStream
static boolean write(RenderedImage im, String formatName, OutputStream output)
          使用支持给定格式的任意 ImageWriter 将一个图像写入 OutputStream
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

方法详细信息

scanForPlugins

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

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

上下文 ClassLoadergetResources 方法被用来沿应用程序类路径查找包含名为 META-INF/services/javax.imageio.spi.classname 的文件的 JAR 文件,其中 classnameImageReaderSpiImageWriterSpiImageTranscoderSpiImageInputStreamSpiImageOutputStreamSpi 之一。

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

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

另请参见:
ClassLoader.getResources(java.lang.String)

setUseCache

public static void setUseCache(boolean useCache)
设置一个标记,指示在创建 ImageInputStreamImageOutputStream 时是否应该使用基于磁盘的缓存文件。

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

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

在启动时,该值被设置为 true

参数:
useCache - 指示是否应使用缓存文件(在可选的情况下)的 boolean
另请参见:
getUseCache()

getUseCache

public static boolean getUseCache()
返回由 setUseCache 设置的当前值;如果没有显式设置该值,则返回 true

返回:
如果可以将基于磁盘的缓存用于 ImageInputStreamImageOutputStream,则返回 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

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

参数:
input - 用作输入源的 Object,比如 File、可读取的 RandomAccessFileInputStream
返回:
一个 ImageInputStreamnull
抛出:
IllegalArgumentException - 如果 inputnull
IOException - 如果需要缓存文件但无法创建。
另请参见:
ImageInputStreamSpi

createImageOutputStream

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

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

参数:
output - 用作输出目标的 Object,比如 File、可写入的 RandomAccessFileOutputStream
返回:
一个 ImageOutputStreamnull
抛出:
IllegalArgumentException - 如果 outputnull
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)
返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码所提供的 Object(通常是一个 ImageInputStream)。

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

参数:
input - ImageInputStream 或包含解码图像数据的其他 Object
返回:
包含 ImageReaderIterator
抛出:
IllegalArgumentException - 如果 inputnull
另请参见:
ImageReaderSpi.canDecodeInput(java.lang.Object)

getImageReadersByFormatName

public static Iterator<ImageReader> getImageReadersByFormatName(String formatName)
返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码指定格式。

参数:
formatName - 包含非正式格式名称的 String例如 "jpeg" 或 "tiff")。
返回:
包含 ImageReaderIterator
抛出:
IllegalArgumentException - 如果 formatNamenull
另请参见:
ImageReaderWriterSpi.getFormatNames()

getImageReadersBySuffix

public static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix)
返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码具有给定后缀的文件。

参数:
fileSuffix - 包含文件后缀的 String例如 "jpg" 或 "tiff")。
返回:
包含 ImageReaderIterator
抛出:
IllegalArgumentException - 如果 fileSuffixnull
另请参见:
ImageReaderWriterSpi.getFileSuffixes()

getImageReadersByMIMEType

public static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType)
返回包含所有当前已注册 ImageReaderIterator,这些 ImageReader 声称能够解码具有给定 MIME 类型的文件。

参数:
MIMEType - 包含文件后缀的 String例如 "image/jpeg" 或 "image/x-bmp")。
返回:
包含 ImageReaderIterator
抛出:
IllegalArgumentException - 如果 MIMETypenull
另请参见:
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)
返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码指定格式。

参数:
formatName - 包含非正式格式名称的 String例如 "jpeg" 或 "tiff")。
返回:
包含 ImageWriterIterator
抛出:
IllegalArgumentException - 如果 formatNamenull
另请参见:
ImageReaderWriterSpi.getFormatNames()

getImageWritersBySuffix

public static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix)
返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码具有给定后缀的文件。

参数:
fileSuffix - 包含文件后缀的 String例如 "jpg" 或 "tiff")。
返回:
包含 ImageWriterIterator
抛出:
IllegalArgumentException - 如果 fileSuffixnull
另请参见:
ImageReaderWriterSpi.getFileSuffixes()

getImageWritersByMIMEType

public static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType)
返回包含所有当前已注册 ImageWriterIterator,这些 ImageReader 声称能够编码具有给定 MIME 类型的文件。

参数:
MIMEType - 包含文件后缀的 String例如 "image/jpeg" 或 "image/x-bmp")。
返回:
包含 ImageWriterIterator
抛出:
IllegalArgumentException - 如果 MIMETypenull
另请参见:
ImageReaderWriterSpi.getMIMETypes()

getImageWriter

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

参数:
reader - 已注册 ImageReader 的实例。
返回:
一个 ImageWriter 或 null。
抛出:
IllegalArgumentException - 如果 readernull
另请参见:
getImageReader(ImageWriter), ImageReaderSpi.getImageWriterSpiNames()

getImageReader

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

参数:
writer - 已注册 ImageWriter 的实例。
返回:
一个 ImageReader 或 null。
抛出:
IllegalArgumentException - 如果 writernull
另请参见:
getImageWriter(ImageReader), ImageWriterSpi.getImageReaderSpiNames()

getImageWriters

public static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type,
                                                    String formatName)
返回包含所有当前已注册 ImageWriterIterator,这些 ImageWriter 声称能够编码使用给定格式的、具有给定布局(使用 ImageTypeSpecifier 指定)的图像。

参数:
type - 指示将写入的图像布局的 ImageTypeSpecifier
formatName - format 的非正式名称。
返回:
包含 ImageWriterIterator
抛出:
IllegalArgumentException - 如果任何参数为 null
另请参见:
ImageWriterSpi.canEncodeImage(ImageTypeSpecifier)

getImageTranscoders

public static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader,
                                                            ImageWriter writer)
返回包含所有当前已注册 ImageTranscoderIterator,这些 ImageTranscoder 声称能够在给定 ImageReaderImageWriter 的元数据之间进行代码转换。

参数:
reader - 一个 ImageReader
writer - 一个 ImageWriter
返回:
包含 ImageTranscoderIterator
抛出:
IllegalArgumentException - 如果 readerwriternull

read

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

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

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

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

参数:
input - 将从中读取数据的 File
返回:
包含解码的输入内容的 BufferedImage,或者返回 null
抛出:
IllegalArgumentException - 如果 inputnull
IOException - 如果在读取过程中发生错误。

read

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

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

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

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

参数:
input - 将从中读取数据的 InputStream
返回:
包含解码的输入内容的 BufferedImage,或者返回 null
抛出:
IllegalArgumentException - 如果 inputnull
IOException - 如果在读取过程中发生错误。

read

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

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

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

参数:
input - 将从中读取数据的 URL
返回:
包含解码的输入内容的 BufferedImage,或者返回 null
抛出:
IllegalArgumentException - 如果 inputnull
IOException - 如果在读取过程中发生错误。

read

public static BufferedImage read(ImageInputStream stream)
                          throws IOException
返回一个 BufferedImage,作为使用 ImageReader(它是从当前已注册 ImageReader 中自动选择的)解码所提供 ImageInputStream 的结果。如果没有已注册的 ImageReader 声称能够读取该流,则返回 null

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

参数:
stream - 将从中读取数据的 ImageInputStream
返回:
包含解码的输入内容的 BufferedImage,或者返回 null
抛出:
IllegalArgumentException - 如果 streamnull
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;如果需要,调用者负责关闭该流。

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

参数:
im - 要写入的 RenderedImage
formatName - 包含格式非正式名称的 String
output - 将在其中写入数据的 OutputStream
返回:
如果没有找到合适的 writer,则返回 false
抛出:
IllegalArgumentException - 如果任何参数为 null
IOException - 如果在写入过程中发生错误。

JavaTM Platform
Standard Ed. 6

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

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