javax.imageio

Class ImageIO

java.lang.Object

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

Methods

Modifier and Type	Method and Description
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