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
getImageReaders(Object input)
Retrieve an iterator over the collection of registered image readers that support reading data from the given object.
static Iterator
getImageReadersByFormatName(String formatName)
Retrieve an iterator over all registered readers for the given format.
static Iterator
getImageReadersByMIMEType(String MIMEType)
Retrieve an iterator over all registered readers for the given MIME type.
static Iterator
getImageReadersBySuffix(String fileSuffix)
Retrieve an iterator over all registered readers for the given file suffix.
static Iterator
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
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
getImageWritersByFormatName(String formatName)
Retrieve an iterator over all registered writers for the given format.
static Iterator
getImageWritersByMIMEType(String MIMEType)
Retrieve an iterator over all registered writers for the given MIME type.
static Iterator
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(InputStream input)
Create a buffered image from an input stream.
static BufferedImage
read(URL input)
Create a buffered image from a URL.
static BufferedImage
read(ImageInputStream stream)
Create a buffered image from an image input stream.
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.

Methods inherited from class java.lang.Object

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

Method Details

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:

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 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 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 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 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 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 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 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 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 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(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


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(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(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


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


ImageIO.java -- Copyright (C) 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.