FileDocCategorySizeDatePackage
ImageIO.javaAPI DocJava SE 5 API54878Fri Aug 26 14:57:30 BST 2005javax.imageio

ImageIO

public final class ImageIO extends Object
A class containing static convenience methods for locating ImageReaders and ImageWriters, and performing simple encoding and decoding.
version
0.5

Fields Summary
private static final IIORegistry
theRegistry
private static Method
readerFormatNamesMethod
private static Method
readerFileSuffixesMethod
private static Method
readerMIMETypesMethod
private static Method
writerFormatNamesMethod
private static Method
writerFileSuffixesMethod
private static Method
writerMIMETypesMethod
Constructors Summary
private ImageIO()
Constructor is private to prevent instantiation.


               
      
Methods Summary
private static booleancontains(java.lang.String[] names, java.lang.String name)

        for (int i = 0; i < names.length; i++) {
            if (name.equalsIgnoreCase(names[i])) {
                return true;
            }
        }

        return false;
    
public static javax.imageio.stream.ImageInputStreamcreateImageInputStream(java.lang.Object input)
Returns an ImageInputStream that will take its input from the given Object. The set of ImageInputStreamSpis registered with the IIORegistry class is queried and the first one that is able to take input from the supplied object is used to create the returned ImageInputStream. If no suitable ImageInputStreamSpi exists, null is returned.

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

param
input an Object to be used as an input source, such as a File, readable RandomAccessFile, or InputStream.
return
an ImageInputStream, or null.
exception
IllegalArgumentException if input is null.
exception
IOException if a cache file is needed but cannot be created.
see
javax.imageio.spi.ImageInputStreamSpi

        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageInputStreamSpi.class,
                                                   true);
        } catch (IllegalArgumentException e) {
            return null;
        }

        boolean usecache = getUseCache() && hasCachePermission();

        while (iter.hasNext()) {
            ImageInputStreamSpi spi = (ImageInputStreamSpi)iter.next();
            if (spi.getInputClass().isInstance(input)) {
                try {
                    return spi.createInputStreamInstance(input,
                                                         usecache,
                                                         getCacheDirectory());
                } catch (IOException e) {
                    throw new IIOException("Can't create cache file!", e);
                }
            }
        }

        return null;
    
public static javax.imageio.stream.ImageOutputStreamcreateImageOutputStream(java.lang.Object output)
Returns an ImageOutputStream that will send its output to the given Object. The set of ImageOutputStreamSpis registered with the IIORegistry class is queried and the first one that is able to send output from the supplied object is used to create the returned ImageOutputStream. If no suitable ImageOutputStreamSpi exists, null is returned.

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

param
output an Object to be used as an output destination, such as a File, writable RandomAccessFile, or OutputStream.
return
an ImageOutputStream, or null.
exception
IllegalArgumentException if output is null.
exception
IOException if a cache file is needed but cannot be created.
see
javax.imageio.spi.ImageOutputStreamSpi

        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageOutputStreamSpi.class,
                                                   true);
        } catch (IllegalArgumentException e) {
            return null;
        }

        boolean usecache = getUseCache() && hasCachePermission();

        while (iter.hasNext()) {
            ImageOutputStreamSpi spi = (ImageOutputStreamSpi)iter.next();
            if (spi.getOutputClass().isInstance(output)) {
                try {
                    return spi.createOutputStreamInstance(output,
                                                          usecache,
                                                          getCacheDirectory());
                } catch (IOException e) {
                    throw new IIOException("Can't create cache file!", e);
                }
            }
        }

        return null;
    
public static java.io.FilegetCacheDirectory()
Returns the current value set by setCacheDirectory, or null if no explicit setting has been made.

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

        return getCacheInfo().getCacheDirectory();
    
private static synchronized javax.imageio.ImageIO$CacheInfogetCacheInfo()
Returns the CacheInfo object associated with this ThreadGroup.

        AppContext context = AppContext.getAppContext();
        CacheInfo info = (CacheInfo)context.get(CacheInfo.class);
        if (info == null) {
            info = new CacheInfo();
            context.put(CacheInfo.class, info);
        }
        return info;
    
public static javax.imageio.ImageReadergetImageReader(javax.imageio.ImageWriter writer)
Returns an ImageReadercorresponding to the given ImageWriter, if there is one, or null if the plug-in for this ImageWriter does not specify a corresponding ImageReader, or if the given ImageWriter is not registered. This method is provided principally for symmetry with getImageWriter(ImageReader). Note that this method returns the "preferred" reader, which is the first in the list returned by javax.imageio.spi.ImageWriterSpi.getImageReaderSpiNames().

param
writer an instance of a registered ImageWriter.
return
an ImageReader, or null.
exception
IllegalArgumentException if writer is null.
see
#getImageWriter(ImageReader)
see
javax.imageio.spi.ImageWriterSpi#getImageReaderSpiNames()

        if (writer == null) {
            throw new IllegalArgumentException("writer == null!");
        }

        ImageWriterSpi writerSpi = writer.getOriginatingProvider();
        if (writerSpi == null) {
            Iterator writerSpiIter;
            // Ensure category is present
            try {
                writerSpiIter =
                    theRegistry.getServiceProviders(ImageWriterSpi.class,
                                                    false);
            } catch (IllegalArgumentException e) {
                return null;
            }

            while (writerSpiIter.hasNext()) {
                ImageWriterSpi temp = (ImageWriterSpi) writerSpiIter.next();
                if (temp.isOwnWriter(writer)) {
                    writerSpi = temp;
                    break;
                }
            }
            if (writerSpi == null) {
                return null;
            }
        }

        String[] readerNames = writerSpi.getImageReaderSpiNames();
        if (readerNames == null) {
            return null;
        }

        Class readerSpiClass = null;
        try {
            readerSpiClass = Class.forName(readerNames[0], true,
                                           ClassLoader.getSystemClassLoader());
        } catch (ClassNotFoundException e) {
            return null;
        }

        ImageReaderSpi readerSpi = (ImageReaderSpi)
            theRegistry.getServiceProviderByClass(readerSpiClass);
        if (readerSpi == null) {
            return null;
        }

        try {
            return readerSpi.createReaderInstance();
        } catch (IOException e) {
            // Deregister the spi in this case, but only as a readerSpi
            theRegistry.deregisterServiceProvider(readerSpi,
                                                  ImageReaderSpi.class);
            return null;
        }
    
public static java.util.IteratorgetImageReaders(java.lang.Object input)
Returns an Iterator containing all currently registered 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.

param
input an ImageInputStream or other Object containing encoded image data.
return
an Iterator containing ImageReaders.
exception
IllegalArgumentException if input is null.
see
javax.imageio.spi.ImageReaderSpi#canDecodeInput

        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                              new CanDecodeInputFilter(input),
                                              true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }

        return new ImageReaderIterator(iter);
    
public static java.util.IteratorgetImageReadersByFormatName(java.lang.String formatName)
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode the named format.

param
formatName a String containing the informal name of a format (e.g., "jpeg" or "tiff".
return
an Iterator containing ImageReaders.
exception
IllegalArgumentException if formatName is null.
see
javax.imageio.spi.ImageReaderSpi#getFormatNames

        try {
            readerFormatNamesMethod =
                ImageReaderSpi.class.getMethod("getFormatNames", null);
            readerFileSuffixesMethod =
                ImageReaderSpi.class.getMethod("getFileSuffixes", null);
            readerMIMETypesMethod =
                ImageReaderSpi.class.getMethod("getMIMETypes", null);
            
            writerFormatNamesMethod =
                ImageWriterSpi.class.getMethod("getFormatNames", null);
            writerFileSuffixesMethod =
                ImageWriterSpi.class.getMethod("getFileSuffixes", null);
            writerMIMETypesMethod =
                ImageWriterSpi.class.getMethod("getMIMETypes", null);
        } catch (NoSuchMethodException e) {
            e.printStackTrace();
        }
    
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        } 
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                    new ContainsFilter(readerFormatNamesMethod,
                                                       formatName),
                                                true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageReaderIterator(iter);
    
public static java.util.IteratorgetImageReadersByMIMEType(java.lang.String MIMEType)
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode files with the given MIME type.

param
MIMEType a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").
return
an Iterator containing ImageReaders.
exception
IllegalArgumentException if MIMEType is null.
see
javax.imageio.spi.ImageReaderSpi#getMIMETypes

        if (MIMEType == null) {
            throw new IllegalArgumentException("MIMEType == null!");
        }
        // Ensure category is present
        Iterator iter;
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                      new ContainsFilter(readerMIMETypesMethod,
                                                         MIMEType),
                                              true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageReaderIterator(iter);
    
public static java.util.IteratorgetImageReadersBySuffix(java.lang.String fileSuffix)
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode files with the given suffix.

param
fileSuffix a String containing a file suffix (e.g., "jpg" or "tiff").
return
an Iterator containing ImageReaders.
exception
IllegalArgumentException if fileSuffix is null.
see
javax.imageio.spi.ImageReaderSpi#getFileSuffixes

        if (fileSuffix == null) {
            throw new IllegalArgumentException("fileSuffix == null!");
        }
        // Ensure category is present
        Iterator iter;
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                   new ContainsFilter(readerFileSuffixesMethod,
                                                      fileSuffix),
                                              true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageReaderIterator(iter);
    
public static java.util.IteratorgetImageTranscoders(javax.imageio.ImageReader reader, javax.imageio.ImageWriter writer)
Returns an Iterator containing all currently registered ImageTranscoders that claim to be able to transcode between the metadata of the given ImageReader and ImageWriter.

param
reader an ImageReader.
param
writer an ImageWriter.
return
an Iterator containing ImageTranscoders.
exception
IllegalArgumentException if reader or writer is null.

        if (reader == null) {
            throw new IllegalArgumentException("reader == null!");
        }
        if (writer == null) {
            throw new IllegalArgumentException("writer == null!");
        }
        ImageReaderSpi readerSpi = reader.getOriginatingProvider();
        ImageWriterSpi writerSpi = writer.getOriginatingProvider();
        ServiceRegistry.Filter filter =
            new TranscoderFilter(readerSpi, writerSpi);

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageTranscoderSpi.class,
                                            filter, true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageTranscoderIterator(iter);
    
public static javax.imageio.ImageWritergetImageWriter(javax.imageio.ImageReader reader)
Returns an ImageWritercorresponding to the given ImageReader, if there is one, or null if the plug-in for this ImageReader does not specify a corresponding ImageWriter, or if the given ImageReader is not registered. This mechanism may be used to obtain an ImageWriter that will understand the internal structure of non-pixel metadata (as encoded by IIOMetadata objects) generated by the ImageReader. 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 preserving all metadata, without having to understand anything about the structure of the metadata, or even about the image format. Note that this method returns the "preferred" writer, which is the first in the list returned by javax.imageio.spi.ImageReaderSpi.getImageWriterSpiNames().

param
reader an instance of a registered ImageReader.
return
an ImageWriter, or null.
exception
IllegalArgumentException if reader is null.
see
#getImageReader(ImageWriter)
see
javax.imageio.spi.ImageReaderSpi#getImageWriterSpiNames()

        if (reader == null) {
            throw new IllegalArgumentException("reader == null!");
        }

        ImageReaderSpi readerSpi = reader.getOriginatingProvider();
        if (readerSpi == null) {
            Iterator readerSpiIter;
            // Ensure category is present
            try {
                readerSpiIter = 
                    theRegistry.getServiceProviders(ImageReaderSpi.class,
                                                    false);
            } catch (IllegalArgumentException e) {
                return null;
            }

            while (readerSpiIter.hasNext()) {
                ImageReaderSpi temp = (ImageReaderSpi) readerSpiIter.next();
                if (temp.isOwnReader(reader)) {
                    readerSpi = temp;
                    break;
                }
            }
            if (readerSpi == null) {
                return null;
            }
        }

        String[] writerNames = readerSpi.getImageWriterSpiNames();
        if (writerNames == null) {
            return null;
        }

        Class writerSpiClass = null;
        try {
            writerSpiClass = Class.forName(writerNames[0], true,
                                           ClassLoader.getSystemClassLoader());
        } catch (ClassNotFoundException e) {
            return null;
        }

        ImageWriterSpi writerSpi = (ImageWriterSpi)
            theRegistry.getServiceProviderByClass(writerSpiClass);
        if (writerSpi == null) {
            return null;
        }

        try {
            return writerSpi.createWriterInstance();
        } catch (IOException e) {
            // Deregister the spi in this case, but only as a writerSpi
            theRegistry.deregisterServiceProvider(writerSpi,
                                                  ImageWriterSpi.class);
            return null;
        }
    
public static java.util.IteratorgetImageWriters(javax.imageio.ImageTypeSpecifier type, java.lang.String formatName)
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode images of the given layout (specified using an ImageTypeSpecifier) in the given format.

param
type an ImageTypeSpecifier indicating the layout of the image to be written.
param
formatName the informal name of the format.
return
an Iterator containing ImageWriters.
exception
IllegalArgumentException if any parameter is null.
see
javax.imageio.spi.ImageWriterSpi#canEncodeImage(ImageTypeSpecifier)

        if (type == null) {
            throw new IllegalArgumentException("type == null!");
        }
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                 new CanEncodeImageAndFormatFilter(type,
                                                                   formatName),
                                            true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }

        return new ImageWriterIterator(iter);
    
public static java.util.IteratorgetImageWritersByFormatName(java.lang.String formatName)
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode the named format.

param
formatName a String containing the informal name of a format (e.g., "jpeg" or "tiff".
return
an Iterator containing ImageWriters.
exception
IllegalArgumentException if formatName is null.
see
javax.imageio.spi.ImageWriterSpi#getFormatNames

        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        } 
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                    new ContainsFilter(writerFormatNamesMethod,
                                                       formatName),
                                            true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageWriterIterator(iter);
    
public static java.util.IteratorgetImageWritersByMIMEType(java.lang.String MIMEType)
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode files with the given MIME type.

param
MIMEType a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").
return
an Iterator containing ImageWriters.
exception
IllegalArgumentException if MIMEType is null.
see
javax.imageio.spi.ImageWriterSpi#getMIMETypes

        if (MIMEType == null) {
            throw new IllegalArgumentException("MIMEType == null!");
        }
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                      new ContainsFilter(writerMIMETypesMethod,
                                                         MIMEType),
                                            true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageWriterIterator(iter);
    
public static java.util.IteratorgetImageWritersBySuffix(java.lang.String fileSuffix)
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode files with the given suffix.

param
fileSuffix a String containing a file suffix (e.g., "jpg" or "tiff").
return
an Iterator containing ImageWriters.
exception
IllegalArgumentException if fileSuffix is null.
see
javax.imageio.spi.ImageWriterSpi#getFileSuffixes

        if (fileSuffix == null) {
            throw new IllegalArgumentException("fileSuffix == null!");
        }
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                   new ContainsFilter(writerFileSuffixesMethod,
                                                      fileSuffix),
                                            true);
        } catch (IllegalArgumentException e) {
            return new HashSet().iterator();
        }
        return new ImageWriterIterator(iter);
    
public static java.lang.String[]getReaderFormatNames()
Returns an array of Strings listing all of the informal format names understood by the current set of registered readers.

return
an array of Strings.

 
        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class, true);
        } catch (IllegalArgumentException e) {
            return new String[0];
        }

        Set s = new HashSet();
        while (iter.hasNext()) {
            ImageReaderSpi spi = (ImageReaderSpi)iter.next();
            String[] names = spi.getFormatNames();
            for (int i = 0; i < names.length; i++) {
                s.add(names[i]);
            }
        }

        return toStringArray(s);
   
public static java.lang.String[]getReaderMIMETypes()
Returns an array of Strings listing all of the MIME types understood by the current set of registered readers.

return
an array of Strings.

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class, true);
        } catch (IllegalArgumentException e) {
            return new String[0];
        }

        Set s = new HashSet();
        while (iter.hasNext()) {
            ImageReaderSpi spi = (ImageReaderSpi)iter.next();
            String[] names = spi.getMIMETypes();
            for (int i = 0; i < names.length; i++) {
                s.add(names[i]);
            }
        }

        return toStringArray(s);
    
private static java.lang.StringgetTempDir()
Returns the default temporary (cache) directory as defined by the java.io.tmpdir system property.

        GetPropertyAction a = new GetPropertyAction("java.io.tmpdir");
        return (String)AccessController.doPrivileged(a);
    
public static booleangetUseCache()
Returns the current value set by setUseCache, or true if no explicit setting has been made.

return
true if a disk-based cache may be used for ImageInputStreams and ImageOutputStreams.
see
#setUseCache

        return getCacheInfo().getUseCache();
    
public static java.lang.String[]getWriterFormatNames()
Returns an array of Strings listing all of the informal format names understood by the current set of registered writers.

return
an array of Strings.

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class, true);
        } catch (IllegalArgumentException e) {
            return new String[0];
        }

        Set s = new HashSet();
        while (iter.hasNext()) {
            ImageWriterSpi spi = (ImageWriterSpi)iter.next();
            String[] names = spi.getFormatNames();
            for (int i = 0; i < names.length; i++) {
                s.add(names[i]);
            }
        }

        return toStringArray(s);
    
public static java.lang.String[]getWriterMIMETypes()
Returns an array of Strings listing all of the MIME types understood by the current set of registered writers.

return
an array of Strings.

        Iterator iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class, true);
        } catch (IllegalArgumentException e) {
            return new String[0];
        }
        
        Set s = new HashSet();
        while (iter.hasNext()) {
            ImageWriterSpi spi = (ImageWriterSpi)iter.next();
            String[] names = spi.getMIMETypes();
            for (int i = 0; i < names.length; i++) {
                s.add(names[i]);
            }
        }

        return toStringArray(s);
    
private static booleanhasCachePermission()
Determines whether the caller has write access to the cache directory, stores the result in the CacheInfo object, and returns the decision. This method helps to prevent mysterious SecurityExceptions to be thrown when this convenience class is used in an applet, for example.

        Boolean hasPermission = getCacheInfo().getHasPermission();

        if (hasPermission != null) {
            return hasPermission.booleanValue();
        } else {
            try {
                SecurityManager security = System.getSecurityManager();
                if (security != null) {
                    File cachedir = getCacheDirectory();
                    String cachepath;

                    if (cachedir != null) {
                        cachepath = cachedir.getPath();
                    } else {
                        cachepath = getTempDir();

                        if (cachepath == null) {
                            getCacheInfo().setHasPermission(Boolean.FALSE);
                            return false;
                        }
                    }

                    security.checkWrite(cachepath);
                }
            } catch (SecurityException e) {
                getCacheInfo().setHasPermission(Boolean.FALSE);
                return false;
            }

            getCacheInfo().setHasPermission(Boolean.TRUE);
            return true;
        }
    
public static java.awt.image.BufferedImageread(java.io.File input)
Returns a BufferedImage as the result of decoding a supplied File with an ImageReader chosen automatically from among those currently registered. The File is wrapped in an ImageInputStream. If no registered 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.

This methods does not attempt to locate ImageReaders that can read directly from a File; that may be accomplished using IIORegistry and ImageReaderSpi.

param
input a File to read from.
return
a BufferedImage containing the decoded contents of the input, or null.
exception
IllegalArgumentException if input is null.
exception
IOException if an error occurs during reading.

        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }
        if (!input.canRead()) {
            throw new IIOException("Can't read input file!");
        }

        ImageInputStream stream = createImageInputStream(input);
        if (stream == null) {
            throw new IIOException("Can't create an ImageInputStream!");
        }
        return read(stream);
    
public static java.awt.image.BufferedImageread(java.io.InputStream input)
Returns a BufferedImage as the result of decoding a supplied InputStream with an ImageReader chosen automatically from among those currently registered. The InputStream is wrapped in an ImageInputStream. If no registered 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.

This methods does not attempt to locate ImageReaders that can read directly from an InputStream; that may be accomplished using IIORegistry and ImageReaderSpi.

param
input an InputStream to read from.
return
a BufferedImage containing the decoded contents of the input, or null.
exception
IllegalArgumentException if input is null.
exception
IOException if an error occurs during reading.

        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }

        ImageInputStream stream = createImageInputStream(input);
        return read(stream);
    
public static java.awt.image.BufferedImageread(java.net.URL input)
Returns a BufferedImage as the result of decoding a supplied URL with an ImageReader chosen automatically from among those currently registered. An InputStream is obtained from the URL, which is wrapped in an ImageInputStream. If no registered 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.

This methods does not attempt to locate ImageReaders that can read directly from a URL; that may be accomplished using IIORegistry and ImageReaderSpi.

param
input a URL to read from.
return
a BufferedImage containing the decoded contents of the input, or null.
exception
IllegalArgumentException if input is null.
exception
IOException if an error occurs during reading.

        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }

        InputStream istream = null;
        try {
            istream = input.openStream();
        } catch (IOException e) {
            throw new IIOException("Can't get input stream from URL!", e);
        }
        ImageInputStream stream = createImageInputStream(istream);
        BufferedImage bi = read(stream);
        istream.close();
        return bi;
    
public static java.awt.image.BufferedImageread(javax.imageio.stream.ImageInputStream stream)
Returns a BufferedImage as the result of decoding a supplied ImageInputStream with an ImageReader chosen automatically from among those currently registered. If no registered ImageReader claims to be able to read the stream, null is returned.

param
stream an ImageInputStream to read from.
return
a BufferedImage containing the decoded contents of the input, or null.
exception
IllegalArgumentException if stream is null.
exception
IOException if an error occurs during reading.

        if (stream == null) {
            throw new IllegalArgumentException("stream == null!");
        }

        Iterator iter = getImageReaders(stream);
        if (!iter.hasNext()) {
            return null;
        }

        ImageReader reader = (ImageReader)iter.next();
        ImageReadParam param = reader.getDefaultReadParam();
        reader.setInput(stream, true, true);
        BufferedImage bi = reader.read(0, param);
        stream.close();
        reader.dispose();
        return bi;
    
public static voidscanForPlugins()
Scans for plug-ins on the application class path, loads their service provider classes, and registers a service provider instance for each one found with the IIORegistry.

This method is needed because the application class path can theoretically change, or additional plug-ins may become available. Rather than re-scanning the classpath on every invocation of the API, the class path is scanned automatically only on the first invocation. Clients can call this method to prompt a re-scan. Thus this method need only be invoked by sophisticated applications which dynamically make new plug-ins available at runtime.

The getResources method of the context ClassLoader is used locate JAR files containing files named META-INF/services/javax.imageio.spi.classname, where classname is one of ImageReaderSpi, ImageWriterSpi, ImageTranscoderSpi, ImageInputStreamSpi, or ImageOutputStreamSpi, along the application class path.

The contents of the located files indicate the names of actual implementation classes which implement the aforementioned service provider interfaces; the default class loader is then used to load each of these classes and to instantiate an instance of each class, which is then placed into the registry for later retrieval.

The exact set of locations searched depends on the implementation of the Java runtime enviroment.

see
ClassLoader#getResources

        theRegistry.registerApplicationClasspathSpis();
    
public static voidsetCacheDirectory(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.

param
cacheDirectory a File specifying a directory.
see
File#createTempFile(String, String, File)
exception
SecurityException if the security manager denies access to the directory.
exception
IllegalArgumentException if cacheDir is non-null but is not a directory.
see
#getCacheDirectory

        if ((cacheDirectory != null) && !(cacheDirectory.isDirectory())) {
            throw new IllegalArgumentException("Not a directory!");
        }
        getCacheInfo().setCacheDirectory(cacheDirectory);
        getCacheInfo().setHasPermission(null);
    
public static voidsetUseCache(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.

param
useCache a boolean indicating whether a cache file should be used, in cases where it is optional.
see
#getUseCache

        getCacheInfo().setUseCache(useCache);
    
private static java.lang.String[]toStringArray(java.util.Set s)

        String[] val = new String[s.size()];
        Iterator iter = s.iterator();
        int index = 0;
        while (iter.hasNext()) {
            val[index++] = (String)iter.next();
        }

        return val;
    
public static booleanwrite(java.awt.image.RenderedImage im, java.lang.String formatName, javax.imageio.stream.ImageOutputStream output)
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.

param
im a RenderedImage to be written.
param
formatName a String containg the informal name of the format.
param
output an ImageOutputStream to be written to.
return
false if no appropriate writer is found.
exception
IllegalArgumentException if any parameter is null.
exception
IOException if an error occurs during writing.

        if (im == null) {
            throw new IllegalArgumentException("im == null!");
        }
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }

        ImageWriter writer = null;
        ImageTypeSpecifier type =
            ImageTypeSpecifier.createFromRenderedImage(im);
        Iterator iter = getImageWriters(type, formatName);
        if (iter.hasNext()) {
            writer = (ImageWriter)iter.next();
        }
        if (writer == null) {
            return false;
        }

        writer.setOutput(output);
        writer.write(im);
        output.flush();
        writer.dispose();
        
        return true;
    
public static booleanwrite(java.awt.image.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. If there is already a File present, its contents are discarded.

param
im a RenderedImage to be written.
param
formatName a String containg the informal name of the format.
param
output a File to be written to.
return
false if no appropriate writer is found.
exception
IllegalArgumentException if any parameter is null.
exception
IOException if an error occurs during writing.

        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }
        ImageOutputStream stream = null;
        try {
            output.delete();
            stream = createImageOutputStream(output);
        } catch (IOException e) {
            throw new IIOException("Can't create output stream!", e);
        }

        boolean val = write(im, formatName, stream);
        stream.close();
        return val;
    
public static booleanwrite(java.awt.image.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.

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

param
im a RenderedImage to be written.
param
formatName a String containg the informal name of the format.
param
output an OutputStream to be written to.
return
false if no appropriate writer is found.
exception
IllegalArgumentException if any parameter is null.
exception
IOException if an error occurs during writing.

        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }
        ImageOutputStream stream = null;
        try {
            stream = createImageOutputStream(output);
        } catch (IOException e) {
            throw new IIOException("Can't create output stream!", e);
        }

        boolean val = write(im, formatName, stream);
        stream.close();
        return val;