https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code 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
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.imageio;

import java.awt.image.BufferedImage;
import java.awt.image.RenderedImage;
import java.io.File;
import java.io.FilePermission;
import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.lang.reflect.Method;
import java.net.URL;
import java.security.AccessController;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Set;
import javax.imageio.spi.IIORegistry;
import javax.imageio.spi.ImageReaderSpi;
import javax.imageio.spi.ImageReaderWriterSpi;
import javax.imageio.spi.ImageWriterSpi;
import javax.imageio.spi.ImageInputStreamSpi;
import javax.imageio.spi.ImageOutputStreamSpi;
import javax.imageio.spi.ImageTranscoderSpi;
import javax.imageio.spi.ServiceRegistry;
import javax.imageio.stream.ImageInputStream;
import javax.imageio.stream.ImageOutputStream;
import sun.awt.AppContext;
import sun.security.action.GetPropertyAction;


A class containing static convenience methods for locating ImageReaders and ImageWriters, and performing simple encoding and decoding. 
/**
 * A class containing static convenience methods for locating
 * {@code ImageReader}s and {@code ImageWriter}s, and
 * performing simple encoding and decoding.
 *
 */
public final class ImageIO {

    private static final IIORegistry theRegistry =
        IIORegistry.getDefaultInstance();

    
Constructor is private to prevent instantiation.

/**
     * Constructor is private to prevent instantiation.
     */
    private ImageIO() {}

    
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 environment.

See Also:
/**
     * 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
     * {@code IIORegistry}.
     *
     * <p>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.
     *
     * <p> The {@code getResources} method of the context
     * {@code ClassLoader} is used locate JAR files containing
     * files named
     * {@code META-INF/services/javax.imageio.spi.}<i>classname</i>,
     * where <i>classname</i> is one of {@code ImageReaderSpi},
     * {@code ImageWriterSpi}, {@code ImageTranscoderSpi},
     * {@code ImageInputStreamSpi}, or
     * {@code ImageOutputStreamSpi}, along the application class
     * path.
     *
     * <p> 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.
     *
     * <p> The exact set of locations searched depends on the
     * implementation of the Java runtime environment.
     *
     * @see ClassLoader#getResources
     */
    public static void scanForPlugins() {
        theRegistry.registerApplicationClasspathSpis();
    }

    // ImageInputStreams

    
A class to hold information about caching. Each ThreadGroup will have its own copy via the AppContext mechanism. 
/**
     * A class to hold information about caching.  Each
     * {@code ThreadGroup} will have its own copy
     * via the {@code AppContext} mechanism.
     */
    static class CacheInfo {
        boolean useCache = true;
        File cacheDirectory = null;
        Boolean hasPermission = null;

        public CacheInfo() {}

        public boolean getUseCache() {
            return useCache;
        }

        public void setUseCache(boolean useCache) {
            this.useCache = useCache;
        }

        public File getCacheDirectory() {
            return cacheDirectory;
        }

        public void setCacheDirectory(File cacheDirectory) {
            this.cacheDirectory = cacheDirectory;
        }

        public Boolean getHasPermission() {
            return hasPermission;
        }

        public void setHasPermission(Boolean hasPermission) {
            this.hasPermission = hasPermission;
        }
    }

    
Returns the CacheInfo object associated with this ThreadGroup. 
/**
     * Returns the {@code CacheInfo} object associated with this
     * {@code ThreadGroup}.
     */
    private static synchronized CacheInfo getCacheInfo() {
        AppContext context = AppContext.getAppContext();
        CacheInfo info = (CacheInfo)context.get(CacheInfo.class);
        if (info == null) {
            info = new CacheInfo();
            context.put(CacheInfo.class, info);
        }
        return info;
    }

    
Returns the default temporary (cache) directory as defined by the
java.io.tmpdir system property.

/**
     * Returns the default temporary (cache) directory as defined by the
     * java.io.tmpdir system property.
     */
    private static String getTempDir() {
        GetPropertyAction a = new GetPropertyAction("java.io.tmpdir");
        return AccessController.doPrivileged(a);
    }

    
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. 
/**
     * Determines whether the caller has write access to the cache
     * directory, stores the result in the {@code 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.
     */
    private static boolean hasCachePermission() {
        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 || cachepath.isEmpty()) {
                            getCacheInfo().setHasPermission(Boolean.FALSE);
                            return false;
                        }
                    }

                    // we have to check whether we can read, write,
                    // and delete cache files.
                    // So, compose cache file path and check it.
                    String filepath = cachepath;
                    if (!filepath.endsWith(File.separator)) {
                        filepath += File.separator;
                    }
                    filepath += "*";

                    security.checkPermission(new FilePermission(filepath, "read, write, delete"));
                }
            } catch (SecurityException e) {
                getCacheInfo().setHasPermission(Boolean.FALSE);
                return false;
            }

            getCacheInfo().setHasPermission(Boolean.TRUE);
            return true;
        }
    }

    
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. 
Params:
  • useCache – a boolean indicating whether a cache file should be used, in cases where it is optional.
See Also:
/**
     * Sets a flag indicating whether a disk-based cache file should
     * be used when creating {@code ImageInputStream}s and
     * {@code ImageOutputStream}s.
     *
     * <p> When reading from a standard {@code 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
     * {@code OutputStream}, a cache may be used to allow a
     * previously written value to be changed before flushing it to
     * the final destination.
     *
     * <p> The cache may reside in main memory or on disk.  Setting
     * this flag to {@code 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.
     *
     * <p> On startup, the value is set to {@code true}.
     *
     * @param useCache a {@code boolean} indicating whether a
     * cache file should be used, in cases where it is optional.
     *
     * @see #getUseCache
     */
    public static void setUseCache(boolean useCache) {
        getCacheInfo().setUseCache(useCache);
    }

    
Returns the current value set by setUseCache, or true if no explicit setting has been made. 
See Also:
Returns:true if a disk-based cache may be used for ImageInputStreams and ImageOutputStreams.
/**
     * Returns the current value set by {@code setUseCache}, or
     * {@code true} if no explicit setting has been made.
     *
     * @return true if a disk-based cache may be used for
     * {@code ImageInputStream}s and
     * {@code ImageOutputStream}s.
     *
     * @see #setUseCache
     */
    public static boolean getUseCache() {
        return getCacheInfo().getUseCache();
    }

    
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. 
Params:
  • cacheDirectory – a File specifying a directory.
Throws:
See Also:
/**
     * Sets the directory where cache files are to be created.  A
     * value of {@code null} indicates that the system-dependent
     * default temporary-file directory is to be used.  If
     * {@code getUseCache} returns false, this value is ignored.
     *
     * @param cacheDirectory a {@code File} specifying a directory.
     *
     * @see File#createTempFile(String, String, File)
     *
     * @exception SecurityException if the security manager denies
     * access to the directory.
     * @exception IllegalArgumentException if {@code cacheDir} is
     * non-{@code null} but is not a directory.
     *
     * @see #getCacheDirectory
     */
    public static void setCacheDirectory(File cacheDirectory) {
        if ((cacheDirectory != null) && !(cacheDirectory.isDirectory())) {
            throw new IllegalArgumentException("Not a directory!");
        }
        getCacheInfo().setCacheDirectory(cacheDirectory);
        getCacheInfo().setHasPermission(null);
    }

    
Returns the current value set by setCacheDirectory, or null if no explicit setting has been made. 
See Also:
Returns:a File indicating the directory where cache files will be created, or null to indicate the system-dependent default temporary-file directory.
/**
     * Returns the current value set by
     * {@code setCacheDirectory}, or {@code null} if no
     * explicit setting has been made.
     *
     * @return a {@code File} indicating the directory where
     * cache files will be created, or {@code null} to indicate
     * the system-dependent default temporary-file directory.
     *
     * @see #setCacheDirectory
     */
    public static File getCacheDirectory() {
        return getCacheInfo().getCacheDirectory();
    }

    
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 getUseCache and getCacheDirectory will be used to control caching. 
Params:
  • input – an Object to be used as an input source, such as a File, readable RandomAccessFile, or InputStream.
Throws:
See Also:
Returns:an ImageInputStream, or null.
/**
     * Returns an {@code ImageInputStream} that will take its
     * input from the given {@code Object}.  The set of
     * {@code ImageInputStreamSpi}s registered with the
     * {@code IIORegistry} class is queried and the first one
     * that is able to take input from the supplied object is used to
     * create the returned {@code ImageInputStream}.  If no
     * suitable {@code ImageInputStreamSpi} exists,
     * {@code null} is returned.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching.
     *
     * @param input an {@code Object} to be used as an input
     * source, such as a {@code File}, readable
     * {@code RandomAccessFile}, or {@code InputStream}.
     *
     * @return an {@code ImageInputStream}, or {@code null}.
     *
     * @exception IllegalArgumentException if {@code input}
     * is {@code null}.
     * @exception IOException if a cache file is needed but cannot be
     * created.
     *
     * @see javax.imageio.spi.ImageInputStreamSpi
     */
    public static ImageInputStream createImageInputStream(Object input)
        throws IOException {
        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }

        Iterator<ImageInputStreamSpi> 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 = 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;
    }

    // ImageOutputStreams

    
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 getUseCache and getCacheDirectory will be used to control caching. 
Params:
  • output – an Object to be used as an output destination, such as a File, writable RandomAccessFile, or OutputStream.
Throws:
See Also:
Returns:an ImageOutputStream, or null.
/**
     * Returns an {@code ImageOutputStream} that will send its
     * output to the given {@code Object}.  The set of
     * {@code ImageOutputStreamSpi}s registered with the
     * {@code IIORegistry} class is queried and the first one
     * that is able to send output from the supplied object is used to
     * create the returned {@code ImageOutputStream}.  If no
     * suitable {@code ImageOutputStreamSpi} exists,
     * {@code null} is returned.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching.
     *
     * @param output an {@code Object} to be used as an output
     * destination, such as a {@code File}, writable
     * {@code RandomAccessFile}, or {@code OutputStream}.
     *
     * @return an {@code ImageOutputStream}, or
     * {@code null}.
     *
     * @exception IllegalArgumentException if {@code output} is
     * {@code null}.
     * @exception IOException if a cache file is needed but cannot be
     * created.
     *
     * @see javax.imageio.spi.ImageOutputStreamSpi
     */
    public static ImageOutputStream createImageOutputStream(Object output)
        throws IOException {
        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }

        Iterator<ImageOutputStreamSpi> 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 = 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;
    }

    private static enum SpiInfo {
        FORMAT_NAMES {
            @Override
            String[] info(ImageReaderWriterSpi spi) {
                return spi.getFormatNames();
            }
        },
        MIME_TYPES {
            @Override
            String[] info(ImageReaderWriterSpi spi) {
                return spi.getMIMETypes();
            }
        },
        FILE_SUFFIXES {
            @Override
            String[] info(ImageReaderWriterSpi spi) {
                return spi.getFileSuffixes();
            }
        };

        abstract String[] info(ImageReaderWriterSpi spi);
    }

    private static <S extends ImageReaderWriterSpi>
        String[] getReaderWriterInfo(Class<S> spiClass, SpiInfo spiInfo)
    {
        // Ensure category is present
        Iterator<S> iter;
        try {
            iter = theRegistry.getServiceProviders(spiClass, true);
        } catch (IllegalArgumentException e) {
            return new String[0];
        }

        HashSet<String> s = new HashSet<>();
        while (iter.hasNext()) {
            ImageReaderWriterSpi spi = iter.next();
            String[] info = spiInfo.info(spi);
            if (info != null) {
                Collections.addAll(s, info);
            }
        }

        return s.toArray(new String[s.size()]);
    }

    // Readers

    
Returns an array of Strings listing all of the informal format names understood by the current set of registered readers. 
Returns:an array of Strings.
/**
     * Returns an array of {@code String}s listing all of the
     * informal format names understood by the current set of registered
     * readers.
     *
     * @return an array of {@code String}s.
     */
    public static String[] getReaderFormatNames() {
        return getReaderWriterInfo(ImageReaderSpi.class,
                                   SpiInfo.FORMAT_NAMES);
    }

    
Returns an array of Strings listing all of the MIME types understood by the current set of registered readers. 
Returns:an array of Strings.
/**
     * Returns an array of {@code String}s listing all of the
     * MIME types understood by the current set of registered
     * readers.
     *
     * @return an array of {@code String}s.
     */
    public static String[] getReaderMIMETypes() {
        return getReaderWriterInfo(ImageReaderSpi.class,
                                   SpiInfo.MIME_TYPES);
    }

    
Returns an array of Strings listing all of the file suffixes associated with the formats understood by the current set of registered readers. 
Returns:an array of Strings.
Since:1.6
/**
     * Returns an array of {@code String}s listing all of the
     * file suffixes associated with the formats understood
     * by the current set of registered readers.
     *
     * @return an array of {@code String}s.
     * @since 1.6
     */
    public static String[] getReaderFileSuffixes() {
        return getReaderWriterInfo(ImageReaderSpi.class,
                                   SpiInfo.FILE_SUFFIXES);
    }

    static class ImageReaderIterator implements Iterator<ImageReader> {
        // Contains ImageReaderSpis
        private Iterator<ImageReaderSpi> iter;

        public ImageReaderIterator(Iterator<ImageReaderSpi> iter) {
            this.iter = iter;
        }

        public boolean hasNext() {
            return iter.hasNext();
        }

        public ImageReader next() {
            ImageReaderSpi spi = null;
            try {
                spi = iter.next();
                return spi.createReaderInstance();
            } catch (IOException e) {
                // Deregister the spi in this case, but only as
                // an ImageReaderSpi
                theRegistry.deregisterServiceProvider(spi, ImageReaderSpi.class);
            }
            return null;
        }

        public void remove() {
            throw new UnsupportedOperationException();
        }
    }

    static class CanDecodeInputFilter
        implements ServiceRegistry.Filter {

        Object input;

        public CanDecodeInputFilter(Object input) {
            this.input = input;
        }

        public boolean filter(Object elt) {
            try {
                ImageReaderSpi spi = (ImageReaderSpi)elt;
                ImageInputStream stream = null;
                if (input instanceof ImageInputStream) {
                    stream = (ImageInputStream)input;
                }

                // Perform mark/reset as a defensive measure
                // even though plug-ins are supposed to take
                // care of it.
                boolean canDecode = false;
                if (stream != null) {
                    stream.mark();
                }
                try {
                    canDecode = spi.canDecodeInput(input);
                } finally {
                    if (stream != null) {
                        stream.reset();
                    }
                }

                return canDecode;
            } catch (IOException e) {
                return false;
            }
        }
    }

    static class CanEncodeImageAndFormatFilter
        implements ServiceRegistry.Filter {

        ImageTypeSpecifier type;
        String formatName;

        public CanEncodeImageAndFormatFilter(ImageTypeSpecifier type,
                                             String formatName) {
            this.type = type;
            this.formatName = formatName;
        }

        public boolean filter(Object elt) {
            ImageWriterSpi spi = (ImageWriterSpi)elt;
            return Arrays.asList(spi.getFormatNames()).contains(formatName) &&
                spi.canEncodeImage(type);
        }
    }

    static class ContainsFilter
        implements ServiceRegistry.Filter {

        Method method;
        String name;

        // method returns an array of Strings
        public ContainsFilter(Method method,
                              String name) {
            this.method = method;
            this.name = name;
        }

        public boolean filter(Object elt) {
            try {
                return contains((String[])method.invoke(elt), name);
            } catch (Exception e) {
                return false;
            }
        }
    }

    
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.

Params:
  • input – an ImageInputStream or other Object containing encoded image data.
Throws:
See Also:
Returns:an Iterator containing ImageReaders.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageReader}s that claim to be able to
     * decode the supplied {@code Object}, typically an
     * {@code ImageInputStream}.
     *
     * <p> The stream position is left at its prior position upon
     * exit from this method.
     *
     * @param input an {@code ImageInputStream} or other
     * {@code Object} containing encoded image data.
     *
     * @return an {@code Iterator} containing {@code ImageReader}s.
     *
     * @exception IllegalArgumentException if {@code input} is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageReaderSpi#canDecodeInput
     */
    public static Iterator<ImageReader> getImageReaders(Object input) {
        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }
        Iterator<ImageReaderSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                              new CanDecodeInputFilter(input),
                                              true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }

        return new ImageReaderIterator(iter);
    }

    private static Method readerFormatNamesMethod;
    private static Method readerFileSuffixesMethod;
    private static Method readerMIMETypesMethod;
    private static Method writerFormatNamesMethod;
    private static Method writerFileSuffixesMethod;
    private static Method writerMIMETypesMethod;

    static {
        try {
            readerFormatNamesMethod =
                ImageReaderSpi.class.getMethod("getFormatNames");
            readerFileSuffixesMethod =
                ImageReaderSpi.class.getMethod("getFileSuffixes");
            readerMIMETypesMethod =
                ImageReaderSpi.class.getMethod("getMIMETypes");

            writerFormatNamesMethod =
                ImageWriterSpi.class.getMethod("getFormatNames");
            writerFileSuffixesMethod =
                ImageWriterSpi.class.getMethod("getFileSuffixes");
            writerMIMETypesMethod =
                ImageWriterSpi.class.getMethod("getMIMETypes");
        } catch (NoSuchMethodException e) {
            e.printStackTrace();
        }
    }

    
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode the named format. 
Params:
  • formatName – a String containing the informal name of a format (e.g., "jpeg" or "tiff".
Throws:
See Also:
Returns:an Iterator containing ImageReaders.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageReader}s that claim to be able to
     * decode the named format.
     *
     * @param formatName a {@code String} containing the informal
     * name of a format (<i>e.g.</i>, "jpeg" or "tiff".
     *
     * @return an {@code Iterator} containing
     * {@code ImageReader}s.
     *
     * @exception IllegalArgumentException if {@code formatName}
     * is {@code null}.
     *
     * @see javax.imageio.spi.ImageReaderSpi#getFormatNames
     */
    public static Iterator<ImageReader>
        getImageReadersByFormatName(String formatName)
    {
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        Iterator<ImageReaderSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                    new ContainsFilter(readerFormatNamesMethod,
                                                       formatName),
                                                true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageReaderIterator(iter);
    }

    
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode files with the given suffix. 
Params:
  • fileSuffix – a String containing a file suffix (e.g., "jpg" or "tiff").
Throws:
See Also:
Returns:an Iterator containing ImageReaders.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageReader}s that claim to be able to
     * decode files with the given suffix.
     *
     * @param fileSuffix a {@code String} containing a file
     * suffix (<i>e.g.</i>, "jpg" or "tiff").
     *
     * @return an {@code Iterator} containing
     * {@code ImageReader}s.
     *
     * @exception IllegalArgumentException if {@code fileSuffix}
     * is {@code null}.
     *
     * @see javax.imageio.spi.ImageReaderSpi#getFileSuffixes
     */
    public static Iterator<ImageReader>
        getImageReadersBySuffix(String fileSuffix)
    {
        if (fileSuffix == null) {
            throw new IllegalArgumentException("fileSuffix == null!");
        }
        // Ensure category is present
        Iterator<ImageReaderSpi> iter;
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                   new ContainsFilter(readerFileSuffixesMethod,
                                                      fileSuffix),
                                              true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageReaderIterator(iter);
    }

    
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode files with the given MIME type. 
Params:
  • MIMEType – a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").
Throws:
See Also:
Returns:an Iterator containing ImageReaders.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageReader}s that claim to be able to
     * decode files with the given MIME type.
     *
     * @param MIMEType a {@code String} containing a file
     * suffix (<i>e.g.</i>, "image/jpeg" or "image/x-bmp").
     *
     * @return an {@code Iterator} containing
     * {@code ImageReader}s.
     *
     * @exception IllegalArgumentException if {@code MIMEType} is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageReaderSpi#getMIMETypes
     */
    public static Iterator<ImageReader>
        getImageReadersByMIMEType(String MIMEType)
    {
        if (MIMEType == null) {
            throw new IllegalArgumentException("MIMEType == null!");
        }
        // Ensure category is present
        Iterator<ImageReaderSpi> iter;
        try {
            iter = theRegistry.getServiceProviders(ImageReaderSpi.class,
                                      new ContainsFilter(readerMIMETypesMethod,
                                                         MIMEType),
                                              true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageReaderIterator(iter);
    }

    // Writers

    
Returns an array of Strings listing all of the informal format names understood by the current set of registered writers. 
Returns:an array of Strings.
/**
     * Returns an array of {@code String}s listing all of the
     * informal format names understood by the current set of registered
     * writers.
     *
     * @return an array of {@code String}s.
     */
    public static String[] getWriterFormatNames() {
        return getReaderWriterInfo(ImageWriterSpi.class,
                                   SpiInfo.FORMAT_NAMES);
    }

    
Returns an array of Strings listing all of the MIME types understood by the current set of registered writers. 
Returns:an array of Strings.
/**
     * Returns an array of {@code String}s listing all of the
     * MIME types understood by the current set of registered
     * writers.
     *
     * @return an array of {@code String}s.
     */
    public static String[] getWriterMIMETypes() {
        return getReaderWriterInfo(ImageWriterSpi.class,
                                   SpiInfo.MIME_TYPES);
    }

    
Returns an array of Strings listing all of the file suffixes associated with the formats understood by the current set of registered writers. 
Returns:an array of Strings.
Since:1.6
/**
     * Returns an array of {@code String}s listing all of the
     * file suffixes associated with the formats understood
     * by the current set of registered writers.
     *
     * @return an array of {@code String}s.
     * @since 1.6
     */
    public static String[] getWriterFileSuffixes() {
        return getReaderWriterInfo(ImageWriterSpi.class,
                                   SpiInfo.FILE_SUFFIXES);
    }

    static class ImageWriterIterator implements Iterator<ImageWriter> {
        // Contains ImageWriterSpis
        private Iterator<ImageWriterSpi> iter;

        public ImageWriterIterator(Iterator<ImageWriterSpi> iter) {
            this.iter = iter;
        }

        public boolean hasNext() {
            return iter.hasNext();
        }

        public ImageWriter next() {
            ImageWriterSpi spi = null;
            try {
                spi = iter.next();
                return spi.createWriterInstance();
            } catch (IOException e) {
                // Deregister the spi in this case, but only as a writerSpi
                theRegistry.deregisterServiceProvider(spi, ImageWriterSpi.class);
            }
            return null;
        }

        public void remove() {
            throw new UnsupportedOperationException();
        }
    }

    private static boolean contains(String[] names, String name) {
        for (int i = 0; i < names.length; i++) {
            if (name.equalsIgnoreCase(names[i])) {
                return true;
            }
        }

        return false;
    }

    
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode the named format. 
Params:
  • formatName – a String containing the informal name of a format (e.g., "jpeg" or "tiff".
Throws:
See Also:
Returns:an Iterator containing ImageWriters.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageWriter}s that claim to be able to
     * encode the named format.
     *
     * @param formatName a {@code String} containing the informal
     * name of a format (<i>e.g.</i>, "jpeg" or "tiff".
     *
     * @return an {@code Iterator} containing
     * {@code ImageWriter}s.
     *
     * @exception IllegalArgumentException if {@code formatName} is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageWriterSpi#getFormatNames
     */
    public static Iterator<ImageWriter>
        getImageWritersByFormatName(String formatName)
    {
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        Iterator<ImageWriterSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                    new ContainsFilter(writerFormatNamesMethod,
                                                       formatName),
                                            true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageWriterIterator(iter);
    }

    
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode files with the given suffix. 
Params:
  • fileSuffix – a String containing a file suffix (e.g., "jpg" or "tiff").
Throws:
See Also:
Returns:an Iterator containing ImageWriters.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageWriter}s that claim to be able to
     * encode files with the given suffix.
     *
     * @param fileSuffix a {@code String} containing a file
     * suffix (<i>e.g.</i>, "jpg" or "tiff").
     *
     * @return an {@code Iterator} containing {@code ImageWriter}s.
     *
     * @exception IllegalArgumentException if {@code fileSuffix} is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageWriterSpi#getFileSuffixes
     */
    public static Iterator<ImageWriter>
        getImageWritersBySuffix(String fileSuffix)
    {
        if (fileSuffix == null) {
            throw new IllegalArgumentException("fileSuffix == null!");
        }
        Iterator<ImageWriterSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                   new ContainsFilter(writerFileSuffixesMethod,
                                                      fileSuffix),
                                            true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageWriterIterator(iter);
    }

    
Returns an Iterator containing all currently registered ImageWriters that claim to be able to encode files with the given MIME type. 
Params:
  • MIMEType – a String containing a file suffix (e.g., "image/jpeg" or "image/x-bmp").
Throws:
See Also:
Returns:an Iterator containing ImageWriters.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageWriter}s that claim to be able to
     * encode files with the given MIME type.
     *
     * @param MIMEType a {@code String} containing a file
     * suffix (<i>e.g.</i>, "image/jpeg" or "image/x-bmp").
     *
     * @return an {@code Iterator} containing {@code ImageWriter}s.
     *
     * @exception IllegalArgumentException if {@code MIMEType} is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageWriterSpi#getMIMETypes
     */
    public static Iterator<ImageWriter>
        getImageWritersByMIMEType(String MIMEType)
    {
        if (MIMEType == null) {
            throw new IllegalArgumentException("MIMEType == null!");
        }
        Iterator<ImageWriterSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageWriterSpi.class,
                                      new ContainsFilter(writerMIMETypesMethod,
                                                         MIMEType),
                                            true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageWriterIterator(iter);
    }

    
Returns an ImageWriter corresponding 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(). 
Params:
  • reader – an instance of a registered ImageReader.
Throws:
See Also:
Returns:an ImageWriter, or null.
/**
     * Returns an {@code ImageWriter} corresponding to the given
     * {@code ImageReader}, if there is one, or {@code null}
     * if the plug-in for this {@code ImageReader} does not
     * specify a corresponding {@code ImageWriter}, or if the
     * given {@code ImageReader} is not registered.  This
     * mechanism may be used to obtain an {@code ImageWriter}
     * that will understand the internal structure of non-pixel
     * metadata (as encoded by {@code IIOMetadata} objects)
     * generated by the {@code ImageReader}.  By obtaining this
     * data from the {@code ImageReader} and passing it on to the
     * {@code 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
     * {@code javax.imageio.spi.ImageReaderSpi.getImageWriterSpiNames()}.
     *
     * @param reader an instance of a registered {@code ImageReader}.
     *
     * @return an {@code ImageWriter}, or null.
     *
     * @exception IllegalArgumentException if {@code reader} is
     * {@code null}.
     *
     * @see #getImageReader(ImageWriter)
     * @see javax.imageio.spi.ImageReaderSpi#getImageWriterSpiNames()
     */
    public static ImageWriter getImageWriter(ImageReader reader) {
        if (reader == null) {
            throw new IllegalArgumentException("reader == null!");
        }

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

            while (readerSpiIter.hasNext()) {
                ImageReaderSpi temp = 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;
        }
    }

    
Returns an ImageReader corresponding 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(). 
Params:
  • writer – an instance of a registered ImageWriter.
Throws:
See Also:
Returns:an ImageReader, or null.
/**
     * Returns an {@code ImageReader} corresponding to the given
     * {@code ImageWriter}, if there is one, or {@code null}
     * if the plug-in for this {@code ImageWriter} does not
     * specify a corresponding {@code ImageReader}, or if the
     * given {@code ImageWriter} is not registered.  This method
     * is provided principally for symmetry with
     * {@code getImageWriter(ImageReader)}.  Note that this
     * method returns the "preferred" reader, which is the first in
     * the list returned by
     * javax.imageio.spi.ImageWriterSpi.{@code getImageReaderSpiNames()}.
     *
     * @param writer an instance of a registered {@code ImageWriter}.
     *
     * @return an {@code ImageReader}, or null.
     *
     * @exception IllegalArgumentException if {@code writer} is
     * {@code null}.
     *
     * @see #getImageWriter(ImageReader)
     * @see javax.imageio.spi.ImageWriterSpi#getImageReaderSpiNames()
     */
    public static ImageReader getImageReader(ImageWriter writer) {
        if (writer == null) {
            throw new IllegalArgumentException("writer == null!");
        }

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

            while (writerSpiIter.hasNext()) {
                ImageWriterSpi temp = 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;
        }
    }

    
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. 
Params:
  • type – an ImageTypeSpecifier indicating the layout of the image to be written.
  • formatName – the informal name of the format.
Throws:
See Also:
Returns:an Iterator containing ImageWriters.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageWriter}s that claim to be able to
     * encode images of the given layout (specified using an
     * {@code ImageTypeSpecifier}) in the given format.
     *
     * @param type an {@code ImageTypeSpecifier} indicating the
     * layout of the image to be written.
     * @param formatName the informal name of the {@code format}.
     *
     * @return an {@code Iterator} containing {@code ImageWriter}s.
     *
     * @exception IllegalArgumentException if any parameter is
     * {@code null}.
     *
     * @see javax.imageio.spi.ImageWriterSpi#canEncodeImage(ImageTypeSpecifier)
     */
    public static Iterator<ImageWriter>
        getImageWriters(ImageTypeSpecifier type, String formatName)
    {
        if (type == null) {
            throw new IllegalArgumentException("type == null!");
        }
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }

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

        return new ImageWriterIterator(iter);
    }

    static class ImageTranscoderIterator
        implements Iterator<ImageTranscoder>
    {
        // Contains ImageTranscoderSpis
        public Iterator<ImageTranscoderSpi> iter;

        public ImageTranscoderIterator(Iterator<ImageTranscoderSpi> iter) {
            this.iter = iter;
        }

        public boolean hasNext() {
            return iter.hasNext();
        }

        public ImageTranscoder next() {
            ImageTranscoderSpi spi = null;
            spi = iter.next();
            return spi.createTranscoderInstance();
        }

        public void remove() {
            throw new UnsupportedOperationException();
        }
    }

    static class TranscoderFilter
        implements ServiceRegistry.Filter {

        String readerSpiName;
        String writerSpiName;

        public TranscoderFilter(ImageReaderSpi readerSpi,
                                ImageWriterSpi writerSpi) {
            this.readerSpiName = readerSpi.getClass().getName();
            this.writerSpiName = writerSpi.getClass().getName();
        }

        public boolean filter(Object elt) {
            ImageTranscoderSpi spi = (ImageTranscoderSpi)elt;
            String readerName = spi.getReaderServiceProviderName();
            String writerName = spi.getWriterServiceProviderName();
            return (readerName.equals(readerSpiName) &&
                    writerName.equals(writerSpiName));
        }
    }

    
Returns an Iterator containing all currently registered ImageTranscoders that claim to be able to transcode between the metadata of the given ImageReader and ImageWriter. 
Params:
  • reader – an ImageReader.
  • writer – an ImageWriter.
Throws:
Returns:an Iterator containing ImageTranscoders.
/**
     * Returns an {@code Iterator} containing all currently
     * registered {@code ImageTranscoder}s that claim to be
     * able to transcode between the metadata of the given
     * {@code ImageReader} and {@code ImageWriter}.
     *
     * @param reader an {@code ImageReader}.
     * @param writer an {@code ImageWriter}.
     *
     * @return an {@code Iterator} containing
     * {@code ImageTranscoder}s.
     *
     * @exception IllegalArgumentException if {@code reader} or
     * {@code writer} is {@code null}.
     */
    public static Iterator<ImageTranscoder>
        getImageTranscoders(ImageReader reader, ImageWriter writer)
    {
        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<ImageTranscoderSpi> iter;
        // Ensure category is present
        try {
            iter = theRegistry.getServiceProviders(ImageTranscoderSpi.class,
                                            filter, true);
        } catch (IllegalArgumentException e) {
            return Collections.emptyIterator();
        }
        return new ImageTranscoderIterator(iter);
    }

    // All-in-one methods

    
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 getUseCache and 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 method does not attempt to locate ImageReaders that can read directly from a File; that may be accomplished using IIORegistry and ImageReaderSpi. 
Params:
  • input – a File to read from.
Throws:
Returns:a BufferedImage containing the decoded contents of the input, or null.
/**
     * Returns a {@code BufferedImage} as the result of decoding
     * a supplied {@code File} with an {@code ImageReader}
     * chosen automatically from among those currently registered.
     * The {@code File} is wrapped in an
     * {@code ImageInputStream}.  If no registered
     * {@code ImageReader} claims to be able to read the
     * resulting stream, {@code null} is returned.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching in the
     * {@code ImageInputStream} that is created.
     *
     * <p> Note that there is no {@code read} method that takes a
     * filename as a {@code String}; use this method instead after
     * creating a {@code File} from the filename.
     *
     * <p> This method does not attempt to locate
     * {@code ImageReader}s that can read directly from a
     * {@code File}; that may be accomplished using
     * {@code IIORegistry} and {@code ImageReaderSpi}.
     *
     * @param input a {@code File} to read from.
     *
     * @return a {@code BufferedImage} containing the decoded
     * contents of the input, or {@code null}.
     *
     * @exception IllegalArgumentException if {@code input} is
     * {@code null}.
     * @exception IOException if an error occurs during reading or when not
     * able to create required ImageInputStream.
     */
    public static BufferedImage read(File input) throws IOException {
        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!");
        }
        BufferedImage bi = read(stream);
        if (bi == null) {
            stream.close();
        }
        return bi;
    }

    
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 getUseCache and getCacheDirectory will be used to control caching in the ImageInputStream that is created. 
 This method does not attempt to locate ImageReaders that can read directly from an InputStream; that may be accomplished using IIORegistry and ImageReaderSpi. 
 This method does not close the provided InputStream after the read operation has completed; it is the responsibility of the caller to close the stream, if desired. 
Params:
  • input – an InputStream to read from.
Throws:
Returns:a BufferedImage containing the decoded contents of the input, or null.
/**
     * Returns a {@code BufferedImage} as the result of decoding
     * a supplied {@code InputStream} with an {@code ImageReader}
     * chosen automatically from among those currently registered.
     * The {@code InputStream} is wrapped in an
     * {@code ImageInputStream}.  If no registered
     * {@code ImageReader} claims to be able to read the
     * resulting stream, {@code null} is returned.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching in the
     * {@code ImageInputStream} that is created.
     *
     * <p> This method does not attempt to locate
     * {@code ImageReader}s that can read directly from an
     * {@code InputStream}; that may be accomplished using
     * {@code IIORegistry} and {@code ImageReaderSpi}.
     *
     * <p> This method <em>does not</em> close the provided
     * {@code InputStream} after the read operation has completed;
     * it is the responsibility of the caller to close the stream, if desired.
     *
     * @param input an {@code InputStream} to read from.
     *
     * @return a {@code BufferedImage} containing the decoded
     * contents of the input, or {@code null}.
     *
     * @exception IllegalArgumentException if {@code input} is
     * {@code null}.
     * @exception IOException if an error occurs during reading or when not
     * able to create required ImageInputStream.
     */
    public static BufferedImage read(InputStream input) throws IOException {
        if (input == null) {
            throw new IllegalArgumentException("input == null!");
        }

        ImageInputStream stream = createImageInputStream(input);
        if (stream == null) {
            throw new IIOException("Can't create an ImageInputStream!");
        }
        BufferedImage bi = read(stream);
        if (bi == null) {
            stream.close();
        }
        return bi;
    }

    
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 getUseCache and getCacheDirectory will be used to control caching in the ImageInputStream that is created. 
 This method does not attempt to locate ImageReaders that can read directly from a URL; that may be accomplished using IIORegistry and ImageReaderSpi. 
Params:
  • input – a URL to read from.
Throws:
Returns:a BufferedImage containing the decoded contents of the input, or null.
/**
     * Returns a {@code BufferedImage} as the result of decoding
     * a supplied {@code URL} with an {@code ImageReader}
     * chosen automatically from among those currently registered.  An
     * {@code InputStream} is obtained from the {@code URL},
     * which is wrapped in an {@code ImageInputStream}.  If no
     * registered {@code ImageReader} claims to be able to read
     * the resulting stream, {@code null} is returned.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching in the
     * {@code ImageInputStream} that is created.
     *
     * <p> This method does not attempt to locate
     * {@code ImageReader}s that can read directly from a
     * {@code URL}; that may be accomplished using
     * {@code IIORegistry} and {@code ImageReaderSpi}.
     *
     * @param input a {@code URL} to read from.
     *
     * @return a {@code BufferedImage} containing the decoded
     * contents of the input, or {@code null}.
     *
     * @exception IllegalArgumentException if {@code input} is
     * {@code null}.
     * @exception IOException if an error occurs during reading or when not
     * able to create required ImageInputStream.
     */
    public static BufferedImage read(URL input) throws IOException {
        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);
        if (stream == null) {
            /* close the istream when stream is null so that if user has
             * given filepath as URL he can delete it, otherwise stream will
             * be open to that file and he will not be able to delete it.
             */
            istream.close();
            throw new IIOException("Can't create an ImageInputStream!");
        }
        BufferedImage bi;
        try {
            bi = read(stream);
            if (bi == null) {
                stream.close();
            }
        } finally {
            istream.close();
        }
        return bi;
    }

    
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. 
 Unlike most other methods in this class, this method does close the provided ImageInputStream after the read operation has completed, unless null is returned, in which case this method does not close the stream.

Params:
  • stream – an ImageInputStream to read from.
Throws:
Returns:a BufferedImage containing the decoded contents of the input, or null.
/**
     * Returns a {@code BufferedImage} as the result of decoding
     * a supplied {@code ImageInputStream} with an
     * {@code ImageReader} chosen automatically from among those
     * currently registered.  If no registered
     * {@code ImageReader} claims to be able to read the stream,
     * {@code null} is returned.
     *
     * <p> Unlike most other methods in this class, this method <em>does</em>
     * close the provided {@code ImageInputStream} after the read
     * operation has completed, unless {@code null} is returned,
     * in which case this method <em>does not</em> close the stream.
     *
     * @param stream an {@code ImageInputStream} to read from.
     *
     * @return a {@code BufferedImage} containing the decoded
     * contents of the input, or {@code null}.
     *
     * @exception IllegalArgumentException if {@code stream} is
     * {@code null}.
     * @exception IOException if an error occurs during reading.
     */
    public static BufferedImage read(ImageInputStream stream)
        throws IOException {
        if (stream == null) {
            throw new IllegalArgumentException("stream == null!");
        }

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

        ImageReader reader = iter.next();
        ImageReadParam param = reader.getDefaultReadParam();
        reader.setInput(stream, true, true);
        BufferedImage bi;
        try {
            bi = reader.read(0, param);
        } finally {
            reader.dispose();
            stream.close();
        }
        return bi;
    }

    
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. 
 This method does not close the provided ImageOutputStream after the write operation has completed; it is the responsibility of the caller to close the stream, if desired. 
Params:
  • im – a RenderedImage to be written.
  • formatName – a String containing the informal name of the format.
  • output – an ImageOutputStream to be written to.
Throws:
Returns:false if no appropriate writer is found.
/**
     * Writes an image using the an arbitrary {@code ImageWriter}
     * that supports the given format to an
     * {@code ImageOutputStream}.  The image is written to the
     * {@code ImageOutputStream} starting at the current stream
     * pointer, overwriting existing stream data from that point
     * forward, if present.
     *
     * <p> This method <em>does not</em> close the provided
     * {@code ImageOutputStream} after the write operation has completed;
     * it is the responsibility of the caller to close the stream, if desired.
     *
     * @param im a {@code RenderedImage} to be written.
     * @param formatName a {@code String} containing the informal
     * name of the format.
     * @param output an {@code ImageOutputStream} to be written to.
     *
     * @return {@code false} if no appropriate writer is found.
     *
     * @exception IllegalArgumentException if any parameter is
     * {@code null}.
     * @exception IOException if an error occurs during writing.
     */
    public static boolean write(RenderedImage im,
                                String formatName,
                                ImageOutputStream output) throws IOException {
        if (im == null) {
            throw new IllegalArgumentException("im == null!");
        }
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }

        return doWrite(im, getWriter(im, formatName), 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. 
Params:
  • im – a RenderedImage to be written.
  • formatName – a String containing the informal name of the format.
  • output – a File to be written to.
Throws:
Returns:false if no appropriate writer is found.
/**
     * Writes an image using an arbitrary {@code ImageWriter}
     * that supports the given format to a {@code File}.  If
     * there is already a {@code File} present, its contents are
     * discarded.
     *
     * @param im a {@code RenderedImage} to be written.
     * @param formatName a {@code String} containing the informal
     * name of the format.
     * @param output a {@code File} to be written to.
     *
     * @return {@code false} if no appropriate writer is found.
     *
     * @exception IllegalArgumentException if any parameter is
     * {@code null}.
     * @exception IOException if an error occurs during writing or when not
     * able to create required ImageOutputStream.
     */
    public static boolean write(RenderedImage im,
                                String formatName,
                                File output) throws IOException {
        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }

        ImageWriter writer = getWriter(im, formatName);
        if (writer == null) {
            /* Do not make changes in the file system if we have
             * no appropriate writer.
             */
            return false;
        }

        output.delete();
        ImageOutputStream stream = createImageOutputStream(output);
        if (stream == null) {
            throw new IIOException("Can't create an ImageOutputStream!");
        }
        try {
            return doWrite(im, writer, stream);
        } finally {
            stream.close();
        }
    }

    
Writes an image using an arbitrary ImageWriter that supports the given format to an OutputStream. 
 This method does not close the provided OutputStream after the write operation has completed; it is the responsibility of the caller to close the stream, if desired. 
 The current cache settings from getUseCache and getCacheDirectory will be used to control caching. 
Params:
  • im – a RenderedImage to be written.
  • formatName – a String containing the informal name of the format.
  • output – an OutputStream to be written to.
Throws:
Returns:false if no appropriate writer is found.
/**
     * Writes an image using an arbitrary {@code ImageWriter}
     * that supports the given format to an {@code OutputStream}.
     *
     * <p> This method <em>does not</em> close the provided
     * {@code OutputStream} after the write operation has completed;
     * it is the responsibility of the caller to close the stream, if desired.
     *
     * <p> The current cache settings from {@code getUseCache} and
     * {@code getCacheDirectory} will be used to control caching.
     *
     * @param im a {@code RenderedImage} to be written.
     * @param formatName a {@code String} containing the informal
     * name of the format.
     * @param output an {@code OutputStream} to be written to.
     *
     * @return {@code false} if no appropriate writer is found.
     *
     * @exception IllegalArgumentException if any parameter is
     * {@code null}.
     * @exception IOException if an error occurs during writing or when not
     * able to create required ImageOutputStream.
     */
    public static boolean write(RenderedImage im,
                                String formatName,
                                OutputStream output) throws IOException {
        if (output == null) {
            throw new IllegalArgumentException("output == null!");
        }
        ImageOutputStream stream = createImageOutputStream(output);
        if (stream == null) {
            throw new IIOException("Can't create an ImageOutputStream!");
        }
        try {
            return doWrite(im, getWriter(im, formatName), stream);
        } finally {
            stream.close();
        }
    }

    
Returns ImageWriter instance according to given rendered image and image format or null if there is no appropriate writer. 
/**
     * Returns {@code ImageWriter} instance according to given
     * rendered image and image format or {@code null} if there
     * is no appropriate writer.
     */
    private static ImageWriter getWriter(RenderedImage im,
                                         String formatName) {
        ImageTypeSpecifier type =
            ImageTypeSpecifier.createFromRenderedImage(im);
        Iterator<ImageWriter> iter = getImageWriters(type, formatName);

        if (iter.hasNext()) {
            return iter.next();
        } else {
            return null;
        }
    }

    
Writes image to output stream  using given image writer.

/**
     * Writes image to output stream  using given image writer.
     */
    private static boolean doWrite(RenderedImage im, ImageWriter writer,
                                 ImageOutputStream output) throws IOException {
        if (writer == null) {
            return false;
        }
        writer.setOutput(output);
        try {
            writer.write(im);
        } finally {
            writer.dispose();
            output.flush();
        }
        return true;
    }
}