javax.imageio

Class 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(ImageInputStream stream) Create a buffered image from an image input stream.
static BufferedImage	read(URL input) Create a buffered image from a URL.
static BufferedImage	read(InputStream input) Create a buffered image from an input stream.
static BufferedImage	read(File input) Create a buffered image from a file.
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, OutputStream output) Write an image to an output stream using a registered writer that supports the given format.
static boolean	write(RenderedImage im, String formatName, ImageOutputStream output) Write an image to an ImageOutputStream using a registered writer that supports the given format.

Method Detail

createImageInputStream

public static ImageInputStream createImageInputStream(Object input)

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)

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

getCacheDirectory

public static File getCacheDirectory()

Retrieve the current cache directory.

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

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

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

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

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

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

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

read

public static BufferedImage read(ImageInputStream stream)

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)

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)

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)

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

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)

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)

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)

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