Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

javax.imageio
Class ImageIO

java.lang.Object
  javax.imageio.ImageIO

public final class ImageIO

extends java.lang.Object

A class containing static convenience methods for locating ImageReaders and ImageWriters, and performing simple encoding and decoding.

Note:

JSR-209 does not include the javax.imageio.spi package in this release. Compliant implementations of JSR-209 will need to implement ImageReaders and ImageWriters for the supported formats such that they are available to applications either through the ImageIO class or the creation of ImageInputStream or ImageOutputStream.

Method Summary

static ImageInputStream	createImageInputStream(java.lang.Object input) Returns an ImageInputStream that will take its input from the given Object.
static ImageOutputStream	createImageOutputStream(java.lang.Object output) Returns an ImageOutputStream that will send its output to the given Object.
static java.io.File	getCacheDirectory() Returns the current value set by setCacheDirectory, or null if no explicit setting has been made.
static ImageReader	getImageReader(ImageWriter writer) Returns an ImageReadercorresponding to the given ImageWriter, if there is one, or null.
static java.util.Iterator	getImageReaders(java.lang.Object input) Returns an Iterator containing all ImageReaders that claim to be able to decode the supplied Object, typically an ImageInputStream.
static java.util.Iterator	getImageReadersByFormatName(java.lang.String formatName) Returns an Iterator containing all ImageReaders that claim to be able to decode the named format.
static java.util.Iterator	getImageReadersByMIMEType(java.lang.String MIMEType) Returns an Iterator containing all ImageReaders that claim to be able to decode files with the given MIME type.
static java.util.Iterator	getImageReadersBySuffix(java.lang.String fileSuffix) Returns an Iterator containing all ImageReaders that claim to be able to decode files with the given suffix.
static ImageWriter	getImageWriter(ImageReader reader) Returns an ImageWritercorresponding to the given ImageReader, if there is one, or null.
static java.util.Iterator	getImageWriters(ImageTypeSpecifier type, java.lang.String formatName) Returns an Iterator containing all ImageWriters that claim to be able to encode images of the given layout (specified using an ImageTypeSpecifier) in the given format.
static java.util.Iterator	getImageWritersByFormatName(java.lang.String formatName) Returns an Iterator containing all ImageWriters that claim to be able to encode the named format.
static java.util.Iterator	getImageWritersByMIMEType(java.lang.String MIMEType) Returns an Iterator containing all ImageWriters that claim to be able to encode files with the given MIME type.
static java.util.Iterator	getImageWritersBySuffix(java.lang.String fileSuffix) Returns an Iterator containing all ImageWriters that claim to be able to encode files with the given suffix.
static java.lang.String[]	getReaderFormatNames() Returns an array of Strings listing all of the informal format names
static java.lang.String[]	getReaderMIMETypes() Returns an array of Strings listing all of the MIME types.
static boolean	getUseCache() Returns the current value set by setUseCache, or true if no explicit setting has been made.
static java.lang.String[]	getWriterFormatNames() Returns an array of Strings listing all of the informal format names understood by the current set of writers.
static java.lang.String[]	getWriterMIMETypes() Returns an array of Strings listing all of the MIME types understood by the current set of writers.
static BufferedImage	read(java.io.File input) Returns a BufferedImage as the result of decoding a supplied File with an ImageReader The File is wrapped in an ImageInputStream.
static BufferedImage	read(ImageInputStream stream) Returns a BufferedImage as the result of decoding a supplied ImageInputStream with an ImageReader.
static BufferedImage	read(java.io.InputStream input) Returns a BufferedImage as the result of decoding a supplied InputStream with an ImageReader.
static BufferedImage	read(java.net.URL input) Returns a BufferedImage as the result of decoding a supplied URL with an ImageReader An InputStream is obtained from the URL, which is wrapped in an ImageInputStream.
static void	setCacheDirectory(java.io.File cacheDirectory) Sets the directory where cache files are to be created.
static void	setUseCache(boolean useCache) Sets a flag indicating whether a disk-based cache file should be used when creating ImageInputStreams and ImageOutputStreams.
static boolean	write(RenderedImage im, java.lang.String formatName, java.io.File output) Writes an image using an arbitrary ImageWriter that supports the given format to a File.
static boolean	write(RenderedImage im, java.lang.String formatName, ImageOutputStream output) Writes an image using the an arbitrary ImageWriter that supports the given format to an ImageOutputStream.
static boolean	write(RenderedImage im, java.lang.String formatName, java.io.OutputStream output) Writes an image using an arbitrary ImageWriter that supports the given format to an OutputStream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setUseCache

public static void setUseCache(boolean useCache)

Sets a flag indicating whether a disk-based cache file should be used when creating ImageInputStreams and ImageOutputStreams.

When reading from a standard InputStream, it may be necessary to save previously read information in a cache since the underlying stream does not allow data to be re-read. Similarly, when writing to a standard OutputStream, a cache may be used to allow a previously written value to be changed before flushing it to the final destination.

The cache may reside in main memory or on disk. Setting this flag to false disallows the use of disk for future streams, which may be advantageous when working with small images, as the overhead of creating and destroying files is removed.

On startup, the value is set to true.

Parameters:

useCache - a boolean indicating whether a cache file should be used, in cases where it is optional.

See Also:

getUseCache()

getUseCache

public static boolean getUseCache()

Returns the current value set by setUseCache, or true if no explicit setting has been made.

Returns:

true if a disk-based cache may be used for ImageInputStreams and ImageOutputStreams.

See Also:

setUseCache(boolean)

setCacheDirectory

public static void setCacheDirectory(java.io.File cacheDirectory)

Sets the directory where cache files are to be created. A value of null indicates that the system-dependent default temporary-file directory is to be used. If getUseCache returns false, this value is ignored.

Parameters:

cacheDirectory - a File specifying a directory.

Throws:

java.lang.SecurityException - if the security manager denies access to the directory.

java.lang.IllegalArgumentException - if cacheDir is non-null but is not a directory.

See Also:

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

getCacheDirectory

public static java.io.File getCacheDirectory()

Returns the current value set by setCacheDirectory, or null if no explicit setting has been made.

Returns:

a File indicating the directory where cache files will be created, or null to indicate the system-dependent default temporary-file directory.

See Also:

setCacheDirectory(java.io.File)

createImageInputStream

public static ImageInputStream createImageInputStream(java.lang.Object input)
                                               throws java.io.IOException

Returns an ImageInputStream that will take its input from the given Object.

The current cache settings from getUseCache and getCacheDirectory will be used to control caching.

Parameters:

input - an Object to be used as an input source, such as a File, readable RandomAccessFile, or InputStream.

Returns:

an ImageInputStream, or null.

Throws:

java.lang.IllegalArgumentException - if input is null.

java.io.IOException - if a cache file is needed but cannot be created.

createImageOutputStream

public static ImageOutputStream createImageOutputStream(java.lang.Object output)
                                                 throws java.io.IOException

Returns an ImageOutputStream that will send its output to the given Object.

The current cache settings from getUseCache and getCacheDirectory will be used to control caching.

Parameters:

output - an Object to be used as an output destination, such as a File, writable RandomAccessFile, or OutputStream.

Returns:

an ImageOutputStream, or null.

Throws:

java.lang.IllegalArgumentException - if output is null.

java.io.IOException - if a cache file is needed but cannot be created.

getReaderFormatNames

public static java.lang.String[] getReaderFormatNames()

Returns an array of Strings listing all of the informal format names

Returns:

an array of Strings.

getReaderMIMETypes

public static java.lang.String[] getReaderMIMETypes()

Returns an array of Strings listing all of the MIME types.

Returns:

an array of Strings.

getImageReaders

public static java.util.Iterator getImageReaders(java.lang.Object input)

Returns an Iterator containing all ImageReaders that claim to be able to decode the supplied Object, typically an ImageInputStream.

The stream position is left at its prior position upon exit from this method.

Parameters:

input - an ImageInputStream or other Object containing encoded image data.

Returns:

an Iterator containing ImageReaders.

Throws:

java.lang.IllegalArgumentException - if input is null.

getImageReadersByFormatName

public static java.util.Iterator getImageReadersByFormatName(java.lang.String formatName)

Returns an Iterator containing all ImageReaders that claim to be able to decode the named format.

Parameters:

formatName - a String containing the informal name of a format (e.g., "jpeg" or "tiff".

Returns:

an Iterator containing ImageReaders.

Throws:

java.lang.IllegalArgumentException - if formatName is null.

getImageReadersBySuffix

public static java.util.Iterator getImageReadersBySuffix(java.lang.String fileSuffix)

Returns an Iterator containing all ImageReaders that claim to be able to decode files with the given suffix.

Parameters:

fileSuffix - a String containing a file suffix (e.g., "jpg" or "tiff").

Returns:

an Iterator containing ImageReaders.

Throws:

java.lang.IllegalArgumentException - if fileSuffix is null.

getImageReadersByMIMEType

public static java.util.Iterator getImageReadersByMIMEType(java.lang.String MIMEType)

Returns an Iterator containing all ImageReaders that claim to be able to decode files with the given MIME type.

Parameters:

MIMEType - a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").

Returns:

an Iterator containing ImageReaders.

Throws:

java.lang.IllegalArgumentException - if MIMEType is null.

getWriterFormatNames

public static java.lang.String[] getWriterFormatNames()

Returns an array of Strings listing all of the informal format names understood by the current set of writers.

Returns:

an array of Strings.

getWriterMIMETypes

public static java.lang.String[] getWriterMIMETypes()

Returns an array of Strings listing all of the MIME types understood by the current set of writers.

Returns:

an array of Strings.

getImageWritersByFormatName

public static java.util.Iterator getImageWritersByFormatName(java.lang.String formatName)

Returns an Iterator containing all ImageWriters that claim to be able to encode the named format.

Parameters:

formatName - a String containing the informal name of a format (e.g., "jpeg" or "tiff".

Returns:

an Iterator containing ImageWriters.

Throws:

java.lang.IllegalArgumentException - if formatName is null.

getImageWritersBySuffix

public static java.util.Iterator getImageWritersBySuffix(java.lang.String fileSuffix)

Returns an Iterator containing all ImageWriters that claim to be able to encode files with the given suffix.

Parameters:

fileSuffix - a String containing a file suffix (e.g., "jpg" or "tiff").

Returns:

an Iterator containing ImageWriters.

Throws:

java.lang.IllegalArgumentException - if fileSuffix is null.

getImageWritersByMIMEType

public static java.util.Iterator getImageWritersByMIMEType(java.lang.String MIMEType)

Returns an Iterator containing all ImageWriters that claim to be able to encode files with the given MIME type.

Parameters:

MIMEType - a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").

Returns:

an Iterator containing ImageWriters.

Throws:

java.lang.IllegalArgumentException - if MIMEType is null.

getImageWriter

public static ImageWriter getImageWriter(ImageReader reader)

Returns an ImageWritercorresponding to the given ImageReader, if there is one, or null. By obtaining this data from the ImageReader and passing it on to the ImageWriter obtained with this method, a client program can read an image, modify it in some way, and write it back out, without having to understand anything about the image format.

Parameters:

reader - an instance of an ImageReader.

Returns:

an ImageWriter, or null.

Throws:

java.lang.IllegalArgumentException - if reader is null.

See Also:

getImageReader(ImageWriter)

getImageReader

public static ImageReader getImageReader(ImageWriter writer)

Returns an ImageReadercorresponding to the given ImageWriter, if there is one, or null. This method is provided principally for symmetry with getImageWriter(ImageReader).

Parameters:

writer - an instance of an ImageWriter.

Returns:

an ImageReader, or null.

Throws:

java.lang.IllegalArgumentException - if writer is null.

See Also:

getImageWriter(ImageReader)

getImageWriters

public static java.util.Iterator getImageWriters(ImageTypeSpecifier type,
                                                 java.lang.String formatName)

Returns an Iterator containing all ImageWriters that claim to be able to encode images of the given layout (specified using an ImageTypeSpecifier) in the given format.

Parameters:

type - an ImageTypeSpecifier indicating the layout of the image to be written.

formatName - the informal name of the format.

Returns:

an Iterator containing ImageWriters.

Throws:

java.lang.IllegalArgumentException - if any parameter is null.

read

public static BufferedImage read(java.io.File input)
                          throws java.io.IOException

Returns a BufferedImage as the result of decoding a supplied File with an ImageReader The File is wrapped in an ImageInputStream. If no ImageReader claims to be able to read the resulting stream, null is returned.

The current cache settings from getUseCacheand getCacheDirectory will be used to control caching in the ImageInputStream that is created.

Note that there is no read method that takes a filename as a String; use this method instead after creating a File from the filename.

Parameters:

input - a File to read from.

Returns:

a BufferedImage containing the decoded contents of the input, or null.

Throws:

java.lang.IllegalArgumentException - if input is null.

java.io.IOException - if an error occurs during reading.

read

public static BufferedImage read(java.io.InputStream input)
                          throws java.io.IOException

Returns a BufferedImage as the result of decoding a supplied InputStream with an ImageReader. The InputStream is wrapped in an ImageInputStream. If no ImageReader claims to be able to read the resulting stream, null is returned.

The current cache settings from getUseCacheand getCacheDirectory will be used to control caching in the ImageInputStream that is created.

Parameters:

input - an InputStream to read from.

Returns:

a BufferedImage containing the decoded contents of the input, or null.

Throws:

java.lang.IllegalArgumentException - if input is null.

java.io.IOException - if an error occurs during reading.

read

public static BufferedImage read(java.net.URL input)
                          throws java.io.IOException

Returns a BufferedImage as the result of decoding a supplied URL with an ImageReader An InputStream is obtained from the URL, which is wrapped in an ImageInputStream. If no ImageReader claims to be able to read the resulting stream, null is returned.

The current cache settings from getUseCacheand getCacheDirectory will be used to control caching in the ImageInputStream that is created.

Parameters:

input - a URL to read from.

Returns:

a BufferedImage containing the decoded contents of the input, or null.

Throws:

java.lang.IllegalArgumentException - if input is null.

java.io.IOException - if an error occurs during reading.

read

public static BufferedImage read(ImageInputStream stream)
                          throws java.io.IOException

Returns a BufferedImage as the result of decoding a supplied ImageInputStream with an ImageReader. If no ImageReader claims to be able to read the stream, null is returned.

Parameters:

stream - an ImageInputStream to read from.

Returns:

a BufferedImage containing the decoded contents of the input, or null.

Throws:

java.lang.IllegalArgumentException - if stream is null.

java.io.IOException - if an error occurs during reading.

write

public static boolean write(RenderedImage im,
                            java.lang.String formatName,
                            ImageOutputStream output)
                     throws java.io.IOException

Writes an image using the an arbitrary ImageWriter that supports the given format to an ImageOutputStream. The image is written to the ImageOutputStream starting at the current stream pointer, overwriting existing stream data from that point forward, if present.

Parameters:

im - a RenderedImage to be written.

formatName - a String containg the informal name of the format.

output - an ImageOutputStream to be written to.

Returns:

false if no appropriate writer is found.

Throws:

java.lang.IllegalArgumentException - if any parameter is null.

java.lang.IllegalArgumentException - if im is not a BufferedImage. See restriction on RenderedImage.

java.io.IOException - if an error occurs during writing.

write

public static boolean write(RenderedImage im,
                            java.lang.String formatName,
                            java.io.File output)
                     throws java.io.IOException

Writes an image using an arbitrary ImageWriter that supports the given format to a File. If there is already a File present, its contents are discarded.

Parameters:

im - a RenderedImage to be written.

formatName - a String containg the informal name of the format.

output - a File to be written to.

Returns:

false if no appropriate writer is found.

Throws:

java.lang.IllegalArgumentException - if any parameter is null.

java.lang.IllegalArgumentException - if im is not a BufferedImage. See restriction on RenderedImage.

java.io.IOException - if an error occurs during writing.

write

public static boolean write(RenderedImage im,
                            java.lang.String formatName,
                            java.io.OutputStream output)
                     throws java.io.IOException

Writes an image using an arbitrary ImageWriter that supports the given format to an OutputStream.

The current cache settings from getUseCacheand getCacheDirectory will be used to control caching.

Parameters:

im - a RenderedImage to be written.

formatName - a String containg the informal name of the format.

output - an OutputStream to be written to.

Returns:

false if no appropriate writer is found.

Throws:

java.lang.IllegalArgumentException - if any parameter is null.

java.lang.IllegalArgumentException - if im is not a BufferedImage. See restriction on RenderedImage.

java.io.IOException - if an error occurs during writing.