javax.imageio
Class ImageIO

java.lang.Object
  extended by javax.imageio.ImageIO

public final class ImageIO
extends Object

An uninstantiable class that provides static methods for locating and using image readers and writers.


Method Summary
static ImageInputStream createImageInputStream(Object input)
          Create an image input stream from the given object.
static ImageOutputStream createImageOutputStream(Object output)
          Create an image output stream from the given object.
static File getCacheDirectory()
          Retrieve the current cache directory.
static ImageReader getImageReader(ImageWriter writer)
          Retrieve an image reader corresponding to an image writer, or null if writer is not registered or if no corresponding reader is registered.
static Iterator<ImageReader> getImageReaders(Object input)
          Retrieve an iterator over the collection of registered image readers that support reading data from the given object.
static Iterator<ImageReader> getImageReadersByFormatName(String formatName)
          Retrieve an iterator over all registered readers for the given format.
static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType)
          Retrieve an iterator over all registered readers for the given MIME type.
static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix)
          Retrieve an iterator over all registered readers for the given file suffix.
static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader, ImageWriter writer)
          Retrieve an iterator over a collection of image transcoders that support transcoding from the given image reader's metadata format to the given writer's metadata format.
static ImageWriter getImageWriter(ImageReader reader)
          Retrieve an image writer corresponding to an image reader, or null if reader is not registered or if no corresponding writer is registered.
static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type, String formatName)
          Retrieve an iterator over the collection of registered image writers that support writing images of the given type and in the given format.
static Iterator<ImageWriter> getImageWritersByFormatName(String formatName)
          Retrieve an iterator over all registered writers for the given format.
static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType)
          Retrieve an iterator over all registered writers for the given MIME type.
static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix)
          Retrieve an iterator over all registered writers for the given file suffix.
static String[] getReaderFormatNames()
          Retrieve all the informal format names supported by the collection of registered image readers.
static String[] getReaderMIMETypes()
          Retrieve all the MIME types supported by the collection of registered image readers.
static boolean getUseCache()
          Check whether or not an on-disk cache is used for image input and output streams.
static String[] getWriterFormatNames()
          Retrieve all the informal format names supported by the collection of registered image writers.
static String[] getWriterMIMETypes()
          Retrieve all the MIME types supported by the collection of registered image writers.
static BufferedImage read(File input)
          Create a buffered image from a file.
static BufferedImage read(ImageInputStream stream)
          Create a buffered image from an image input stream.
static BufferedImage read(InputStream input)
          Create a buffered image from an input stream.
static BufferedImage read(URL input)
          Create a buffered image from a URL.
static void scanForPlugins()
          Rescans the application classpath for ImageIO service providers and registers them.
static void setCacheDirectory(File cacheDirectory)
          Set the directory to be used for caching image data.
static void setUseCache(boolean useCache)
          Control whether or not an on-disk cache is used.
static boolean write(RenderedImage im, String formatName, File output)
          Write an image to a file using a registered writer that supports the given format, overwriting the file if it already exists.
static boolean write(RenderedImage im, String formatName, ImageOutputStream output)
          Write an image to an ImageOutputStream using a registered writer that supports the given format.
static boolean write(RenderedImage im, String formatName, OutputStream output)
          Write an image to an output stream using a registered writer that supports the given format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getCacheDirectory

public static File getCacheDirectory()
Retrieve the current cache directory.

Returns:
the current cache directory or null if none is set.

getImageReadersByFormatName

public static Iterator<ImageReader> getImageReadersByFormatName(String formatName)
Retrieve an iterator over all registered readers for the given format.

Parameters:
formatName - an infomal format name (e.g. "jpeg" or "bmp")
Returns:
an iterator over a collection of image readers
Throws:
IllegalArgumentException - if formatName is null

getImageReadersByMIMEType

public static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType)
Retrieve an iterator over all registered readers for the given MIME type.

Parameters:
MIMEType - a MIME specification for an image type (e.g. "image/jpeg" or "image/x-bmp")
Returns:
an iterator over a collection of image readers
Throws:
IllegalArgumentException - if MIMEType is null

getImageReadersBySuffix

public static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix)
Retrieve an iterator over all registered readers for the given file suffix.

Parameters:
fileSuffix - an image file suffix (e.g. "jpg" or "bmp")
Returns:
an iterator over a collection of image readers
Throws:
IllegalArgumentException - if fileSuffix is null

getImageWritersByFormatName

public static Iterator<ImageWriter> getImageWritersByFormatName(String formatName)
Retrieve an iterator over all registered writers for the given format.

Parameters:
formatName - an infomal format name (e.g. "jpeg" or "bmp")
Returns:
an iterator over a collection of image writers
Throws:
IllegalArgumentException - if formatName is null

getImageWritersByMIMEType

public static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType)
Retrieve an iterator over all registered writers for the given MIME type.

Parameters:
MIMEType - a MIME specification for an image type (e.g. "image/jpeg" or "image/x-bmp")
Returns:
an iterator over a collection of image writers
Throws:
IllegalArgumentException - if MIMEType is null

getImageWritersBySuffix

public static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix)
Retrieve an iterator over all registered writers for the given file suffix.

Parameters:
fileSuffix - an image file suffix (e.g. "jpg" or "bmp")
Returns:
an iterator over a collection of image writers
Throws:
IllegalArgumentException - if fileSuffix is null

getReaderFormatNames

public static String[] getReaderFormatNames()
Retrieve all the informal format names supported by the collection of registered image readers.

Returns:
an array of format names

getReaderMIMETypes

public static String[] getReaderMIMETypes()
Retrieve all the MIME types supported by the collection of registered image readers.

Returns:
an array of MIME types

getUseCache

public static boolean getUseCache()
Check whether or not an on-disk cache is used for image input and output streams.

Returns:
true if an on-disk cache is available, false otherwise

getWriterFormatNames

public static String[] getWriterFormatNames()
Retrieve all the informal format names supported by the collection of registered image writers.

Returns:
an array of format names

getWriterMIMETypes

public static String[] getWriterMIMETypes()
Retrieve all the MIME types supported by the collection of registered image writers.

Returns:
an array of MIME types

scanForPlugins

public static void scanForPlugins()
Rescans the application classpath for ImageIO service providers and registers them.


setCacheDirectory

public static void setCacheDirectory(File cacheDirectory)
Set the directory to be used for caching image data. A null argument means to use the default system temporary directory. This cache directory is only used if getUseCache returns true.

Parameters:
cacheDirectory - the directory where image data should be cached
Throws:
IllegalArgumentException - if cacheDirectory is not a directory

setUseCache

public static void setUseCache(boolean useCache)
Control whether or not an on-disk cache is used. This cache is used to store input or output data from an image data stream when data in the stream needs to be re-processed. If useCache is false the cache will be stored in memory. Doing so eliminates file creation and deletion overhead. The default is to use an on-disk cache.

Parameters:
useCache - true to use an on-disk cache, false otherwise

write

public static boolean write(RenderedImage im,
                            String formatName,
                            File output)
                     throws IOException
Write an image to a file using a registered writer that supports the given format, overwriting the file if it already exists.

Parameters:
im - the image data to write
formatName - an informal description of the output format
output - the file to which the image will be written
Returns:
false if no registered writer supports the given format, true otherwise
Throws:
IllegalArgumentException - if any argument is null
IOException - if a writing error occurs

write

public static boolean write(RenderedImage im,
                            String formatName,
                            OutputStream output)
                     throws IOException
Write an image to an output stream using a registered writer that supports the given format.

Parameters:
im - the image data to write
formatName - an informal description of the output format
output - the output stream to which the image will be written
Returns:
false if no registered writer supports the given format, true otherwise
Throws:
IllegalArgumentException - if any argument is null
IOException - if a writing error occurs

write

public static boolean write(RenderedImage im,
                            String formatName,
                            ImageOutputStream output)
                     throws IOException
Write an image to an ImageOutputStream using a registered writer that supports the given format. Image data is written starting at the ImageOutputStream's current stream pointer, overwriting any existing data.

Parameters:
im - the image data to write
formatName - an informal description of the output format
output - the image output stream to which the image will be written
Returns:
false if no registered writer supports the given format, true otherwise
Throws:
IllegalArgumentException - if any argument is null
IOException - if a writing error occurs

read

public static BufferedImage read(ImageInputStream stream)
                          throws IOException
Create a buffered image from an image input stream. An image reader that supports the given image data is automatically selected from the collection of registered readers. If no registered reader can handle the input format, null is returned.

Parameters:
stream - the image input stream from which to read image data
Returns:
a new buffered image created from the given image data, or null
Throws:
IllegalArgumentException - if stream is null
IOException - if a reading error occurs

read

public static BufferedImage read(URL input)
                          throws IOException
Create a buffered image from a URL. An image reader that supports the given image data is automatically selected from the collection of registered readers. If no registered reader can handle the input format, null is returned. The image data will be cached in the current cache directory if caching is enabled. This method does not locate readers that read data directly from a URL. To locate such readers manually, use IIORegistry and ImageReaderSpi.

Parameters:
input - the URL from which to retrieve the image file
Returns:
a new buffered image created from the given image URL, or null
Throws:
IllegalArgumentException - if input is null
IOException - if a reading error occurs

read

public static BufferedImage read(InputStream input)
                          throws IOException
Create a buffered image from an input stream. An image reader that supports the given image data is automatically selected from the collection of registered readers. If no registered reader can handle the input format, null is returned. The image data will be cached in the current cache directory if caching is enabled. This method does not locate readers that read data directly from an input stream. To locate such readers manually, use IIORegistry and ImageReaderSpi.

Parameters:
input - the input stream from which to read the image data
Returns:
a new buffered image created from the given input stream, or null
Throws:
IllegalArgumentException - if input is null
IOException - if a reading error occurs

read

public static BufferedImage read(File input)
                          throws IOException
Create a buffered image from a file. An image reader that supports the given image data is automatically selected from the collection of registered readers. If no registered reader can handle the input format, null is returned. The image data will be cached in the current cache directory if caching is enabled. This method does not locate readers that read data directly from a file. To locate such readers manually, use IIORegistry and ImageReaderSpi.

Parameters:
input - the file from which to read image data
Returns:
a new buffered image created from the given image file, or null
Throws:
IllegalArgumentException - if input is null
IOException - if a reading error occurs

createImageInputStream

public static ImageInputStream createImageInputStream(Object input)
                                               throws IOException
Create an image input stream from the given object. The collection of ImageInputStreamSpis registered with the IIORegistry is searched for an image input stream that can take input from the given object. null is returned if no such SPI is registered. The image data will be cached in the current cache directory if caching is enabled.

Parameters:
input - an object from which to read image data
Returns:
an ImageInputStream that can read data from input, or null
Throws:
IllegalArgumentException - if input is null
IOException - if caching is required but not enabled

createImageOutputStream

public static ImageOutputStream createImageOutputStream(Object output)
                                                 throws IOException
Create an image output stream from the given object. The collection of ImageOutputStreamSpis registered with the IIORegistry is searched for an image output stream that can send output to the given object. null is returned if no such SPI is registered. The image data will be cached in the current cache directory if caching is enabled.

Parameters:
output - an object to which to write image data
Returns:
an ImageOutputStream that can send data to output, or null
Throws:
IllegalArgumentException - if output is null
IOException - if caching is required but not enabled

getImageReader

public static ImageReader getImageReader(ImageWriter writer)
Retrieve an image reader corresponding to an image writer, or null if writer is not registered or if no corresponding reader is registered.

Parameters:
writer - a registered image writer
Returns:
an image reader corresponding to writer, or null
Throws:
IllegalArgumentException - if writer is null

getImageReaders

public static Iterator<ImageReader> getImageReaders(Object input)
Retrieve an iterator over the collection of registered image readers that support reading data from the given object.

Parameters:
input - the object for which to retrieve image readers
Returns:
an iterator over a collection of image readers

getImageWriters

public static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type,
                                                    String formatName)
Retrieve an iterator over the collection of registered image writers that support writing images of the given type and in the given format.

Parameters:
type - the output image's colour and sample models
formatName - the output image format
Returns:
an iterator over a collection of image writers

getImageWriter

public static ImageWriter getImageWriter(ImageReader reader)
Retrieve an image writer corresponding to an image reader, or null if reader is not registered or if no corresponding writer is registered. This method is useful for preserving metadata without needing to understand its format, since the returned writer will be able to write, unchanged, the metadata passed to it by the reader.

Parameters:
reader - a registered image reader
Returns:
an image writer corresponding to reader, or null
Throws:
IllegalArgumentException - if reader is null

getImageTranscoders

public static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader,
                                                            ImageWriter writer)
Retrieve an iterator over a collection of image transcoders that support transcoding from the given image reader's metadata format to the given writer's metadata format.

Parameters:
reader - an image reader
writer - an image writer
Returns:
an iterator over a collection of image transcoders
Throws:
IllegalArgumentException - if either reader or writer is null