/*
 * Copyright (c) 1999, 2004, 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.Point;
import java.awt.Rectangle;
import java.awt.image.BufferedImage;
import java.awt.image.Raster;
import java.awt.image.RenderedImage;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
import java.util.Set;
import javax.imageio.spi.ImageReaderSpi;
import javax.imageio.event.IIOReadWarningListener;
import javax.imageio.event.IIOReadProgressListener;
import javax.imageio.event.IIOReadUpdateListener;
import javax.imageio.metadata.IIOMetadata;
import javax.imageio.metadata.IIOMetadataFormatImpl;
import javax.imageio.stream.ImageInputStream;

An abstract superclass for parsing and decoding of images.  This
class must be subclassed by classes that read in images in the
context of the Java Image I/O framework.
 ImageReader objects are normally instantiated by
the service provider interface (SPI) class for the specific format.
Service provider classes (e.g., instances of
ImageReaderSpi) are registered with the
IIORegistry, which uses them for format recognition
and presentation of available format readers and writers.
 When an input source is set (using the setInput
method), it may be marked as "seek forward only".  This setting
means that images contained within the input source will only be
read in order, possibly allowing the reader to avoid caching
portions of the input containing data associated with images that
have been read previously.
See Also:
ImageWriter
IIORegistry
ImageReaderSpi/**
 * An abstract superclass for parsing and decoding of images.  This
 * class must be subclassed by classes that read in images in the
 * context of the Java Image I/O framework.
 *
 * <p> <code>ImageReader</code> objects are normally instantiated by
 * the service provider interface (SPI) class for the specific format.
 * Service provider classes (e.g., instances of
 * <code>ImageReaderSpi</code>) are registered with the
 * <code>IIORegistry</code>, which uses them for format recognition
 * and presentation of available format readers and writers.
 *
 * <p> When an input source is set (using the <code>setInput</code>
 * method), it may be marked as "seek forward only".  This setting
 * means that images contained within the input source will only be
 * read in order, possibly allowing the reader to avoid caching
 * portions of the input containing data associated with images that
 * have been read previously.
 *
 * @see ImageWriter
 * @see javax.imageio.spi.IIORegistry
 * @see javax.imageio.spi.ImageReaderSpi
 *
 */
public abstract class ImageReader {

    
The ImageReaderSpi that instantiated this object,
or null if its identity is not known or none
exists.  By default it is initialized to null.
/**
     * The <code>ImageReaderSpi</code> that instantiated this object,
     * or <code>null</code> if its identity is not known or none
     * exists.  By default it is initialized to <code>null</code>.
     */
    protected ImageReaderSpi originatingProvider;

    
The ImageInputStream or other
Object by setInput and retrieved
by getInput.  By default it is initialized to
null.
/**
     * The <code>ImageInputStream</code> or other
     * <code>Object</code> by <code>setInput</code> and retrieved
     * by <code>getInput</code>.  By default it is initialized to
     * <code>null</code>.
     */
    protected Object input = null;

    
true if the current input source has been marked
as allowing only forward seeking by setInput.  By
default, the value is false.
See Also:
minIndex
setInput/**
     * <code>true</code> if the current input source has been marked
     * as allowing only forward seeking by <code>setInput</code>.  By
     * default, the value is <code>false</code>.
     *
     * @see #minIndex
     * @see #setInput
     */
    protected boolean seekForwardOnly = false;

    
true if the current input source has been marked
as allowing metadata to be ignored by setInput.
By default, the value is false.
See Also:
setInput/**
     * <code>true</code> if the current input source has been marked
     * as allowing metadata to be ignored by <code>setInput</code>.
     * By default, the value is <code>false</code>.
     *
     * @see #setInput
     */
    protected boolean ignoreMetadata = false;

    
The smallest valid index for reading, initially 0.  When
seekForwardOnly is true, various methods
may throw an IndexOutOfBoundsException on an
attempt to access data associate with an image having a lower
index.
See Also:
seekForwardOnly
setInput/**
     * The smallest valid index for reading, initially 0.  When
     * <code>seekForwardOnly</code> is <code>true</code>, various methods
     * may throw an <code>IndexOutOfBoundsException</code> on an
     * attempt to access data associate with an image having a lower
     * index.
     *
     * @see #seekForwardOnly
     * @see #setInput
     */
    protected int minIndex = 0;

    
An array of Locales which may be used to localize
warning messages, or null if localization is not
supported.
/**
     * An array of <code>Locale</code>s which may be used to localize
     * warning messages, or <code>null</code> if localization is not
     * supported.
     */
    protected Locale[] availableLocales = null;

    
The current Locale to be used for localization, or
null if none has been set.
/**
     * The current <code>Locale</code> to be used for localization, or
     * <code>null</code> if none has been set.
     */
    protected Locale locale = null;

    
A List of currently registered
IIOReadWarningListeners, initialized by default to
null, which is synonymous with an empty
List.
/**
     * A <code>List</code> of currently registered
     * <code>IIOReadWarningListener</code>s, initialized by default to
     * <code>null</code>, which is synonymous with an empty
     * <code>List</code>.
     */
    protected List<IIOReadWarningListener> warningListeners = null;

    
A List of the Locales associated with
each currently registered IIOReadWarningListener,
initialized by default to null, which is
synonymous with an empty List.
/**
     * A <code>List</code> of the <code>Locale</code>s associated with
     * each currently registered <code>IIOReadWarningListener</code>,
     * initialized by default to <code>null</code>, which is
     * synonymous with an empty <code>List</code>.
     */
    protected List<Locale> warningLocales = null;

    
A List of currently registered
IIOReadProgressListeners, initialized by default
to null, which is synonymous with an empty
List.
/**
     * A <code>List</code> of currently registered
     * <code>IIOReadProgressListener</code>s, initialized by default
     * to <code>null</code>, which is synonymous with an empty
     * <code>List</code>.
     */
    protected List<IIOReadProgressListener> progressListeners = null;

    
A List of currently registered
IIOReadUpdateListeners, initialized by default to
null, which is synonymous with an empty
List.
/**
     * A <code>List</code> of currently registered
     * <code>IIOReadUpdateListener</code>s, initialized by default to
     * <code>null</code>, which is synonymous with an empty
     * <code>List</code>.
     */
    protected List<IIOReadUpdateListener> updateListeners = null;

    
If true, the current read operation should be
aborted.
/**
     * If <code>true</code>, the current read operation should be
     * aborted.
     */
    private boolean abortFlag = false;

    
Constructs an ImageReader and sets its
originatingProvider field to the supplied value.
 Subclasses that make use of extensions should provide a
constructor with signature (ImageReaderSpi,
Object) in order to retrieve the extension object.  If
the extension object is unsuitable, an
IllegalArgumentException should be thrown.
Params:
originatingProvider – the ImageReaderSpi that is
invoking this constructor, or null./**
     * Constructs an <code>ImageReader</code> and sets its
     * <code>originatingProvider</code> field to the supplied value.
     *
     * <p> Subclasses that make use of extensions should provide a
     * constructor with signature <code>(ImageReaderSpi,
     * Object)</code> in order to retrieve the extension object.  If
     * the extension object is unsuitable, an
     * <code>IllegalArgumentException</code> should be thrown.
     *
     * @param originatingProvider the <code>ImageReaderSpi</code> that is
     * invoking this constructor, or <code>null</code>.
     */
    protected ImageReader(ImageReaderSpi originatingProvider) {
        this.originatingProvider = originatingProvider;
    }

    
Returns a String identifying the format of the
input source.
 The default implementation returns
originatingProvider.getFormatNames()[0].
Implementations that may not have an originating service
provider, or which desire a different naming policy should
override this method.
Throws:
IOException – if an error occurs reading the
information from the input source.
Returns:
the format name, as a String./**
     * Returns a <code>String</code> identifying the format of the
     * input source.
     *
     * <p> The default implementation returns
     * <code>originatingProvider.getFormatNames()[0]</code>.
     * Implementations that may not have an originating service
     * provider, or which desire a different naming policy should
     * override this method.
     *
     * @exception IOException if an error occurs reading the
     * information from the input source.
     *
     * @return the format name, as a <code>String</code>.
     */
    public String getFormatName() throws IOException {
        return originatingProvider.getFormatNames()[0];
    }

    
Returns the ImageReaderSpi that was passed in on
the constructor.  Note that this value may be null.
See Also:
ImageReaderSpi
Returns:
an ImageReaderSpi, or null./**
     * Returns the <code>ImageReaderSpi</code> that was passed in on
     * the constructor.  Note that this value may be <code>null</code>.
     *
     * @return an <code>ImageReaderSpi</code>, or <code>null</code>.
     *
     * @see ImageReaderSpi
     */
    public ImageReaderSpi getOriginatingProvider() {
        return originatingProvider;
    }

    
Sets the input source to use to the given
ImageInputStream or other Object.
The input source must be set before any of the query or read
methods are used.  If input is null,
any currently set input source will be removed.  In any case,
the value of minIndex will be initialized to 0.
 The seekForwardOnly parameter controls whether
the value returned by getMinIndex will be
increased as each image (or thumbnail, or image metadata) is
read.  If seekForwardOnly is true, then a call to
read(index) will throw an
IndexOutOfBoundsException if index <
this.minIndex; otherwise, the value of
minIndex will be set to index.  If
seekForwardOnly is false, the value of
minIndex will remain 0 regardless of any read
operations.
 The ignoreMetadata parameter, if set to
true, allows the reader to disregard any metadata
encountered during the read.  Subsequent calls to the
getStreamMetadata and
getImageMetadata methods may return
null, and an IIOImage returned from
readAll may return null from their
getMetadata method.  Setting this parameter may
allow the reader to work more efficiently.  The reader may
choose to disregard this setting and return metadata normally.
 Subclasses should take care to remove any cached
information based on the previous stream, such as header
information or partially decoded image data.
 Use of a general Object other than an
ImageInputStream is intended for readers that
interact directly with a capture device or imaging protocol.
The set of legal classes is advertised by the reader's service
provider's getInputTypes method; most readers
will return a single-element array containing only
ImageInputStream.class to indicate that they
accept only an ImageInputStream.
 The default implementation checks the input
argument against the list returned by
originatingProvider.getInputTypes() and fails
if the argument is not an instance of one of the classes
in the list.  If the originating provider is set to
null, the input is accepted only if it is an
ImageInputStream.
Params:
input – the ImageInputStream or other
Object to use for future decoding.
seekForwardOnly – if true, images and metadata
may only be read in ascending order from this input source.
ignoreMetadata – if true, metadata
may be ignored during reads.
Throws:
IllegalArgumentException – if input is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream.
See Also:
ImageInputStream
getInput
ImageReaderSpi.getInputTypes/**
     * Sets the input source to use to the given
     * <code>ImageInputStream</code> or other <code>Object</code>.
     * The input source must be set before any of the query or read
     * methods are used.  If <code>input</code> is <code>null</code>,
     * any currently set input source will be removed.  In any case,
     * the value of <code>minIndex</code> will be initialized to 0.
     *
     * <p> The <code>seekForwardOnly</code> parameter controls whether
     * the value returned by <code>getMinIndex</code> will be
     * increased as each image (or thumbnail, or image metadata) is
     * read.  If <code>seekForwardOnly</code> is true, then a call to
     * <code>read(index)</code> will throw an
     * <code>IndexOutOfBoundsException</code> if <code>index &lt
     * this.minIndex</code>; otherwise, the value of
     * <code>minIndex</code> will be set to <code>index</code>.  If
     * <code>seekForwardOnly</code> is <code>false</code>, the value of
     * <code>minIndex</code> will remain 0 regardless of any read
     * operations.
     *
     * <p> The <code>ignoreMetadata</code> parameter, if set to
     * <code>true</code>, allows the reader to disregard any metadata
     * encountered during the read.  Subsequent calls to the
     * <code>getStreamMetadata</code> and
     * <code>getImageMetadata</code> methods may return
     * <code>null</code>, and an <code>IIOImage</code> returned from
     * <code>readAll</code> may return <code>null</code> from their
     * <code>getMetadata</code> method.  Setting this parameter may
     * allow the reader to work more efficiently.  The reader may
     * choose to disregard this setting and return metadata normally.
     *
     * <p> Subclasses should take care to remove any cached
     * information based on the previous stream, such as header
     * information or partially decoded image data.
     *
     * <p> Use of a general <code>Object</code> other than an
     * <code>ImageInputStream</code> is intended for readers that
     * interact directly with a capture device or imaging protocol.
     * The set of legal classes is advertised by the reader's service
     * provider's <code>getInputTypes</code> method; most readers
     * will return a single-element array containing only
     * <code>ImageInputStream.class</code> to indicate that they
     * accept only an <code>ImageInputStream</code>.
     *
     * <p> The default implementation checks the <code>input</code>
     * argument against the list returned by
     * <code>originatingProvider.getInputTypes()</code> and fails
     * if the argument is not an instance of one of the classes
     * in the list.  If the originating provider is set to
     * <code>null</code>, the input is accepted only if it is an
     * <code>ImageInputStream</code>.
     *
     * @param input the <code>ImageInputStream</code> or other
     * <code>Object</code> to use for future decoding.
     * @param seekForwardOnly if <code>true</code>, images and metadata
     * may only be read in ascending order from this input source.
     * @param ignoreMetadata if <code>true</code>, metadata
     * may be ignored during reads.
     *
     * @exception IllegalArgumentException if <code>input</code> is
     * not an instance of one of the classes returned by the
     * originating service provider's <code>getInputTypes</code>
     * method, or is not an <code>ImageInputStream</code>.
     *
     * @see ImageInputStream
     * @see #getInput
     * @see javax.imageio.spi.ImageReaderSpi#getInputTypes
     */
    public void setInput(Object input,
                         boolean seekForwardOnly,
                         boolean ignoreMetadata) {
        if (input != null) {
            boolean found = false;
            if (originatingProvider != null) {
                Class[] classes = originatingProvider.getInputTypes();
                for (int i = 0; i < classes.length; i++) {
                    if (classes[i].isInstance(input)) {
                        found = true;
                        break;
                    }
                }
            } else {
                if (input instanceof ImageInputStream) {
                    found = true;
                }
            }
            if (!found) {
                throw new IllegalArgumentException("Incorrect input type!");
            }

            this.seekForwardOnly = seekForwardOnly;
            this.ignoreMetadata = ignoreMetadata;
            this.minIndex = 0;
        }

        this.input = input;
    }

    
Sets the input source to use to the given
ImageInputStream or other Object.
The input source must be set before any of the query or read
methods are used.  If input is null,
any currently set input source will be removed.  In any case,
the value of minIndex will be initialized to 0.
 The seekForwardOnly parameter controls whether
the value returned by getMinIndex will be
increased as each image (or thumbnail, or image metadata) is
read.  If seekForwardOnly is true, then a call to
read(index) will throw an
IndexOutOfBoundsException if index <
this.minIndex; otherwise, the value of
minIndex will be set to index.  If
seekForwardOnly is false, the value of
minIndex will remain 0 regardless of any read
operations.
 This method is equivalent to setInput(input,
seekForwardOnly, false).
Params:
input – the ImageInputStream or other
Object to use for future decoding.
seekForwardOnly – if true, images and metadata
may only be read in ascending order from this input source.
Throws:
IllegalArgumentException – if input is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream.
See Also:
getInput/**
     * Sets the input source to use to the given
     * <code>ImageInputStream</code> or other <code>Object</code>.
     * The input source must be set before any of the query or read
     * methods are used.  If <code>input</code> is <code>null</code>,
     * any currently set input source will be removed.  In any case,
     * the value of <code>minIndex</code> will be initialized to 0.
     *
     * <p> The <code>seekForwardOnly</code> parameter controls whether
     * the value returned by <code>getMinIndex</code> will be
     * increased as each image (or thumbnail, or image metadata) is
     * read.  If <code>seekForwardOnly</code> is true, then a call to
     * <code>read(index)</code> will throw an
     * <code>IndexOutOfBoundsException</code> if <code>index &lt
     * this.minIndex</code>; otherwise, the value of
     * <code>minIndex</code> will be set to <code>index</code>.  If
     * <code>seekForwardOnly</code> is <code>false</code>, the value of
     * <code>minIndex</code> will remain 0 regardless of any read
     * operations.
     *
     * <p> This method is equivalent to <code>setInput(input,
     * seekForwardOnly, false)</code>.
     *
     * @param input the <code>ImageInputStream</code> or other
     * <code>Object</code> to use for future decoding.
     * @param seekForwardOnly if <code>true</code>, images and metadata
     * may only be read in ascending order from this input source.
     *
     * @exception IllegalArgumentException if <code>input</code> is
     * not an instance of one of the classes returned by the
     * originating service provider's <code>getInputTypes</code>
     * method, or is not an <code>ImageInputStream</code>.
     *
     * @see #getInput
     */
    public void setInput(Object input,
                         boolean seekForwardOnly) {
        setInput(input, seekForwardOnly, false);
    }

    
Sets the input source to use to the given
ImageInputStream or other Object.
The input source must be set before any of the query or read
methods are used.  If input is null,
any currently set input source will be removed.  In any case,
the value of minIndex will be initialized to 0.
 This method is equivalent to setInput(input, false,
false).
Params:
input – the ImageInputStream or other
Object to use for future decoding.
Throws:
IllegalArgumentException – if input is
not an instance of one of the classes returned by the
originating service provider's getInputTypes
method, or is not an ImageInputStream.
See Also:
getInput/**
     * Sets the input source to use to the given
     * <code>ImageInputStream</code> or other <code>Object</code>.
     * The input source must be set before any of the query or read
     * methods are used.  If <code>input</code> is <code>null</code>,
     * any currently set input source will be removed.  In any case,
     * the value of <code>minIndex</code> will be initialized to 0.
     *
     * <p> This method is equivalent to <code>setInput(input, false,
     * false)</code>.
     *
     * @param input the <code>ImageInputStream</code> or other
     * <code>Object</code> to use for future decoding.
     *
     * @exception IllegalArgumentException if <code>input</code> is
     * not an instance of one of the classes returned by the
     * originating service provider's <code>getInputTypes</code>
     * method, or is not an <code>ImageInputStream</code>.
     *
     * @see #getInput
     */
    public void setInput(Object input) {
        setInput(input, false, false);
    }

    
Returns the ImageInputStream or other
Object previously set as the input source.  If the
input source has not been set, null is returned.
See Also:
ImageInputStream
setInput
Returns:
the Object that will be used for future
decoding, or null./**
     * Returns the <code>ImageInputStream</code> or other
     * <code>Object</code> previously set as the input source.  If the
     * input source has not been set, <code>null</code> is returned.
     *
     * @return the <code>Object</code> that will be used for future
     * decoding, or <code>null</code>.
     *
     * @see ImageInputStream
     * @see #setInput
     */
    public Object getInput() {
        return input;
    }

    
Returns true if the current input source has been
marked as seek forward only by passing true as the
seekForwardOnly argument to the
setInput method.
See Also:
setInput
Returns:
true if the input source is seek forward
only./**
     * Returns <code>true</code> if the current input source has been
     * marked as seek forward only by passing <code>true</code> as the
     * <code>seekForwardOnly</code> argument to the
     * <code>setInput</code> method.
     *
     * @return <code>true</code> if the input source is seek forward
     * only.
     *
     * @see #setInput
     */
    public boolean isSeekForwardOnly() {
        return seekForwardOnly;
    }

    
Returns true if the current input source has been
marked as allowing metadata to be ignored by passing
true as the ignoreMetadata argument
to the setInput method.
See Also:
setInput
Returns:
true if the metadata may be ignored./**
     * Returns <code>true</code> if the current input source has been
     * marked as allowing metadata to be ignored by passing
     * <code>true</code> as the <code>ignoreMetadata</code> argument
     * to the <code>setInput</code> method.
     *
     * @return <code>true</code> if the metadata may be ignored.
     *
     * @see #setInput
     */
    public boolean isIgnoringMetadata() {
        return ignoreMetadata;
    }

    
Returns the lowest valid index for reading an image, thumbnail,
or image metadata.  If seekForwardOnly() is
false, this value will typically remain 0,
indicating that random access is possible.  Otherwise, it will
contain the value of the most recently accessed index, and
increase in a monotonic fashion.
Returns:
the minimum legal index for reading./**
     * Returns the lowest valid index for reading an image, thumbnail,
     * or image metadata.  If <code>seekForwardOnly()</code> is
     * <code>false</code>, this value will typically remain 0,
     * indicating that random access is possible.  Otherwise, it will
     * contain the value of the most recently accessed index, and
     * increase in a monotonic fashion.
     *
     * @return the minimum legal index for reading.
     */
    public int getMinIndex() {
        return minIndex;
    }

    // Localization

    
Returns an array of Locales that may be used to
localize warning listeners and compression settings.  A return
value of null indicates that localization is not
supported.
 The default implementation returns a clone of the
availableLocales instance variable if it is
non-null, or else returns null.
Returns:
an array of Locales that may be used as
arguments to setLocale, or null./**
     * Returns an array of <code>Locale</code>s that may be used to
     * localize warning listeners and compression settings.  A return
     * value of <code>null</code> indicates that localization is not
     * supported.
     *
     * <p> The default implementation returns a clone of the
     * <code>availableLocales</code> instance variable if it is
     * non-<code>null</code>, or else returns <code>null</code>.
     *
     * @return an array of <code>Locale</code>s that may be used as
     * arguments to <code>setLocale</code>, or <code>null</code>.
     */
    public Locale[] getAvailableLocales() {
        if (availableLocales == null) {
            return null;
        } else {
            return (Locale[])availableLocales.clone();
        }
    }

    
Sets the current Locale of this
ImageReader to the given value.  A value of
null removes any previous setting, and indicates
that the reader should localize as it sees fit.
Params:
locale – the desired Locale, or
null.
Throws:
IllegalArgumentException – if locale is
non-null but is not one of the values returned by
getAvailableLocales.
See Also:
getLocale/**
     * Sets the current <code>Locale</code> of this
     * <code>ImageReader</code> to the given value.  A value of
     * <code>null</code> removes any previous setting, and indicates
     * that the reader should localize as it sees fit.
     *
     * @param locale the desired <code>Locale</code>, or
     * <code>null</code>.
     *
     * @exception IllegalArgumentException if <code>locale</code> is
     * non-<code>null</code> but is not one of the values returned by
     * <code>getAvailableLocales</code>.
     *
     * @see #getLocale
     */
    public void setLocale(Locale locale) {
        if (locale != null) {
            Locale[] locales = getAvailableLocales();
            boolean found = false;
            if (locales != null) {
                for (int i = 0; i < locales.length; i++) {
                    if (locale.equals(locales[i])) {
                        found = true;
                        break;
                    }
                }
            }
            if (!found) {
                throw new IllegalArgumentException("Invalid locale!");
            }
        }
        this.locale = locale;
    }

    
Returns the currently set Locale, or
null if none has been set.
See Also:
setLocale
Returns:
the current Locale, or null./**
     * Returns the currently set <code>Locale</code>, or
     * <code>null</code> if none has been set.
     *
     * @return the current <code>Locale</code>, or <code>null</code>.
     *
     * @see #setLocale
     */
    public Locale getLocale() {
        return locale;
    }

    // Image queries

    
Returns the number of images, not including thumbnails, available
from the current input source.
 Note that some image formats (such as animated GIF) do not
specify how many images are present in the stream.  Thus
determining the number of images will require the entire stream
to be scanned and may require memory for buffering.  If images
are to be processed in order, it may be more efficient to
simply call read with increasing indices until an
IndexOutOfBoundsException is thrown to indicate
that no more images are available.  The
allowSearch parameter may be set to
false to indicate that an exhaustive search is not
desired; the return value will be -1 to indicate
that a search is necessary.  If the input has been specified
with seekForwardOnly set to true,
this method throws an IllegalStateException if
allowSearch is set to true.
Params:
allowSearch – if true, the true number of
images will be returned even if a search is required.  If
false, the reader may return -1
without performing the search.
Throws:
IllegalStateException – if the input source has not been set,
or if the input has been specified with seekForwardOnly
set to true.
IOException – if an error occurs reading the
information from the input source.
See Also:
setInput
Returns:
the number of images, as an int, or
-1 if allowSearch is
false and a search would be required./**
     * Returns the number of images, not including thumbnails, available
     * from the current input source.
     *
     * <p> Note that some image formats (such as animated GIF) do not
     * specify how many images are present in the stream.  Thus
     * determining the number of images will require the entire stream
     * to be scanned and may require memory for buffering.  If images
     * are to be processed in order, it may be more efficient to
     * simply call <code>read</code> with increasing indices until an
     * <code>IndexOutOfBoundsException</code> is thrown to indicate
     * that no more images are available.  The
     * <code>allowSearch</code> parameter may be set to
     * <code>false</code> to indicate that an exhaustive search is not
     * desired; the return value will be <code>-1</code> to indicate
     * that a search is necessary.  If the input has been specified
     * with <code>seekForwardOnly</code> set to <code>true</code>,
     * this method throws an <code>IllegalStateException</code> if
     * <code>allowSearch</code> is set to <code>true</code>.
     *
     * @param allowSearch if <code>true</code>, the true number of
     * images will be returned even if a search is required.  If
     * <code>false</code>, the reader may return <code>-1</code>
     * without performing the search.
     *
     * @return the number of images, as an <code>int</code>, or
     * <code>-1</code> if <code>allowSearch</code> is
     * <code>false</code> and a search would be required.
     *
     * @exception IllegalStateException if the input source has not been set,
     * or if the input has been specified with <code>seekForwardOnly</code>
     * set to <code>true</code>.
     * @exception IOException if an error occurs reading the
     * information from the input source.
     *
     * @see #setInput
     */
    public abstract int getNumImages(boolean allowSearch) throws IOException;

    
Returns the width in pixels of the given image within the input
source.
 If the image can be rendered to a user-specified size, then
this method returns the default width.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs reading the width
information from the input source.
Returns:
the width of the image, as an int./**
     * Returns the width in pixels of the given image within the input
     * source.
     *
     * <p> If the image can be rendered to a user-specified size, then
     * this method returns the default width.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return the width of the image, as an <code>int</code>.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs reading the width
     * information from the input source.
     */
    public abstract int getWidth(int imageIndex) throws IOException;

    
Returns the height in pixels of the given image within the
input source.
 If the image can be rendered to a user-specified size, then
this method returns the default height.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs reading the height
information from the input source.
Returns:
the height of the image, as an int./**
     * Returns the height in pixels of the given image within the
     * input source.
     *
     * <p> If the image can be rendered to a user-specified size, then
     * this method returns the default height.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return the height of the image, as an <code>int</code>.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs reading the height
     * information from the input source.
     */
    public abstract int getHeight(int imageIndex) throws IOException;

    
Returns true if the storage format of the given
image places no inherent impediment on random access to pixels.
For most compressed formats, such as JPEG, this method should
return false, as a large section of the image in
addition to the region of interest may need to be decoded.
 This is merely a hint for programs that wish to be
efficient; all readers must be able to read arbitrary regions
as specified in an ImageReadParam.
 Note that formats that return false from
this method may nonetheless allow tiling (e.g. Restart Markers in JPEG), and random access will likely be reasonably efficient on tiles. See isImageTiled. 
 A reader for which all images are guaranteed to support
easy random access, or are guaranteed not to support easy
random access, may return true or
false respectively without accessing any image
data.  In such cases, it is not necessary to throw an exception
even if no input source has been set or the image index is out
of bounds.
 The default implementation returns false.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException – if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException – if an error occurs during reading.
Returns:
true if reading a region of interest of
the given image is likely to be efficient./**
     * Returns <code>true</code> if the storage format of the given
     * image places no inherent impediment on random access to pixels.
     * For most compressed formats, such as JPEG, this method should
     * return <code>false</code>, as a large section of the image in
     * addition to the region of interest may need to be decoded.
     *
     * <p> This is merely a hint for programs that wish to be
     * efficient; all readers must be able to read arbitrary regions
     * as specified in an <code>ImageReadParam</code>.
     *
     * <p> Note that formats that return <code>false</code> from
     * this method may nonetheless allow tiling (<i>e.g.</i> Restart
     * Markers in JPEG), and random access will likely be reasonably
     * efficient on tiles.  See {@link #isImageTiled
     * <code>isImageTiled</code>}.
     *
     * <p> A reader for which all images are guaranteed to support
     * easy random access, or are guaranteed not to support easy
     * random access, may return <code>true</code> or
     * <code>false</code> respectively without accessing any image
     * data.  In such cases, it is not necessary to throw an exception
     * even if no input source has been set or the image index is out
     * of bounds.
     *
     * <p> The default implementation returns <code>false</code>.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return <code>true</code> if reading a region of interest of
     * the given image is likely to be efficient.
     *
     * @exception IllegalStateException if an input source is required
     * to determine the return value, but none has been set.
     * @exception IndexOutOfBoundsException if an image must be
     * accessed to determine the return value, but the supplied index
     * is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public boolean isRandomAccessEasy(int imageIndex) throws IOException {
        return false;
    }

    
Returns the aspect ratio of the given image (that is, its width
divided by its height) as a float.  For images
that are inherently resizable, this method provides a way to
determine the appropriate width given a desired height, or vice
versa.  For non-resizable images, the true width and height
are used.
 The default implementation simply returns
(float)getWidth(imageIndex)/getHeight(imageIndex).
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
Returns:
a float indicating the aspect ratio of the
given image./**
     * Returns the aspect ratio of the given image (that is, its width
     * divided by its height) as a <code>float</code>.  For images
     * that are inherently resizable, this method provides a way to
     * determine the appropriate width given a desired height, or vice
     * versa.  For non-resizable images, the true width and height
     * are used.
     *
     * <p> The default implementation simply returns
     * <code>(float)getWidth(imageIndex)/getHeight(imageIndex)</code>.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return a <code>float</code> indicating the aspect ratio of the
     * given image.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public float getAspectRatio(int imageIndex) throws IOException {
        return (float)getWidth(imageIndex)/getHeight(imageIndex);
    }

    
Returns an ImageTypeSpecifier indicating the
SampleModel and ColorModel which most
closely represents the "raw" internal format of the image.  For
example, for a JPEG image the raw type might have a YCbCr color
space even though the image would conventionally be transformed
into an RGB color space prior to display.  The returned value
should also be included in the list of values returned by
getImageTypes.
 The default implementation simply returns the first entry
from the list provided by getImageType.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs reading the format
information from the input source.
Returns:
an ImageTypeSpecifier./**
     * Returns an <code>ImageTypeSpecifier</code> indicating the
     * <code>SampleModel</code> and <code>ColorModel</code> which most
     * closely represents the "raw" internal format of the image.  For
     * example, for a JPEG image the raw type might have a YCbCr color
     * space even though the image would conventionally be transformed
     * into an RGB color space prior to display.  The returned value
     * should also be included in the list of values returned by
     * <code>getImageTypes</code>.
     *
     * <p> The default implementation simply returns the first entry
     * from the list provided by <code>getImageType</code>.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return an <code>ImageTypeSpecifier</code>.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs reading the format
     * information from the input source.
     */
    public ImageTypeSpecifier getRawImageType(int imageIndex)
        throws IOException {
        return (ImageTypeSpecifier)getImageTypes(imageIndex).next();
    }

    
Returns an Iterator containing possible image
types to which the given image may be decoded, in the form of
ImageTypeSpecifierss.  At least one legal image
type will be returned.
 The first element of the iterator should be the most
"natural" type for decoding the image with as little loss as
possible.  For example, for a JPEG image the first entry should
be an RGB image, even though the image data is stored
internally in a YCbCr color space.
Params:
imageIndex – the index of the image to be
retrieved.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs reading the format
information from the input source.
See Also:
ImageReadParam.setDestination(BufferedImage)
ImageReadParam.setDestinationType(ImageTypeSpecifier)
Returns:
an Iterator containing at least one
ImageTypeSpecifier representing suggested image
types for decoding the current given image./**
     * Returns an <code>Iterator</code> containing possible image
     * types to which the given image may be decoded, in the form of
     * <code>ImageTypeSpecifiers</code>s.  At least one legal image
     * type will be returned.
     *
     * <p> The first element of the iterator should be the most
     * "natural" type for decoding the image with as little loss as
     * possible.  For example, for a JPEG image the first entry should
     * be an RGB image, even though the image data is stored
     * internally in a YCbCr color space.
     *
     * @param imageIndex the index of the image to be
     * <code>retrieved</code>.
     *
     * @return an <code>Iterator</code> containing at least one
     * <code>ImageTypeSpecifier</code> representing suggested image
     * types for decoding the current given image.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs reading the format
     * information from the input source.
     *
     * @see ImageReadParam#setDestination(BufferedImage)
     * @see ImageReadParam#setDestinationType(ImageTypeSpecifier)
     */
    public abstract Iterator<ImageTypeSpecifier>
        getImageTypes(int imageIndex) throws IOException;

    
Returns a default ImageReadParam object
appropriate for this format.  All subclasses should define a
set of default values for all parameters and return them with
this call.  This method may be called before the input source
is set.
 The default implementation constructs and returns a new
ImageReadParam object that does not allow source
scaling (i.e., it returns new
ImageReadParam().
Returns:
an ImageReadParam object which may be used
to control the decoding process using a set of default settings./**
     * Returns a default <code>ImageReadParam</code> object
     * appropriate for this format.  All subclasses should define a
     * set of default values for all parameters and return them with
     * this call.  This method may be called before the input source
     * is set.
     *
     * <p> The default implementation constructs and returns a new
     * <code>ImageReadParam</code> object that does not allow source
     * scaling (<i>i.e.</i>, it returns <code>new
     * ImageReadParam()</code>.
     *
     * @return an <code>ImageReadParam</code> object which may be used
     * to control the decoding process using a set of default settings.
     */
    public ImageReadParam getDefaultReadParam() {
        return new ImageReadParam();
    }

    
Returns an IIOMetadata object representing the
metadata associated with the input source as a whole (i.e., not
associated with any particular image), or null if
the reader does not support reading metadata, is set to ignore
metadata, or if no metadata is available.
Throws:
IOException – if an error occurs during reading.
Returns:
an IIOMetadata object, or null./**
     * Returns an <code>IIOMetadata</code> object representing the
     * metadata associated with the input source as a whole (i.e., not
     * associated with any particular image), or <code>null</code> if
     * the reader does not support reading metadata, is set to ignore
     * metadata, or if no metadata is available.
     *
     * @return an <code>IIOMetadata</code> object, or <code>null</code>.
     *
     * @exception IOException if an error occurs during reading.
     */
    public abstract IIOMetadata getStreamMetadata() throws IOException;

    
Returns an IIOMetadata object representing the
metadata associated with the input source as a whole (i.e.,
not associated with any particular image).  If no such data
exists, null is returned.
 The resulting metadata object is only responsible for
returning documents in the format named by
formatName.  Within any documents that are
returned, only nodes whose names are members of
nodeNames are required to be returned.  In this
way, the amount of metadata processing done by the reader may
be kept to a minimum, based on what information is actually
needed.
 If formatName is not the name of a supported
metadata format, null is returned.
 In all cases, it is legal to return a more capable metadata
object than strictly necessary.  The format name and node names
are merely hints that may be used to reduce the reader's
workload.
 The default implementation simply returns the result of
calling getStreamMetadata(), after checking that
the format name is supported.  If it is not,
null is returned.
Params:
formatName – a metadata format name that may be used to retrieve
a document from the returned IIOMetadata object.
nodeNames – a Set containing the names of
nodes that may be contained in a retrieved document.
Throws:
IllegalArgumentException – if formatName
is null.
IllegalArgumentException – if nodeNames
is null.
IOException – if an error occurs during reading.
Returns:
an IIOMetadata object, or null./**
     * Returns an <code>IIOMetadata</code> object representing the
     * metadata associated with the input source as a whole (i.e.,
     * not associated with any particular image).  If no such data
     * exists, <code>null</code> is returned.
     *
     * <p> The resulting metadata object is only responsible for
     * returning documents in the format named by
     * <code>formatName</code>.  Within any documents that are
     * returned, only nodes whose names are members of
     * <code>nodeNames</code> are required to be returned.  In this
     * way, the amount of metadata processing done by the reader may
     * be kept to a minimum, based on what information is actually
     * needed.
     *
     * <p> If <code>formatName</code> is not the name of a supported
     * metadata format, <code>null</code> is returned.
     *
     * <p> In all cases, it is legal to return a more capable metadata
     * object than strictly necessary.  The format name and node names
     * are merely hints that may be used to reduce the reader's
     * workload.
     *
     * <p> The default implementation simply returns the result of
     * calling <code>getStreamMetadata()</code>, after checking that
     * the format name is supported.  If it is not,
     * <code>null</code> is returned.
     *
     * @param formatName a metadata format name that may be used to retrieve
     * a document from the returned <code>IIOMetadata</code> object.
     * @param nodeNames a <code>Set</code> containing the names of
     * nodes that may be contained in a retrieved document.
     *
     * @return an <code>IIOMetadata</code> object, or <code>null</code>.
     *
     * @exception IllegalArgumentException if <code>formatName</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if <code>nodeNames</code>
     * is <code>null</code>.
     * @exception IOException if an error occurs during reading.
     */
    public IIOMetadata getStreamMetadata(String formatName,
                                         Set<String> nodeNames)
        throws IOException
    {
        return getMetadata(formatName, nodeNames, true, 0);
    }

    private IIOMetadata getMetadata(String formatName,
                                    Set nodeNames,
                                    boolean wantStream,
                                    int imageIndex) throws IOException {
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        if (nodeNames == null) {
            throw new IllegalArgumentException("nodeNames == null!");
        }
        IIOMetadata metadata =
            wantStream
            ? getStreamMetadata()
            : getImageMetadata(imageIndex);
        if (metadata != null) {
            if (metadata.isStandardMetadataFormatSupported() &&
                formatName.equals
                (IIOMetadataFormatImpl.standardMetadataFormatName)) {
                return metadata;
            }
            String nativeName = metadata.getNativeMetadataFormatName();
            if (nativeName != null && formatName.equals(nativeName)) {
                return metadata;
            }
            String[] extraNames = metadata.getExtraMetadataFormatNames();
            if (extraNames != null) {
                for (int i = 0; i < extraNames.length; i++) {
                    if (formatName.equals(extraNames[i])) {
                        return metadata;
                    }
                }
            }
        }
        return null;
    }

    
Returns an IIOMetadata object containing metadata
associated with the given image, or null if the
reader does not support reading metadata, is set to ignore
metadata, or if no metadata is available.
Params:
imageIndex – the index of the image whose metadata is to
be retrieved.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
Returns:
an IIOMetadata object, or
null./**
     * Returns an <code>IIOMetadata</code> object containing metadata
     * associated with the given image, or <code>null</code> if the
     * reader does not support reading metadata, is set to ignore
     * metadata, or if no metadata is available.
     *
     * @param imageIndex the index of the image whose metadata is to
     * be retrieved.
     *
     * @return an <code>IIOMetadata</code> object, or
     * <code>null</code>.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public abstract IIOMetadata getImageMetadata(int imageIndex)
        throws IOException;

    
Returns an IIOMetadata object representing the
metadata associated with the given image, or null
if the reader does not support reading metadata or none
is available.
 The resulting metadata object is only responsible for
returning documents in the format named by
formatName.  Within any documents that are
returned, only nodes whose names are members of
nodeNames are required to be returned.  In this
way, the amount of metadata processing done by the reader may
be kept to a minimum, based on what information is actually
needed.
 If formatName is not the name of a supported
metadata format, null may be returned.
 In all cases, it is legal to return a more capable metadata
object than strictly necessary.  The format name and node names
are merely hints that may be used to reduce the reader's
workload.
 The default implementation simply returns the result of
calling getImageMetadata(imageIndex), after
checking that the format name is supported.  If it is not,
null is returned.
Params:
imageIndex – the index of the image whose metadata is to
be retrieved.
formatName – a metadata format name that may be used to retrieve
a document from the returned IIOMetadata object.
nodeNames – a Set containing the names of
nodes that may be contained in a retrieved document.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IllegalArgumentException – if formatName
is null.
IllegalArgumentException – if nodeNames
is null.
IOException – if an error occurs during reading.
Returns:
an IIOMetadata object, or null./**
     * Returns an <code>IIOMetadata</code> object representing the
     * metadata associated with the given image, or <code>null</code>
     * if the reader does not support reading metadata or none
     * is available.
     *
     * <p> The resulting metadata object is only responsible for
     * returning documents in the format named by
     * <code>formatName</code>.  Within any documents that are
     * returned, only nodes whose names are members of
     * <code>nodeNames</code> are required to be returned.  In this
     * way, the amount of metadata processing done by the reader may
     * be kept to a minimum, based on what information is actually
     * needed.
     *
     * <p> If <code>formatName</code> is not the name of a supported
     * metadata format, <code>null</code> may be returned.
     *
     * <p> In all cases, it is legal to return a more capable metadata
     * object than strictly necessary.  The format name and node names
     * are merely hints that may be used to reduce the reader's
     * workload.
     *
     * <p> The default implementation simply returns the result of
     * calling <code>getImageMetadata(imageIndex)</code>, after
     * checking that the format name is supported.  If it is not,
     * <code>null</code> is returned.
     *
     * @param imageIndex the index of the image whose metadata is to
     * be retrieved.
     * @param formatName a metadata format name that may be used to retrieve
     * a document from the returned <code>IIOMetadata</code> object.
     * @param nodeNames a <code>Set</code> containing the names of
     * nodes that may be contained in a retrieved document.
     *
     * @return an <code>IIOMetadata</code> object, or <code>null</code>.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IllegalArgumentException if <code>formatName</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if <code>nodeNames</code>
     * is <code>null</code>.
     * @exception IOException if an error occurs during reading.
     */
    public IIOMetadata getImageMetadata(int imageIndex,
                                        String formatName,
                                        Set<String> nodeNames)
        throws IOException {
        return getMetadata(formatName, nodeNames, false, imageIndex);
    }

    
Reads the image indexed by imageIndex and returns
it as a complete BufferedImage, using a default
ImageReadParam.  This is a convenience method
that calls read(imageIndex, null).
 The image returned will be formatted according to the first
ImageTypeSpecifier returned from
getImageTypes.
 Any registered IIOReadProgressListener objects
will be notified by calling their imageStarted
method, followed by calls to their imageProgress
method as the read progresses.  Finally their
imageComplete method will be called.
IIOReadUpdateListener objects may be updated at
other times during the read as pixels are decoded.  Finally,
IIOReadWarningListener objects will receive
notification of any non-fatal warnings that occur during
decoding.
Params:
imageIndex – the index of the image to be retrieved.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
Returns:
the desired portion of the image as a
BufferedImage./**
     * Reads the image indexed by <code>imageIndex</code> and returns
     * it as a complete <code>BufferedImage</code>, using a default
     * <code>ImageReadParam</code>.  This is a convenience method
     * that calls <code>read(imageIndex, null)</code>.
     *
     * <p> The image returned will be formatted according to the first
     * <code>ImageTypeSpecifier</code> returned from
     * <code>getImageTypes</code>.
     *
     * <p> Any registered <code>IIOReadProgressListener</code> objects
     * will be notified by calling their <code>imageStarted</code>
     * method, followed by calls to their <code>imageProgress</code>
     * method as the read progresses.  Finally their
     * <code>imageComplete</code> method will be called.
     * <code>IIOReadUpdateListener</code> objects may be updated at
     * other times during the read as pixels are decoded.  Finally,
     * <code>IIOReadWarningListener</code> objects will receive
     * notification of any non-fatal warnings that occur during
     * decoding.
     *
     * @param imageIndex the index of the image to be retrieved.
     *
     * @return the desired portion of the image as a
     * <code>BufferedImage</code>.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public BufferedImage read(int imageIndex) throws IOException {
        return read(imageIndex, null);
    }

    
Reads the image indexed by imageIndex and returns
it as a complete BufferedImage, using a supplied
ImageReadParam.
 The actual BufferedImage returned will be
chosen using the algorithm defined by the
getDestination method.
 Any registered IIOReadProgressListener objects
will be notified by calling their imageStarted
method, followed by calls to their imageProgress
method as the read progresses.  Finally their
imageComplete method will be called.
IIOReadUpdateListener objects may be updated at
other times during the read as pixels are decoded.  Finally,
IIOReadWarningListener objects will receive
notification of any non-fatal warnings that occur during
decoding.
 The set of source bands to be read and destination bands to
be written is determined by calling getSourceBands
and getDestinationBands on the supplied
ImageReadParam.  If the lengths of the arrays
returned by these methods differ, the set of source bands
contains an index larger that the largest available source
index, or the set of destination bands contains an index larger
than the largest legal destination index, an
IllegalArgumentException is thrown.
 If the supplied ImageReadParam contains
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), they will
be ignored.
Params:
imageIndex – the index of the image to be retrieved.
param – an ImageReadParam used to control
the reading process, or null.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IllegalArgumentException – if the set of source and
destination bands specified by
param.getSourceBands and
param.getDestinationBands differ in length or
include indices that are out of bounds.
IllegalArgumentException – if the resulting image would
have a width or height less than 1.
IOException – if an error occurs during reading.
Returns:
the desired portion of the image as a
BufferedImage./**
     * Reads the image indexed by <code>imageIndex</code> and returns
     * it as a complete <code>BufferedImage</code>, using a supplied
     * <code>ImageReadParam</code>.
     *
     * <p> The actual <code>BufferedImage</code> returned will be
     * chosen using the algorithm defined by the
     * <code>getDestination</code> method.
     *
     * <p> Any registered <code>IIOReadProgressListener</code> objects
     * will be notified by calling their <code>imageStarted</code>
     * method, followed by calls to their <code>imageProgress</code>
     * method as the read progresses.  Finally their
     * <code>imageComplete</code> method will be called.
     * <code>IIOReadUpdateListener</code> objects may be updated at
     * other times during the read as pixels are decoded.  Finally,
     * <code>IIOReadWarningListener</code> objects will receive
     * notification of any non-fatal warnings that occur during
     * decoding.
     *
     * <p> The set of source bands to be read and destination bands to
     * be written is determined by calling <code>getSourceBands</code>
     * and <code>getDestinationBands</code> on the supplied
     * <code>ImageReadParam</code>.  If the lengths of the arrays
     * returned by these methods differ, the set of source bands
     * contains an index larger that the largest available source
     * index, or the set of destination bands contains an index larger
     * than the largest legal destination index, an
     * <code>IllegalArgumentException</code> is thrown.
     *
     * <p> If the supplied <code>ImageReadParam</code> contains
     * optional setting values not supported by this reader (<i>e.g.</i>
     * source render size or any format-specific settings), they will
     * be ignored.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param param an <code>ImageReadParam</code> used to control
     * the reading process, or <code>null</code>.
     *
     * @return the desired portion of the image as a
     * <code>BufferedImage</code>.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IllegalArgumentException if the set of source and
     * destination bands specified by
     * <code>param.getSourceBands</code> and
     * <code>param.getDestinationBands</code> differ in length or
     * include indices that are out of bounds.
     * @exception IllegalArgumentException if the resulting image would
     * have a width or height less than 1.
     * @exception IOException if an error occurs during reading.
     */
    public abstract BufferedImage read(int imageIndex, ImageReadParam param)
        throws IOException;

    
Reads the image indexed by imageIndex and returns
an IIOImage containing the image, thumbnails, and
associated image metadata, using a supplied
ImageReadParam.
 The actual BufferedImage referenced by the
returned IIOImage will be chosen using the
algorithm defined by the getDestination method.
 Any registered IIOReadProgressListener objects
will be notified by calling their imageStarted
method, followed by calls to their imageProgress
method as the read progresses.  Finally their
imageComplete method will be called.
IIOReadUpdateListener objects may be updated at
other times during the read as pixels are decoded.  Finally,
IIOReadWarningListener objects will receive
notification of any non-fatal warnings that occur during
decoding.
 The set of source bands to be read and destination bands to
be written is determined by calling getSourceBands
and getDestinationBands on the supplied
ImageReadParam.  If the lengths of the arrays
returned by these methods differ, the set of source bands
contains an index larger that the largest available source
index, or the set of destination bands contains an index larger
than the largest legal destination index, an
IllegalArgumentException is thrown.
 Thumbnails will be returned in their entirety regardless of
the region settings.
 If the supplied ImageReadParam contains
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), those
values will be ignored.
Params:
imageIndex – the index of the image to be retrieved.
param – an ImageReadParam used to control
the reading process, or null.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IllegalArgumentException – if the set of source and
destination bands specified by
param.getSourceBands and
param.getDestinationBands differ in length or
include indices that are out of bounds.
IllegalArgumentException – if the resulting image
would have a width or height less than 1.
IOException – if an error occurs during reading.
Returns:
an IIOImage containing the desired portion
of the image, a set of thumbnails, and associated image
metadata./**
     * Reads the image indexed by <code>imageIndex</code> and returns
     * an <code>IIOImage</code> containing the image, thumbnails, and
     * associated image metadata, using a supplied
     * <code>ImageReadParam</code>.
     *
     * <p> The actual <code>BufferedImage</code> referenced by the
     * returned <code>IIOImage</code> will be chosen using the
     * algorithm defined by the <code>getDestination</code> method.
     *
     * <p> Any registered <code>IIOReadProgressListener</code> objects
     * will be notified by calling their <code>imageStarted</code>
     * method, followed by calls to their <code>imageProgress</code>
     * method as the read progresses.  Finally their
     * <code>imageComplete</code> method will be called.
     * <code>IIOReadUpdateListener</code> objects may be updated at
     * other times during the read as pixels are decoded.  Finally,
     * <code>IIOReadWarningListener</code> objects will receive
     * notification of any non-fatal warnings that occur during
     * decoding.
     *
     * <p> The set of source bands to be read and destination bands to
     * be written is determined by calling <code>getSourceBands</code>
     * and <code>getDestinationBands</code> on the supplied
     * <code>ImageReadParam</code>.  If the lengths of the arrays
     * returned by these methods differ, the set of source bands
     * contains an index larger that the largest available source
     * index, or the set of destination bands contains an index larger
     * than the largest legal destination index, an
     * <code>IllegalArgumentException</code> is thrown.
     *
     * <p> Thumbnails will be returned in their entirety regardless of
     * the region settings.
     *
     * <p> If the supplied <code>ImageReadParam</code> contains
     * optional setting values not supported by this reader (<i>e.g.</i>
     * source render size or any format-specific settings), those
     * values will be ignored.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param param an <code>ImageReadParam</code> used to control
     * the reading process, or <code>null</code>.
     *
     * @return an <code>IIOImage</code> containing the desired portion
     * of the image, a set of thumbnails, and associated image
     * metadata.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IllegalArgumentException if the set of source and
     * destination bands specified by
     * <code>param.getSourceBands</code> and
     * <code>param.getDestinationBands</code> differ in length or
     * include indices that are out of bounds.
     * @exception IllegalArgumentException if the resulting image
     * would have a width or height less than 1.
     * @exception IOException if an error occurs during reading.
     */
    public IIOImage readAll(int imageIndex, ImageReadParam param)
        throws IOException {
        if (imageIndex < getMinIndex()) {
            throw new IndexOutOfBoundsException("imageIndex < getMinIndex()!");
        }

        BufferedImage im = read(imageIndex, param);

        ArrayList thumbnails = null;
        int numThumbnails = getNumThumbnails(imageIndex);
        if (numThumbnails > 0) {
            thumbnails = new ArrayList();
            for (int j = 0; j < numThumbnails; j++) {
                thumbnails.add(readThumbnail(imageIndex, j));
            }
        }

        IIOMetadata metadata = getImageMetadata(imageIndex);
        return new IIOImage(im, thumbnails, metadata);
    }

    
Returns an Iterator containing all the images,
thumbnails, and metadata, starting at the index given by
getMinIndex, from the input source in the form of
IIOImage objects.  An Iterator
containing ImageReadParam objects is supplied; one
element is consumed for each image read from the input source
until no more images are available.  If the read param
Iterator runs out of elements, but there are still
more images available from the input source, default read
params are used for the remaining images.
 If params is null, a default read
param will be used for all images.
 The actual BufferedImage referenced by the
returned IIOImage will be chosen using the
algorithm defined by the getDestination method.
 Any registered IIOReadProgressListener objects
will be notified by calling their sequenceStarted
method once.  Then, for each image decoded, there will be a
call to imageStarted, followed by calls to
imageProgress as the read progresses, and finally
to imageComplete.  The
sequenceComplete method will be called after the
last image has been decoded.
IIOReadUpdateListener objects may be updated at
other times during the read as pixels are decoded.  Finally,
IIOReadWarningListener objects will receive
notification of any non-fatal warnings that occur during
decoding.
 The set of source bands to be read and destination bands to
be written is determined by calling getSourceBands
and getDestinationBands on the supplied
ImageReadParam.  If the lengths of the arrays
returned by these methods differ, the set of source bands
contains an index larger that the largest available source
index, or the set of destination bands contains an index larger
than the largest legal destination index, an
IllegalArgumentException is thrown.
 Thumbnails will be returned in their entirety regardless of the
region settings.
 If any of the supplied ImageReadParams contain
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), they will
be ignored.
Params:
params – an Iterator containing
ImageReadParam objects.
Throws:
IllegalStateException – if the input source has not been
set.
IllegalArgumentException – if any
non-null element of params is not an
ImageReadParam.
IllegalArgumentException – if the set of source and
destination bands specified by
param.getSourceBands and
param.getDestinationBands differ in length or
include indices that are out of bounds.
IllegalArgumentException – if a resulting image would
have a width or height less than 1.
IOException – if an error occurs during reading.
See Also:
ImageReadParam
IIOImage
Returns:
an Iterator representing the
contents of the input source as IIOImages./**
     * Returns an <code>Iterator</code> containing all the images,
     * thumbnails, and metadata, starting at the index given by
     * <code>getMinIndex</code>, from the input source in the form of
     * <code>IIOImage</code> objects.  An <code>Iterator</code>
     * containing <code>ImageReadParam</code> objects is supplied; one
     * element is consumed for each image read from the input source
     * until no more images are available.  If the read param
     * <code>Iterator</code> runs out of elements, but there are still
     * more images available from the input source, default read
     * params are used for the remaining images.
     *
     * <p> If <code>params</code> is <code>null</code>, a default read
     * param will be used for all images.
     *
     * <p> The actual <code>BufferedImage</code> referenced by the
     * returned <code>IIOImage</code> will be chosen using the
     * algorithm defined by the <code>getDestination</code> method.
     *
     * <p> Any registered <code>IIOReadProgressListener</code> objects
     * will be notified by calling their <code>sequenceStarted</code>
     * method once.  Then, for each image decoded, there will be a
     * call to <code>imageStarted</code>, followed by calls to
     * <code>imageProgress</code> as the read progresses, and finally
     * to <code>imageComplete</code>.  The
     * <code>sequenceComplete</code> method will be called after the
     * last image has been decoded.
     * <code>IIOReadUpdateListener</code> objects may be updated at
     * other times during the read as pixels are decoded.  Finally,
     * <code>IIOReadWarningListener</code> objects will receive
     * notification of any non-fatal warnings that occur during
     * decoding.
     *
     * <p> The set of source bands to be read and destination bands to
     * be written is determined by calling <code>getSourceBands</code>
     * and <code>getDestinationBands</code> on the supplied
     * <code>ImageReadParam</code>.  If the lengths of the arrays
     * returned by these methods differ, the set of source bands
     * contains an index larger that the largest available source
     * index, or the set of destination bands contains an index larger
     * than the largest legal destination index, an
     * <code>IllegalArgumentException</code> is thrown.
     *
     * <p> Thumbnails will be returned in their entirety regardless of the
     * region settings.
     *
     * <p> If any of the supplied <code>ImageReadParam</code>s contain
     * optional setting values not supported by this reader (<i>e.g.</i>
     * source render size or any format-specific settings), they will
     * be ignored.
     *
     * @param params an <code>Iterator</code> containing
     * <code>ImageReadParam</code> objects.
     *
     * @return an <code>Iterator</code> representing the
     * contents of the input source as <code>IIOImage</code>s.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IllegalArgumentException if any
     * non-<code>null</code> element of <code>params</code> is not an
     * <code>ImageReadParam</code>.
     * @exception IllegalArgumentException if the set of source and
     * destination bands specified by
     * <code>param.getSourceBands</code> and
     * <code>param.getDestinationBands</code> differ in length or
     * include indices that are out of bounds.
     * @exception IllegalArgumentException if a resulting image would
     * have a width or height less than 1.
     * @exception IOException if an error occurs during reading.
     *
     * @see ImageReadParam
     * @see IIOImage
     */
    public Iterator<IIOImage>
        readAll(Iterator<? extends ImageReadParam> params)
        throws IOException
    {
        List output = new ArrayList();

        int imageIndex = getMinIndex();

        // Inform IIOReadProgressListeners we're starting a sequence
        processSequenceStarted(imageIndex);

        while (true) {
            // Inform IIOReadProgressListeners and IIOReadUpdateListeners
            // that we're starting a new image

            ImageReadParam param = null;
            if (params != null && params.hasNext()) {
                Object o = params.next();
                if (o != null) {
                    if (o instanceof ImageReadParam) {
                        param = (ImageReadParam)o;
                    } else {
                        throw new IllegalArgumentException
                            ("Non-ImageReadParam supplied as part of params!");
                    }
                }
            }

            BufferedImage bi = null;
            try {
                bi = read(imageIndex, param);
            } catch (IndexOutOfBoundsException e) {
                break;
            }

            ArrayList thumbnails = null;
            int numThumbnails = getNumThumbnails(imageIndex);
            if (numThumbnails > 0) {
                thumbnails = new ArrayList();
                for (int j = 0; j < numThumbnails; j++) {
                    thumbnails.add(readThumbnail(imageIndex, j));
                }
            }

            IIOMetadata metadata = getImageMetadata(imageIndex);
            IIOImage im = new IIOImage(bi, thumbnails, metadata);
            output.add(im);

            ++imageIndex;
        }

        // Inform IIOReadProgressListeners we're ending a sequence
        processSequenceComplete();

        return output.iterator();
    }

    
Returns true if this plug-in supports reading just a Raster of pixel data. If this method returns false, calls to readRaster or readTileRaster will throw an UnsupportedOperationException.
 The default implementation returns false.
See Also:
readRaster
readTileRaster
Returns:
true if this plug-in supports reading raw
Rasters./**
     * Returns <code>true</code> if this plug-in supports reading
     * just a {@link java.awt.image.Raster <code>Raster</code>} of pixel data.
     * If this method returns <code>false</code>, calls to
     * {@link #readRaster <code>readRaster</code>} or {@link #readTileRaster
     * <code>readTileRaster</code>} will throw an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> The default implementation returns <code>false</code>.
     *
     * @return <code>true</code> if this plug-in supports reading raw
     * <code>Raster</code>s.
     *
     * @see #readRaster
     * @see #readTileRaster
     */
    public boolean canReadRaster() {
        return false;
    }

    
Returns a new Raster object containing the raw pixel data
from the image stream, without any color conversion applied.  The
application must determine how to interpret the pixel data by other
means.  Any destination or image-type parameters in the supplied
ImageReadParam object are ignored, but all other parameters are used exactly as in the read method, except that any destination offset is used as a logical rather than a physical offset. The size of the returned Raster
will always be that of the source region clipped to the actual image.
Logical offsets in the stream itself are ignored.
 This method allows formats that normally apply a color
conversion, such as JPEG, and formats that do not normally have an
associated colorspace, such as remote sensing or medical imaging data,
to provide access to raw pixel data.
 Any registered readUpdateListeners are ignored, as
there is no BufferedImage, but all other listeners are called exactly as they are for the read method. 
 If canReadRaster() returns false, this method throws an
UnsupportedOperationException.
 If the supplied ImageReadParam contains
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), they will
be ignored.
 The default implementation throws an
UnsupportedOperationException.
Params:
imageIndex – the index of the image to be read.
param – an ImageReadParam used to control
the reading process, or null.
Throws:
UnsupportedOperationException – if this plug-in does not
support reading raw Rasters.
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
See Also:
canReadRaster
read
Raster
Returns:
the desired portion of the image as a
Raster./**
     * Returns a new <code>Raster</code> object containing the raw pixel data
     * from the image stream, without any color conversion applied.  The
     * application must determine how to interpret the pixel data by other
     * means.  Any destination or image-type parameters in the supplied
     * <code>ImageReadParam</code> object are ignored, but all other
     * parameters are used exactly as in the {@link #read <code>read</code>}
     * method, except that any destination offset is used as a logical rather
     * than a physical offset.  The size of the returned <code>Raster</code>
     * will always be that of the source region clipped to the actual image.
     * Logical offsets in the stream itself are ignored.
     *
     * <p> This method allows formats that normally apply a color
     * conversion, such as JPEG, and formats that do not normally have an
     * associated colorspace, such as remote sensing or medical imaging data,
     * to provide access to raw pixel data.
     *
     * <p> Any registered <code>readUpdateListener</code>s are ignored, as
     * there is no <code>BufferedImage</code>, but all other listeners are
     * called exactly as they are for the {@link #read <code>read</code>}
     * method.
     *
     * <p> If {@link #canReadRaster <code>canReadRaster()</code>} returns
     * <code>false</code>, this method throws an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> If the supplied <code>ImageReadParam</code> contains
     * optional setting values not supported by this reader (<i>e.g.</i>
     * source render size or any format-specific settings), they will
     * be ignored.
     *
     * <p> The default implementation throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index of the image to be read.
     * @param param an <code>ImageReadParam</code> used to control
     * the reading process, or <code>null</code>.
     *
     * @return the desired portion of the image as a
     * <code>Raster</code>.
     *
     * @exception UnsupportedOperationException if this plug-in does not
     * support reading raw <code>Raster</code>s.
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     *
     * @see #canReadRaster
     * @see #read
     * @see java.awt.image.Raster
     */
    public Raster readRaster(int imageIndex, ImageReadParam param)
        throws IOException {
        throw new UnsupportedOperationException("readRaster not supported!");
    }

    
Returns true if the image is organized into
tiles, that is, equal-sized non-overlapping rectangles.
 A reader plug-in may choose whether or not to expose tiling
that is present in the image as it is stored.  It may even
choose to advertise tiling when none is explicitly present.  In
general, tiling should only be advertised if there is some
advantage (in speed or space) to accessing individual tiles.
Regardless of whether the reader advertises tiling, it must be
capable of reading an arbitrary rectangular region specified in
an ImageReadParam.
 A reader for which all images are guaranteed to be tiled,
or are guaranteed not to be tiled, may return true
or false respectively without accessing any image
data.  In such cases, it is not necessary to throw an exception
even if no input source has been set or the image index is out
of bounds.
 The default implementation just returns false.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException – if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException – if an error occurs during reading.
Returns:
true if the image is tiled./**
     * Returns <code>true</code> if the image is organized into
     * <i>tiles</i>, that is, equal-sized non-overlapping rectangles.
     *
     * <p> A reader plug-in may choose whether or not to expose tiling
     * that is present in the image as it is stored.  It may even
     * choose to advertise tiling when none is explicitly present.  In
     * general, tiling should only be advertised if there is some
     * advantage (in speed or space) to accessing individual tiles.
     * Regardless of whether the reader advertises tiling, it must be
     * capable of reading an arbitrary rectangular region specified in
     * an <code>ImageReadParam</code>.
     *
     * <p> A reader for which all images are guaranteed to be tiled,
     * or are guaranteed not to be tiled, may return <code>true</code>
     * or <code>false</code> respectively without accessing any image
     * data.  In such cases, it is not necessary to throw an exception
     * even if no input source has been set or the image index is out
     * of bounds.
     *
     * <p> The default implementation just returns <code>false</code>.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @return <code>true</code> if the image is tiled.
     *
     * @exception IllegalStateException if an input source is required
     * to determine the return value, but none has been set.
     * @exception IndexOutOfBoundsException if an image must be
     * accessed to determine the return value, but the supplied index
     * is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public boolean isImageTiled(int imageIndex) throws IOException {
        return false;
    }

    
Returns the width of a tile in the given image.
 The default implementation simply returns
getWidth(imageIndex), which is correct for
non-tiled images.  Readers that support tiling should override
this method.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
Returns:
the width of a tile./**
     * Returns the width of a tile in the given image.
     *
     * <p> The default implementation simply returns
     * <code>getWidth(imageIndex)</code>, which is correct for
     * non-tiled images.  Readers that support tiling should override
     * this method.
     *
     * @return the width of a tile.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getTileWidth(int imageIndex) throws IOException {
        return getWidth(imageIndex);
    }

    
Returns the height of a tile in the given image.
 The default implementation simply returns
getHeight(imageIndex), which is correct for
non-tiled images.  Readers that support tiling should override
this method.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IOException – if an error occurs during reading.
Returns:
the height of a tile./**
     * Returns the height of a tile in the given image.
     *
     * <p> The default implementation simply returns
     * <code>getHeight(imageIndex)</code>, which is correct for
     * non-tiled images.  Readers that support tiling should override
     * this method.
     *
     * @return the height of a tile.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getTileHeight(int imageIndex) throws IOException {
        return getHeight(imageIndex);
    }

    
Returns the X coordinate of the upper-left corner of tile (0,
0) in the given image.
 A reader for which the tile grid X offset always has the
same value (usually 0), may return the value without accessing
any image data.  In such cases, it is not necessary to throw an
exception even if no input source has been set or the image
index is out of bounds.
 The default implementation simply returns 0, which is
correct for non-tiled images and tiled images in most formats.
Readers that support tiling with non-(0, 0) offsets should
override this method.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException – if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException – if an error occurs during reading.
Returns:
the X offset of the tile grid./**
     * Returns the X coordinate of the upper-left corner of tile (0,
     * 0) in the given image.
     *
     * <p> A reader for which the tile grid X offset always has the
     * same value (usually 0), may return the value without accessing
     * any image data.  In such cases, it is not necessary to throw an
     * exception even if no input source has been set or the image
     * index is out of bounds.
     *
     * <p> The default implementation simply returns 0, which is
     * correct for non-tiled images and tiled images in most formats.
     * Readers that support tiling with non-(0, 0) offsets should
     * override this method.
     *
     * @return the X offset of the tile grid.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @exception IllegalStateException if an input source is required
     * to determine the return value, but none has been set.
     * @exception IndexOutOfBoundsException if an image must be
     * accessed to determine the return value, but the supplied index
     * is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getTileGridXOffset(int imageIndex) throws IOException {
        return 0;
    }

    
Returns the Y coordinate of the upper-left corner of tile (0,
0) in the given image.
 A reader for which the tile grid Y offset always has the
same value (usually 0), may return the value without accessing
any image data.  In such cases, it is not necessary to throw an
exception even if no input source has been set or the image
index is out of bounds.
 The default implementation simply returns 0, which is
correct for non-tiled images and tiled images in most formats.
Readers that support tiling with non-(0, 0) offsets should
override this method.
Params:
imageIndex – the index of the image to be queried.
Throws:
IllegalStateException – if an input source is required
to determine the return value, but none has been set.
IndexOutOfBoundsException – if an image must be
accessed to determine the return value, but the supplied index
is out of bounds.
IOException – if an error occurs during reading.
Returns:
the Y offset of the tile grid./**
     * Returns the Y coordinate of the upper-left corner of tile (0,
     * 0) in the given image.
     *
     * <p> A reader for which the tile grid Y offset always has the
     * same value (usually 0), may return the value without accessing
     * any image data.  In such cases, it is not necessary to throw an
     * exception even if no input source has been set or the image
     * index is out of bounds.
     *
     * <p> The default implementation simply returns 0, which is
     * correct for non-tiled images and tiled images in most formats.
     * Readers that support tiling with non-(0, 0) offsets should
     * override this method.
     *
     * @return the Y offset of the tile grid.
     *
     * @param imageIndex the index of the image to be queried.
     *
     * @exception IllegalStateException if an input source is required
     * to determine the return value, but none has been set.
     * @exception IndexOutOfBoundsException if an image must be
     * accessed to determine the return value, but the supplied index
     * is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getTileGridYOffset(int imageIndex) throws IOException {
        return 0;
    }

    
Reads the tile indicated by the tileX and
tileY arguments, returning it as a
BufferedImage.  If the arguments are out of range,
an IllegalArgumentException is thrown.  If the
image is not tiled, the values 0, 0 will return the entire
image; any other values will cause an
IllegalArgumentException to be thrown.
 This method is merely a convenience equivalent to calling
read(int, ImageReadParam) with a read param
specifying a source region having offsets of
tileX*getTileWidth(imageIndex),
tileY*getTileHeight(imageIndex) and width and
height of getTileWidth(imageIndex),
getTileHeight(imageIndex); and subsampling
factors of 1 and offsets of 0.  To subsample a tile, call
read with a read param specifying this region
and different subsampling parameters.
 The default implementation returns the entire image if
tileX and tileY are 0, or throws
an IllegalArgumentException otherwise.
Params:
imageIndex – the index of the image to be retrieved.
tileX – the column index (starting with 0) of the tile
to be retrieved.
tileY – the row index (starting with 0) of the tile
to be retrieved.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if imageIndex
is out of bounds.
IllegalArgumentException – if the tile indices are
out of bounds.
IOException – if an error occurs during reading.
Returns:
the tile as a BufferedImage./**
     * Reads the tile indicated by the <code>tileX</code> and
     * <code>tileY</code> arguments, returning it as a
     * <code>BufferedImage</code>.  If the arguments are out of range,
     * an <code>IllegalArgumentException</code> is thrown.  If the
     * image is not tiled, the values 0, 0 will return the entire
     * image; any other values will cause an
     * <code>IllegalArgumentException</code> to be thrown.
     *
     * <p> This method is merely a convenience equivalent to calling
     * <code>read(int, ImageReadParam)</code> with a read param
     * specifying a source region having offsets of
     * <code>tileX*getTileWidth(imageIndex)</code>,
     * <code>tileY*getTileHeight(imageIndex)</code> and width and
     * height of <code>getTileWidth(imageIndex)</code>,
     * <code>getTileHeight(imageIndex)</code>; and subsampling
     * factors of 1 and offsets of 0.  To subsample a tile, call
     * <code>read</code> with a read param specifying this region
     * and different subsampling parameters.
     *
     * <p> The default implementation returns the entire image if
     * <code>tileX</code> and <code>tileY</code> are 0, or throws
     * an <code>IllegalArgumentException</code> otherwise.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param tileX the column index (starting with 0) of the tile
     * to be retrieved.
     * @param tileY the row index (starting with 0) of the tile
     * to be retrieved.
     *
     * @return the tile as a <code>BufferedImage</code>.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is out of bounds.
     * @exception IllegalArgumentException if the tile indices are
     * out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public BufferedImage readTile(int imageIndex,
                                  int tileX, int tileY) throws IOException {
        if ((tileX != 0) || (tileY != 0)) {
            throw new IllegalArgumentException("Invalid tile indices");
        }
        return read(imageIndex);
    }

    
Returns a new Raster object containing the raw
pixel data from the tile, without any color conversion applied.
The application must determine how to interpret the pixel data by other
means.
 If canReadRaster() returns false, this method throws an
UnsupportedOperationException.
 The default implementation checks if reading
Rasters is supported, and if so calls readRaster(imageIndex, null) if tileX and tileY are 0, or throws an
IllegalArgumentException otherwise.
Params:
imageIndex – the index of the image to be retrieved.
tileX – the column index (starting with 0) of the tile
to be retrieved.
tileY – the row index (starting with 0) of the tile
to be retrieved.
Throws:
UnsupportedOperationException – if this plug-in does not
support reading raw Rasters.
IllegalArgumentException – if the tile indices are
out of bounds.
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if imageIndex
is out of bounds.
IOException – if an error occurs during reading.
See Also:
readTile
readRaster
Raster
Returns:
the tile as a Raster./**
     * Returns a new <code>Raster</code> object containing the raw
     * pixel data from the tile, without any color conversion applied.
     * The application must determine how to interpret the pixel data by other
     * means.
     *
     * <p> If {@link #canReadRaster <code>canReadRaster()</code>} returns
     * <code>false</code>, this method throws an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> The default implementation checks if reading
     * <code>Raster</code>s is supported, and if so calls {@link
     * #readRaster <code>readRaster(imageIndex, null)</code>} if
     * <code>tileX</code> and <code>tileY</code> are 0, or throws an
     * <code>IllegalArgumentException</code> otherwise.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param tileX the column index (starting with 0) of the tile
     * to be retrieved.
     * @param tileY the row index (starting with 0) of the tile
     * to be retrieved.
     *
     * @return the tile as a <code>Raster</code>.
     *
     * @exception UnsupportedOperationException if this plug-in does not
     * support reading raw <code>Raster</code>s.
     * @exception IllegalArgumentException if the tile indices are
     * out of bounds.
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is out of bounds.
     * @exception IOException if an error occurs during reading.
     *
     * @see #readTile
     * @see #readRaster
     * @see java.awt.image.Raster
     */
    public Raster readTileRaster(int imageIndex,
                                 int tileX, int tileY) throws IOException {
        if (!canReadRaster()) {
            throw new UnsupportedOperationException
                ("readTileRaster not supported!");
        }
        if ((tileX != 0) || (tileY != 0)) {
            throw new IllegalArgumentException("Invalid tile indices");
        }
        return readRaster(imageIndex, null);
    }

    // RenderedImages

    
Returns a RenderedImage object that contains the
contents of the image indexed by imageIndex.  By
default, the returned image is simply the
BufferedImage returned by read(imageIndex,
param).
 The semantics of this method may differ from those of the
other read methods in several ways.  First, any
destination image and/or image type set in the
ImageReadParam may be ignored.  Second, the usual
listener calls are not guaranteed to be made, or to be
meaningful if they are.  This is because the returned image may
not be fully populated with pixel data at the time it is
returned, or indeed at any time.
 If the supplied ImageReadParam contains
optional setting values not supported by this reader (e.g.
source render size or any format-specific settings), they will
be ignored.
 The default implementation just calls read(imageIndex, param). 
Params:
imageIndex – the index of the image to be retrieved.
param – an ImageReadParam used to control
the reading process, or null.
Throws:
IllegalStateException – if the input source has not been
set.
IndexOutOfBoundsException – if the supplied index is
out of bounds.
IllegalArgumentException – if the set of source and
destination bands specified by
param.getSourceBands and
param.getDestinationBands differ in length or
include indices that are out of bounds.
IllegalArgumentException – if the resulting image
would have a width or height less than 1.
IOException – if an error occurs during reading.
Returns:
a RenderedImage object providing a view of
the image./**
     * Returns a <code>RenderedImage</code> object that contains the
     * contents of the image indexed by <code>imageIndex</code>.  By
     * default, the returned image is simply the
     * <code>BufferedImage</code> returned by <code>read(imageIndex,
     * param)</code>.
     *
     * <p> The semantics of this method may differ from those of the
     * other <code>read</code> methods in several ways.  First, any
     * destination image and/or image type set in the
     * <code>ImageReadParam</code> may be ignored.  Second, the usual
     * listener calls are not guaranteed to be made, or to be
     * meaningful if they are.  This is because the returned image may
     * not be fully populated with pixel data at the time it is
     * returned, or indeed at any time.
     *
     * <p> If the supplied <code>ImageReadParam</code> contains
     * optional setting values not supported by this reader (<i>e.g.</i>
     * source render size or any format-specific settings), they will
     * be ignored.
     *
     * <p> The default implementation just calls {@link #read
     * <code>read(imageIndex, param)</code>}.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param param an <code>ImageReadParam</code> used to control
     * the reading process, or <code>null</code>.
     *
     * @return a <code>RenderedImage</code> object providing a view of
     * the image.
     *
     * @exception IllegalStateException if the input source has not been
     * set.
     * @exception IndexOutOfBoundsException if the supplied index is
     * out of bounds.
     * @exception IllegalArgumentException if the set of source and
     * destination bands specified by
     * <code>param.getSourceBands</code> and
     * <code>param.getDestinationBands</code> differ in length or
     * include indices that are out of bounds.
     * @exception IllegalArgumentException if the resulting image
     * would have a width or height less than 1.
     * @exception IOException if an error occurs during reading.
     */
    public RenderedImage readAsRenderedImage(int imageIndex,
                                             ImageReadParam param)
        throws IOException {
        return read(imageIndex, param);
    }

    // Thumbnails

    
Returns true if the image format understood by
this reader supports thumbnail preview images associated with
it.  The default implementation returns false.
 If this method returns false,
hasThumbnails and getNumThumbnails
will return false and 0,
respectively, and readThumbnail will throw an
UnsupportedOperationException, regardless of their
arguments.
 A reader that does not support thumbnails need not
implement any of the thumbnail-related methods.
Returns:
true if thumbnails are supported./**
     * Returns <code>true</code> if the image format understood by
     * this reader supports thumbnail preview images associated with
     * it.  The default implementation returns <code>false</code>.
     *
     * <p> If this method returns <code>false</code>,
     * <code>hasThumbnails</code> and <code>getNumThumbnails</code>
     * will return <code>false</code> and <code>0</code>,
     * respectively, and <code>readThumbnail</code> will throw an
     * <code>UnsupportedOperationException</code>, regardless of their
     * arguments.
     *
     * <p> A reader that does not support thumbnails need not
     * implement any of the thumbnail-related methods.
     *
     * @return <code>true</code> if thumbnails are supported.
     */
    public boolean readerSupportsThumbnails() {
        return false;
    }

    
Returns true if the given image has thumbnail
preview images associated with it.  If the format does not
support thumbnails (readerSupportsThumbnails
returns false), false will be
returned regardless of whether an input source has been set or
whether imageIndex is in bounds.
 The default implementation returns true if
getNumThumbnails returns a value greater than 0.
Params:
imageIndex – the index of the image being queried.
Throws:
IllegalStateException – if the reader supports
thumbnails but the input source has not been set.
IndexOutOfBoundsException – if the reader supports
thumbnails but imageIndex is out of bounds.
IOException – if an error occurs during reading.
Returns:
true if the given image has thumbnails./**
     * Returns <code>true</code> if the given image has thumbnail
     * preview images associated with it.  If the format does not
     * support thumbnails (<code>readerSupportsThumbnails</code>
     * returns <code>false</code>), <code>false</code> will be
     * returned regardless of whether an input source has been set or
     * whether <code>imageIndex</code> is in bounds.
     *
     * <p> The default implementation returns <code>true</code> if
     * <code>getNumThumbnails</code> returns a value greater than 0.
     *
     * @param imageIndex the index of the image being queried.
     *
     * @return <code>true</code> if the given image has thumbnails.
     *
     * @exception IllegalStateException if the reader supports
     * thumbnails but the input source has not been set.
     * @exception IndexOutOfBoundsException if the reader supports
     * thumbnails but <code>imageIndex</code> is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public boolean hasThumbnails(int imageIndex) throws IOException {
        return getNumThumbnails(imageIndex) > 0;
    }

    
Returns the number of thumbnail preview images associated with
the given image.  If the format does not support thumbnails,
(readerSupportsThumbnails returns
false), 0 will be returned regardless
of whether an input source has been set or whether
imageIndex is in bounds.
 The default implementation returns 0 without checking its
argument.
Params:
imageIndex – the index of the image being queried.
Throws:
IllegalStateException – if the reader supports
thumbnails but the input source has not been set.
IndexOutOfBoundsException – if the reader supports
thumbnails but imageIndex is out of bounds.
IOException – if an error occurs during reading.
Returns:
the number of thumbnails associated with the given
image./**
     * Returns the number of thumbnail preview images associated with
     * the given image.  If the format does not support thumbnails,
     * (<code>readerSupportsThumbnails</code> returns
     * <code>false</code>), <code>0</code> will be returned regardless
     * of whether an input source has been set or whether
     * <code>imageIndex</code> is in bounds.
     *
     * <p> The default implementation returns 0 without checking its
     * argument.
     *
     * @param imageIndex the index of the image being queried.
     *
     * @return the number of thumbnails associated with the given
     * image.
     *
     * @exception IllegalStateException if the reader supports
     * thumbnails but the input source has not been set.
     * @exception IndexOutOfBoundsException if the reader supports
     * thumbnails but <code>imageIndex</code> is out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getNumThumbnails(int imageIndex)
        throws IOException {
        return 0;
    }

    
Returns the width of the thumbnail preview image indexed by
thumbnailIndex, associated with the image indexed
by ImageIndex.
 If the reader does not support thumbnails,
(readerSupportsThumbnails returns
false), an UnsupportedOperationException
will be thrown.
 The default implementation simply returns
readThumbnail(imageindex,
thumbnailIndex).getWidth().  Subclasses should therefore
override this method if possible in order to avoid forcing the
thumbnail to be read.
Params:
imageIndex – the index of the image to be retrieved.
thumbnailIndex – the index of the thumbnail to be retrieved.
Throws:
UnsupportedOperationException – if thumbnails are not
supported.
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if either of the supplied
indices are out of bounds.
IOException – if an error occurs during reading.
Returns:
the width of the desired thumbnail as an int./**
     * Returns the width of the thumbnail preview image indexed by
     * <code>thumbnailIndex</code>, associated with the image indexed
     * by <code>ImageIndex</code>.
     *
     * <p> If the reader does not support thumbnails,
     * (<code>readerSupportsThumbnails</code> returns
     * <code>false</code>), an <code>UnsupportedOperationException</code>
     * will be thrown.
     *
     * <p> The default implementation simply returns
     * <code>readThumbnail(imageindex,
     * thumbnailIndex).getWidth()</code>.  Subclasses should therefore
     * override this method if possible in order to avoid forcing the
     * thumbnail to be read.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param thumbnailIndex the index of the thumbnail to be retrieved.
     *
     * @return the width of the desired thumbnail as an <code>int</code>.
     *
     * @exception UnsupportedOperationException if thumbnails are not
     * supported.
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if either of the supplied
     * indices are out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getThumbnailWidth(int imageIndex, int thumbnailIndex)
        throws IOException {
        return readThumbnail(imageIndex, thumbnailIndex).getWidth();
    }

    
Returns the height of the thumbnail preview image indexed by
thumbnailIndex, associated with the image indexed
by ImageIndex.
 If the reader does not support thumbnails,
(readerSupportsThumbnails returns
false), an UnsupportedOperationException
will be thrown.
 The default implementation simply returns
readThumbnail(imageindex,
thumbnailIndex).getHeight().  Subclasses should
therefore override this method if possible in order to avoid
forcing the thumbnail to be read.
Params:
imageIndex – the index of the image to be retrieved.
thumbnailIndex – the index of the thumbnail to be retrieved.
Throws:
UnsupportedOperationException – if thumbnails are not
supported.
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if either of the supplied
indices are out of bounds.
IOException – if an error occurs during reading.
Returns:
the height of the desired thumbnail as an int./**
     * Returns the height of the thumbnail preview image indexed by
     * <code>thumbnailIndex</code>, associated with the image indexed
     * by <code>ImageIndex</code>.
     *
     * <p> If the reader does not support thumbnails,
     * (<code>readerSupportsThumbnails</code> returns
     * <code>false</code>), an <code>UnsupportedOperationException</code>
     * will be thrown.
     *
     * <p> The default implementation simply returns
     * <code>readThumbnail(imageindex,
     * thumbnailIndex).getHeight()</code>.  Subclasses should
     * therefore override this method if possible in order to avoid
     * forcing the thumbnail to be read.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param thumbnailIndex the index of the thumbnail to be retrieved.
     *
     * @return the height of the desired thumbnail as an <code>int</code>.
     *
     * @exception UnsupportedOperationException if thumbnails are not
     * supported.
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if either of the supplied
     * indices are out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public int getThumbnailHeight(int imageIndex, int thumbnailIndex)
        throws IOException {
        return readThumbnail(imageIndex, thumbnailIndex).getHeight();
    }

    
Returns the thumbnail preview image indexed by
thumbnailIndex, associated with the image indexed
by ImageIndex as a BufferedImage.
 Any registered IIOReadProgressListener objects
will be notified by calling their
thumbnailStarted, thumbnailProgress,
and thumbnailComplete methods.
 If the reader does not support thumbnails,
(readerSupportsThumbnails returns
false), an UnsupportedOperationException
will be thrown regardless of whether an input source has been
set or whether the indices are in bounds.
 The default implementation throws an
UnsupportedOperationException.
Params:
imageIndex – the index of the image to be retrieved.
thumbnailIndex – the index of the thumbnail to be retrieved.
Throws:
UnsupportedOperationException – if thumbnails are not
supported.
IllegalStateException – if the input source has not been set.
IndexOutOfBoundsException – if either of the supplied
indices are out of bounds.
IOException – if an error occurs during reading.
Returns:
the desired thumbnail as a BufferedImage./**
     * Returns the thumbnail preview image indexed by
     * <code>thumbnailIndex</code>, associated with the image indexed
     * by <code>ImageIndex</code> as a <code>BufferedImage</code>.
     *
     * <p> Any registered <code>IIOReadProgressListener</code> objects
     * will be notified by calling their
     * <code>thumbnailStarted</code>, <code>thumbnailProgress</code>,
     * and <code>thumbnailComplete</code> methods.
     *
     * <p> If the reader does not support thumbnails,
     * (<code>readerSupportsThumbnails</code> returns
     * <code>false</code>), an <code>UnsupportedOperationException</code>
     * will be thrown regardless of whether an input source has been
     * set or whether the indices are in bounds.
     *
     * <p> The default implementation throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index of the image to be retrieved.
     * @param thumbnailIndex the index of the thumbnail to be retrieved.
     *
     * @return the desired thumbnail as a <code>BufferedImage</code>.
     *
     * @exception UnsupportedOperationException if thumbnails are not
     * supported.
     * @exception IllegalStateException if the input source has not been set.
     * @exception IndexOutOfBoundsException if either of the supplied
     * indices are out of bounds.
     * @exception IOException if an error occurs during reading.
     */
    public BufferedImage readThumbnail(int imageIndex,
                                       int thumbnailIndex)
        throws IOException {
        throw new UnsupportedOperationException("Thumbnails not supported!");
    }

    // Abort

    
Requests that any current read operation be aborted.  The
contents of the image following the abort will be undefined.
 Readers should call clearAbortRequest at the
beginning of each read operation, and poll the value of
abortRequested regularly during the read.
/**
     * Requests that any current read operation be aborted.  The
     * contents of the image following the abort will be undefined.
     *
     * <p> Readers should call <code>clearAbortRequest</code> at the
     * beginning of each read operation, and poll the value of
     * <code>abortRequested</code> regularly during the read.
     */
    public synchronized void abort() {
        this.abortFlag = true;
    }

    
Returns true if a request to abort the current
read operation has been made since the reader was instantiated or
clearAbortRequest was called.
See Also:
abort
clearAbortRequest
Returns:
true if the current read operation should
be aborted./**
     * Returns <code>true</code> if a request to abort the current
     * read operation has been made since the reader was instantiated or
     * <code>clearAbortRequest</code> was called.
     *
     * @return <code>true</code> if the current read operation should
     * be aborted.
     *
     * @see #abort
     * @see #clearAbortRequest
     */
    protected synchronized boolean abortRequested() {
        return this.abortFlag;
    }

    
Clears any previous abort request.  After this method has been
called, abortRequested will return
false.
See Also:
abort
abortRequested/**
     * Clears any previous abort request.  After this method has been
     * called, <code>abortRequested</code> will return
     * <code>false</code>.
     *
     * @see #abort
     * @see #abortRequested
     */
    protected synchronized void clearAbortRequest() {
        this.abortFlag = false;
    }

    // Listeners

    // Add an element to a list, creating a new list if the
    // existing list is null, and return the list.
    static List addToList(List l, Object elt) {
        if (l == null) {
            l = new ArrayList();
        }
        l.add(elt);
        return l;
    }


    // Remove an element from a list, discarding the list if the
    // resulting list is empty, and return the list or null.
    static List removeFromList(List l, Object elt) {
        if (l == null) {
            return l;
        }
        l.remove(elt);
        if (l.size() == 0) {
            l = null;
        }
        return l;
    }

    
Adds an IIOReadWarningListener to the list of
registered warning listeners.  If listener is
null, no exception will be thrown and no action
will be taken.  Messages sent to the given listener will be
localized, if possible, to match the current
Locale.  If no Locale has been set,
warning messages may be localized as the reader sees fit.
Params:
listener – an IIOReadWarningListener to be registered.
See Also:
removeIIOReadWarningListener/**
     * Adds an <code>IIOReadWarningListener</code> to the list of
     * registered warning listeners.  If <code>listener</code> is
     * <code>null</code>, no exception will be thrown and no action
     * will be taken.  Messages sent to the given listener will be
     * localized, if possible, to match the current
     * <code>Locale</code>.  If no <code>Locale</code> has been set,
     * warning messages may be localized as the reader sees fit.
     *
     * @param listener an <code>IIOReadWarningListener</code> to be registered.
     *
     * @see #removeIIOReadWarningListener
     */
    public void addIIOReadWarningListener(IIOReadWarningListener listener) {
        if (listener == null) {
            return;
        }
        warningListeners = addToList(warningListeners, listener);
        warningLocales = addToList(warningLocales, getLocale());
    }

    
Removes an IIOReadWarningListener from the list of
registered error listeners.  If the listener was not previously
registered, or if listener is null,
no exception will be thrown and no action will be taken.
Params:
listener – an IIOReadWarningListener to be unregistered.
See Also:
addIIOReadWarningListener/**
     * Removes an <code>IIOReadWarningListener</code> from the list of
     * registered error listeners.  If the listener was not previously
     * registered, or if <code>listener</code> is <code>null</code>,
     * no exception will be thrown and no action will be taken.
     *
     * @param listener an IIOReadWarningListener to be unregistered.
     *
     * @see #addIIOReadWarningListener
     */
    public void removeIIOReadWarningListener(IIOReadWarningListener listener) {
        if (listener == null || warningListeners == null) {
            return;
        }
        int index = warningListeners.indexOf(listener);
        if (index != -1) {
            warningListeners.remove(index);
            warningLocales.remove(index);
            if (warningListeners.size() == 0) {
                warningListeners = null;
                warningLocales = null;
            }
        }
    }

    
Removes all currently registered
IIOReadWarningListener objects.
 The default implementation sets the
warningListeners and warningLocales
instance variables to null.
/**
     * Removes all currently registered
     * <code>IIOReadWarningListener</code> objects.
     *
     * <p> The default implementation sets the
     * <code>warningListeners</code> and <code>warningLocales</code>
     * instance variables to <code>null</code>.
     */
    public void removeAllIIOReadWarningListeners() {
        warningListeners = null;
        warningLocales = null;
    }

    
Adds an IIOReadProgressListener to the list of
registered progress listeners.  If listener is
null, no exception will be thrown and no action
will be taken.
Params:
listener – an IIOReadProgressListener to be registered.
See Also:
removeIIOReadProgressListener/**
     * Adds an <code>IIOReadProgressListener</code> to the list of
     * registered progress listeners.  If <code>listener</code> is
     * <code>null</code>, no exception will be thrown and no action
     * will be taken.
     *
     * @param listener an IIOReadProgressListener to be registered.
     *
     * @see #removeIIOReadProgressListener
     */
    public void addIIOReadProgressListener(IIOReadProgressListener listener) {
        if (listener == null) {
            return;
        }
        progressListeners = addToList(progressListeners, listener);
    }

    
Removes an IIOReadProgressListener from the list
of registered progress listeners.  If the listener was not
previously registered, or if listener is
null, no exception will be thrown and no action
will be taken.
Params:
listener – an IIOReadProgressListener to be unregistered.
See Also:
addIIOReadProgressListener/**
     * Removes an <code>IIOReadProgressListener</code> from the list
     * of registered progress listeners.  If the listener was not
     * previously registered, or if <code>listener</code> is
     * <code>null</code>, no exception will be thrown and no action
     * will be taken.
     *
     * @param listener an IIOReadProgressListener to be unregistered.
     *
     * @see #addIIOReadProgressListener
     */
    public void
        removeIIOReadProgressListener (IIOReadProgressListener listener) {
        if (listener == null || progressListeners == null) {
            return;
        }
        progressListeners = removeFromList(progressListeners, listener);
    }

    
Removes all currently registered
IIOReadProgressListener objects.
 The default implementation sets the
progressListeners instance variable to
null.
/**
     * Removes all currently registered
     * <code>IIOReadProgressListener</code> objects.
     *
     * <p> The default implementation sets the
     * <code>progressListeners</code> instance variable to
     * <code>null</code>.
     */
    public void removeAllIIOReadProgressListeners() {
        progressListeners = null;
    }

    
Adds an IIOReadUpdateListener to the list of
registered update listeners.  If listener is
null, no exception will be thrown and no action
will be taken.  The listener will receive notification of pixel
updates as images and thumbnails are decoded, including the
starts and ends of progressive passes.
 If no update listeners are present, the reader may choose
to perform fewer updates to the pixels of the destination
images and/or thumbnails, which may result in more efficient
decoding.
 For example, in progressive JPEG decoding each pass
contains updates to a set of coefficients, which would have to
be transformed into pixel values and converted to an RGB color
space for each pass if listeners are present.  If no listeners
are present, the coefficients may simply be accumulated and the
final results transformed and color converted one time only.
 The final results of decoding will be the same whether or
not intermediate updates are performed.  Thus if only the final
image is desired it may be preferable not to register any
IIOReadUpdateListeners.  In general, progressive
updating is most effective when fetching images over a network
connection that is very slow compared to local CPU processing;
over a fast connection, progressive updates may actually slow
down the presentation of the image.
Params:
listener – an IIOReadUpdateListener to be registered.
See Also:
removeIIOReadUpdateListener/**
     * Adds an <code>IIOReadUpdateListener</code> to the list of
     * registered update listeners.  If <code>listener</code> is
     * <code>null</code>, no exception will be thrown and no action
     * will be taken.  The listener will receive notification of pixel
     * updates as images and thumbnails are decoded, including the
     * starts and ends of progressive passes.
     *
     * <p> If no update listeners are present, the reader may choose
     * to perform fewer updates to the pixels of the destination
     * images and/or thumbnails, which may result in more efficient
     * decoding.
     *
     * <p> For example, in progressive JPEG decoding each pass
     * contains updates to a set of coefficients, which would have to
     * be transformed into pixel values and converted to an RGB color
     * space for each pass if listeners are present.  If no listeners
     * are present, the coefficients may simply be accumulated and the
     * final results transformed and color converted one time only.
     *
     * <p> The final results of decoding will be the same whether or
     * not intermediate updates are performed.  Thus if only the final
     * image is desired it may be preferable not to register any
     * <code>IIOReadUpdateListener</code>s.  In general, progressive
     * updating is most effective when fetching images over a network
     * connection that is very slow compared to local CPU processing;
     * over a fast connection, progressive updates may actually slow
     * down the presentation of the image.
     *
     * @param listener an IIOReadUpdateListener to be registered.
     *
     * @see #removeIIOReadUpdateListener
     */
    public void
        addIIOReadUpdateListener(IIOReadUpdateListener listener) {
        if (listener == null) {
            return;
        }
        updateListeners = addToList(updateListeners, listener);
    }

    
Removes an IIOReadUpdateListener from the list of
registered update listeners.  If the listener was not
previously registered, or if listener is
null, no exception will be thrown and no action
will be taken.
Params:
listener – an IIOReadUpdateListener to be unregistered.
See Also:
addIIOReadUpdateListener/**
     * Removes an <code>IIOReadUpdateListener</code> from the list of
     * registered update listeners.  If the listener was not
     * previously registered, or if <code>listener</code> is
     * <code>null</code>, no exception will be thrown and no action
     * will be taken.
     *
     * @param listener an IIOReadUpdateListener to be unregistered.
     *
     * @see #addIIOReadUpdateListener
     */
    public void removeIIOReadUpdateListener(IIOReadUpdateListener listener) {
        if (listener == null || updateListeners == null) {
            return;
        }
        updateListeners = removeFromList(updateListeners, listener);
    }

    
Removes all currently registered
IIOReadUpdateListener objects.
 The default implementation sets the
updateListeners instance variable to
null.
/**
     * Removes all currently registered
     * <code>IIOReadUpdateListener</code> objects.
     *
     * <p> The default implementation sets the
     * <code>updateListeners</code> instance variable to
     * <code>null</code>.
     */
    public void removeAllIIOReadUpdateListeners() {
        updateListeners = null;
    }

    
Broadcasts the start of an sequence of image reads to all
registered IIOReadProgressListeners by calling
their sequenceStarted method.  Subclasses may use
this method as a convenience.
Params:
minIndex – the lowest index being read./**
     * Broadcasts the start of an sequence of image reads to all
     * registered <code>IIOReadProgressListener</code>s by calling
     * their <code>sequenceStarted</code> method.  Subclasses may use
     * this method as a convenience.
     *
     * @param minIndex the lowest index being read.
     */
    protected void processSequenceStarted(int minIndex) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.sequenceStarted(this, minIndex);
        }
    }

    
Broadcasts the completion of an sequence of image reads to all
registered IIOReadProgressListeners by calling
their sequenceComplete method.  Subclasses may use
this method as a convenience.
/**
     * Broadcasts the completion of an sequence of image reads to all
     * registered <code>IIOReadProgressListener</code>s by calling
     * their <code>sequenceComplete</code> method.  Subclasses may use
     * this method as a convenience.
     */
    protected void processSequenceComplete() {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.sequenceComplete(this);
        }
    }

    
Broadcasts the start of an image read to all registered
IIOReadProgressListeners by calling their
imageStarted method.  Subclasses may use this
method as a convenience.
Params:
imageIndex – the index of the image about to be read./**
     * Broadcasts the start of an image read to all registered
     * <code>IIOReadProgressListener</code>s by calling their
     * <code>imageStarted</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param imageIndex the index of the image about to be read.
     */
    protected void processImageStarted(int imageIndex) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.imageStarted(this, imageIndex);
        }
    }

    
Broadcasts the current percentage of image completion to all
registered IIOReadProgressListeners by calling
their imageProgress method.  Subclasses may use
this method as a convenience.
Params:
percentageDone – the current percentage of completion,
as a float./**
     * Broadcasts the current percentage of image completion to all
     * registered <code>IIOReadProgressListener</code>s by calling
     * their <code>imageProgress</code> method.  Subclasses may use
     * this method as a convenience.
     *
     * @param percentageDone the current percentage of completion,
     * as a <code>float</code>.
     */
    protected void processImageProgress(float percentageDone) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.imageProgress(this, percentageDone);
        }
    }

    
Broadcasts the completion of an image read to all registered
IIOReadProgressListeners by calling their
imageComplete method.  Subclasses may use this
method as a convenience.
/**
     * Broadcasts the completion of an image read to all registered
     * <code>IIOReadProgressListener</code>s by calling their
     * <code>imageComplete</code> method.  Subclasses may use this
     * method as a convenience.
     */
    protected void processImageComplete() {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.imageComplete(this);
        }
    }

    
Broadcasts the start of a thumbnail read to all registered
IIOReadProgressListeners by calling their
thumbnailStarted method.  Subclasses may use this
method as a convenience.
Params:
imageIndex – the index of the image associated with the
thumbnail.
thumbnailIndex – the index of the thumbnail./**
     * Broadcasts the start of a thumbnail read to all registered
     * <code>IIOReadProgressListener</code>s by calling their
     * <code>thumbnailStarted</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param imageIndex the index of the image associated with the
     * thumbnail.
     * @param thumbnailIndex the index of the thumbnail.
     */
    protected void processThumbnailStarted(int imageIndex,
                                           int thumbnailIndex) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.thumbnailStarted(this, imageIndex, thumbnailIndex);
        }
    }

    
Broadcasts the current percentage of thumbnail completion to
all registered IIOReadProgressListeners by calling
their thumbnailProgress method.  Subclasses may
use this method as a convenience.
Params:
percentageDone – the current percentage of completion,
as a float./**
     * Broadcasts the current percentage of thumbnail completion to
     * all registered <code>IIOReadProgressListener</code>s by calling
     * their <code>thumbnailProgress</code> method.  Subclasses may
     * use this method as a convenience.
     *
     * @param percentageDone the current percentage of completion,
     * as a <code>float</code>.
     */
    protected void processThumbnailProgress(float percentageDone) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.thumbnailProgress(this, percentageDone);
        }
    }

    
Broadcasts the completion of a thumbnail read to all registered
IIOReadProgressListeners by calling their
thumbnailComplete method.  Subclasses may use this
method as a convenience.
/**
     * Broadcasts the completion of a thumbnail read to all registered
     * <code>IIOReadProgressListener</code>s by calling their
     * <code>thumbnailComplete</code> method.  Subclasses may use this
     * method as a convenience.
     */
    protected void processThumbnailComplete() {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.thumbnailComplete(this);
        }
    }

    
Broadcasts that the read has been aborted to all registered
IIOReadProgressListeners by calling their
readAborted method.  Subclasses may use this
method as a convenience.
/**
     * Broadcasts that the read has been aborted to all registered
     * <code>IIOReadProgressListener</code>s by calling their
     * <code>readAborted</code> method.  Subclasses may use this
     * method as a convenience.
     */
    protected void processReadAborted() {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadProgressListener listener =
                (IIOReadProgressListener)progressListeners.get(i);
            listener.readAborted(this);
        }
    }

    
Broadcasts the beginning of a progressive pass to all
registered IIOReadUpdateListeners by calling their
passStarted method.  Subclasses may use this
method as a convenience.
Params:
theImage – the BufferedImage being updated.
pass – the index of the current pass, starting with 0.
minPass – the index of the first pass that will be decoded.
maxPass – the index of the last pass that will be decoded.
minX – the X coordinate of the upper-left pixel included
in the pass.
minY – the X coordinate of the upper-left pixel included
in the pass.
periodX – the horizontal separation between pixels.
periodY – the vertical separation between pixels.
bands – an array of ints indicating the
set of affected bands of the destination./**
     * Broadcasts the beginning of a progressive pass to all
     * registered <code>IIOReadUpdateListener</code>s by calling their
     * <code>passStarted</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param theImage the <code>BufferedImage</code> being updated.
     * @param pass the index of the current pass, starting with 0.
     * @param minPass the index of the first pass that will be decoded.
     * @param maxPass the index of the last pass that will be decoded.
     * @param minX the X coordinate of the upper-left pixel included
     * in the pass.
     * @param minY the X coordinate of the upper-left pixel included
     * in the pass.
     * @param periodX the horizontal separation between pixels.
     * @param periodY the vertical separation between pixels.
     * @param bands an array of <code>int</code>s indicating the
     * set of affected bands of the destination.
     */
    protected void processPassStarted(BufferedImage theImage,
                                      int pass,
                                      int minPass, int maxPass,
                                      int minX, int minY,
                                      int periodX, int periodY,
                                      int[] bands) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.passStarted(this, theImage, pass,
                                 minPass,
                                 maxPass,
                                 minX, minY,
                                 periodX, periodY,
                                 bands);
        }
    }

    
Broadcasts the update of a set of samples to all registered
IIOReadUpdateListeners by calling their
imageUpdate method.  Subclasses may use this
method as a convenience.
Params:
theImage – the BufferedImage being updated.
minX – the X coordinate of the upper-left pixel included
in the pass.
minY – the X coordinate of the upper-left pixel included
in the pass.
width – the total width of the area being updated, including
pixels being skipped if periodX > 1.
height – the total height of the area being updated,
including pixels being skipped if periodY > 1.
periodX – the horizontal separation between pixels.
periodY – the vertical separation between pixels.
bands – an array of ints indicating the
set of affected bands of the destination./**
     * Broadcasts the update of a set of samples to all registered
     * <code>IIOReadUpdateListener</code>s by calling their
     * <code>imageUpdate</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param theImage the <code>BufferedImage</code> being updated.
     * @param minX the X coordinate of the upper-left pixel included
     * in the pass.
     * @param minY the X coordinate of the upper-left pixel included
     * in the pass.
     * @param width the total width of the area being updated, including
     * pixels being skipped if <code>periodX &gt; 1</code>.
     * @param height the total height of the area being updated,
     * including pixels being skipped if <code>periodY &gt; 1</code>.
     * @param periodX the horizontal separation between pixels.
     * @param periodY the vertical separation between pixels.
     * @param bands an array of <code>int</code>s indicating the
     * set of affected bands of the destination.
     */
    protected void processImageUpdate(BufferedImage theImage,
                                      int minX, int minY,
                                      int width, int height,
                                      int periodX, int periodY,
                                      int[] bands) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.imageUpdate(this,
                                 theImage,
                                 minX, minY,
                                 width, height,
                                 periodX, periodY,
                                 bands);
        }
    }

    
Broadcasts the end of a progressive pass to all
registered IIOReadUpdateListeners by calling their
passComplete method.  Subclasses may use this
method as a convenience.
Params:
theImage – the BufferedImage being updated./**
     * Broadcasts the end of a progressive pass to all
     * registered <code>IIOReadUpdateListener</code>s by calling their
     * <code>passComplete</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param theImage the <code>BufferedImage</code> being updated.
     */
    protected void processPassComplete(BufferedImage theImage) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.passComplete(this, theImage);
        }
    }

    
Broadcasts the beginning of a thumbnail progressive pass to all
registered IIOReadUpdateListeners by calling their
thumbnailPassStarted method.  Subclasses may use this
method as a convenience.
Params:
theThumbnail – the BufferedImage thumbnail
being updated.
pass – the index of the current pass, starting with 0.
minPass – the index of the first pass that will be decoded.
maxPass – the index of the last pass that will be decoded.
minX – the X coordinate of the upper-left pixel included
in the pass.
minY – the X coordinate of the upper-left pixel included
in the pass.
periodX – the horizontal separation between pixels.
periodY – the vertical separation between pixels.
bands – an array of ints indicating the
set of affected bands of the destination./**
     * Broadcasts the beginning of a thumbnail progressive pass to all
     * registered <code>IIOReadUpdateListener</code>s by calling their
     * <code>thumbnailPassStarted</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param theThumbnail the <code>BufferedImage</code> thumbnail
     * being updated.
     * @param pass the index of the current pass, starting with 0.
     * @param minPass the index of the first pass that will be decoded.
     * @param maxPass the index of the last pass that will be decoded.
     * @param minX the X coordinate of the upper-left pixel included
     * in the pass.
     * @param minY the X coordinate of the upper-left pixel included
     * in the pass.
     * @param periodX the horizontal separation between pixels.
     * @param periodY the vertical separation between pixels.
     * @param bands an array of <code>int</code>s indicating the
     * set of affected bands of the destination.
     */
    protected void processThumbnailPassStarted(BufferedImage theThumbnail,
                                               int pass,
                                               int minPass, int maxPass,
                                               int minX, int minY,
                                               int periodX, int periodY,
                                               int[] bands) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.thumbnailPassStarted(this, theThumbnail, pass,
                                          minPass,
                                          maxPass,
                                          minX, minY,
                                          periodX, periodY,
                                          bands);
        }
    }

    
Broadcasts the update of a set of samples in a thumbnail image
to all registered IIOReadUpdateListeners by
calling their thumbnailUpdate method.  Subclasses may
use this method as a convenience.
Params:
theThumbnail – the BufferedImage thumbnail
being updated.
minX – the X coordinate of the upper-left pixel included
in the pass.
minY – the X coordinate of the upper-left pixel included
in the pass.
width – the total width of the area being updated, including
pixels being skipped if periodX > 1.
height – the total height of the area being updated,
including pixels being skipped if periodY > 1.
periodX – the horizontal separation between pixels.
periodY – the vertical separation between pixels.
bands – an array of ints indicating the
set of affected bands of the destination./**
     * Broadcasts the update of a set of samples in a thumbnail image
     * to all registered <code>IIOReadUpdateListener</code>s by
     * calling their <code>thumbnailUpdate</code> method.  Subclasses may
     * use this method as a convenience.
     *
     * @param theThumbnail the <code>BufferedImage</code> thumbnail
     * being updated.
     * @param minX the X coordinate of the upper-left pixel included
     * in the pass.
     * @param minY the X coordinate of the upper-left pixel included
     * in the pass.
     * @param width the total width of the area being updated, including
     * pixels being skipped if <code>periodX &gt; 1</code>.
     * @param height the total height of the area being updated,
     * including pixels being skipped if <code>periodY &gt; 1</code>.
     * @param periodX the horizontal separation between pixels.
     * @param periodY the vertical separation between pixels.
     * @param bands an array of <code>int</code>s indicating the
     * set of affected bands of the destination.
     */
    protected void processThumbnailUpdate(BufferedImage theThumbnail,
                                          int minX, int minY,
                                          int width, int height,
                                          int periodX, int periodY,
                                          int[] bands) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.thumbnailUpdate(this,
                                     theThumbnail,
                                     minX, minY,
                                     width, height,
                                     periodX, periodY,
                                     bands);
        }
    }

    
Broadcasts the end of a thumbnail progressive pass to all
registered IIOReadUpdateListeners by calling their
thumbnailPassComplete method.  Subclasses may use this
method as a convenience.
Params:
theThumbnail – the BufferedImage thumbnail
being updated./**
     * Broadcasts the end of a thumbnail progressive pass to all
     * registered <code>IIOReadUpdateListener</code>s by calling their
     * <code>thumbnailPassComplete</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param theThumbnail the <code>BufferedImage</code> thumbnail
     * being updated.
     */
    protected void processThumbnailPassComplete(BufferedImage theThumbnail) {
        if (updateListeners == null) {
            return;
        }
        int numListeners = updateListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadUpdateListener listener =
                (IIOReadUpdateListener)updateListeners.get(i);
            listener.thumbnailPassComplete(this, theThumbnail);
        }
    }

    
Broadcasts a warning message to all registered
IIOReadWarningListeners by calling their
warningOccurred method.  Subclasses may use this
method as a convenience.
Params:
warning – the warning message to send.
Throws:
IllegalArgumentException – if warning
is null./**
     * Broadcasts a warning message to all registered
     * <code>IIOReadWarningListener</code>s by calling their
     * <code>warningOccurred</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param warning the warning message to send.
     *
     * @exception IllegalArgumentException if <code>warning</code>
     * is <code>null</code>.
     */
    protected void processWarningOccurred(String warning) {
        if (warningListeners == null) {
            return;
        }
        if (warning == null) {
            throw new IllegalArgumentException("warning == null!");
        }
        int numListeners = warningListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadWarningListener listener =
                (IIOReadWarningListener)warningListeners.get(i);

            listener.warningOccurred(this, warning);
        }
    }

    
Broadcasts a localized warning message to all registered
IIOReadWarningListeners by calling their
warningOccurred method with a string taken
from a ResourceBundle.  Subclasses may use this
method as a convenience.
Params:
baseName – the base name of a set of
ResourceBundles containing localized warning
messages.
keyword – the keyword used to index the warning message
within the set of ResourceBundles.
Throws:
IllegalArgumentException – if baseName
is null.
IllegalArgumentException – if keyword
is null.
IllegalArgumentException – if no appropriate
ResourceBundle may be located.
IllegalArgumentException – if the named resource is
not found in the located ResourceBundle.
IllegalArgumentException – if the object retrieved
from the ResourceBundle is not a
String./**
     * Broadcasts a localized warning message to all registered
     * <code>IIOReadWarningListener</code>s by calling their
     * <code>warningOccurred</code> method with a string taken
     * from a <code>ResourceBundle</code>.  Subclasses may use this
     * method as a convenience.
     *
     * @param baseName the base name of a set of
     * <code>ResourceBundle</code>s containing localized warning
     * messages.
     * @param keyword the keyword used to index the warning message
     * within the set of <code>ResourceBundle</code>s.
     *
     * @exception IllegalArgumentException if <code>baseName</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if <code>keyword</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if no appropriate
     * <code>ResourceBundle</code> may be located.
     * @exception IllegalArgumentException if the named resource is
     * not found in the located <code>ResourceBundle</code>.
     * @exception IllegalArgumentException if the object retrieved
     * from the <code>ResourceBundle</code> is not a
     * <code>String</code>.
     */
    protected void processWarningOccurred(String baseName,
                                          String keyword) {
        if (warningListeners == null) {
            return;
        }
        if (baseName == null) {
            throw new IllegalArgumentException("baseName == null!");
        }
        if (keyword == null) {
            throw new IllegalArgumentException("keyword == null!");
        }
        int numListeners = warningListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOReadWarningListener listener =
                (IIOReadWarningListener)warningListeners.get(i);
            Locale locale = (Locale)warningLocales.get(i);
            if (locale == null) {
                locale = Locale.getDefault();
            }

            /**
             * If an applet supplies an implementation of ImageReader and
             * resource bundles, then the resource bundle will need to be
             * accessed via the applet class loader. So first try the context
             * class loader to locate the resource bundle.
             * If that throws MissingResourceException, then try the
             * system class loader.
             */
            ClassLoader loader = (ClassLoader)
                java.security.AccessController.doPrivileged(
                   new java.security.PrivilegedAction() {
                      public Object run() {
                        return Thread.currentThread().getContextClassLoader();
                      }
                });

            ResourceBundle bundle = null;
            try {
                bundle = ResourceBundle.getBundle(baseName, locale, loader);
            } catch (MissingResourceException mre) {
                try {
                    bundle = ResourceBundle.getBundle(baseName, locale);
                } catch (MissingResourceException mre1) {
                    throw new IllegalArgumentException("Bundle not found!");
                }
            }

            String warning = null;
            try {
                warning = bundle.getString(keyword);
            } catch (ClassCastException cce) {
                throw new IllegalArgumentException("Resource is not a String!");
            } catch (MissingResourceException mre) {
                throw new IllegalArgumentException("Resource is missing!");
            }

            listener.warningOccurred(this, warning);
        }
    }

    // State management

    
Restores the ImageReader to its initial state.
 The default implementation calls setInput(null,
false), setLocale(null),
removeAllIIOReadUpdateListeners(),
removeAllIIOReadWarningListeners(),
removeAllIIOReadProgressListeners(), and
clearAbortRequest.
/**
     * Restores the <code>ImageReader</code> to its initial state.
     *
     * <p> The default implementation calls <code>setInput(null,
     * false)</code>, <code>setLocale(null)</code>,
     * <code>removeAllIIOReadUpdateListeners()</code>,
     * <code>removeAllIIOReadWarningListeners()</code>,
     * <code>removeAllIIOReadProgressListeners()</code>, and
     * <code>clearAbortRequest</code>.
     */
    public void reset() {
        setInput(null, false, false);
        setLocale(null);
        removeAllIIOReadUpdateListeners();
        removeAllIIOReadProgressListeners();
        removeAllIIOReadWarningListeners();
        clearAbortRequest();
    }

    
Allows any resources held by this object to be released.  The
result of calling any other method (other than
finalize) subsequent to a call to this method
is undefined.
It is important for applications to call this method when they
know they will no longer be using this ImageReader.
Otherwise, the reader may continue to hold on to resources
indefinitely.
The default implementation of this method in the superclass does
nothing.  Subclass implementations should ensure that all resources,
especially native resources, are released.
/**
     * Allows any resources held by this object to be released.  The
     * result of calling any other method (other than
     * <code>finalize</code>) subsequent to a call to this method
     * is undefined.
     *
     * <p>It is important for applications to call this method when they
     * know they will no longer be using this <code>ImageReader</code>.
     * Otherwise, the reader may continue to hold on to resources
     * indefinitely.
     *
     * <p>The default implementation of this method in the superclass does
     * nothing.  Subclass implementations should ensure that all resources,
     * especially native resources, are released.
     */
    public void dispose() {
    }

    // Utility methods

    
A utility method that may be used by readers to compute the
region of the source image that should be read, taking into
account any source region and subsampling offset settings in
the supplied ImageReadParam.  The actual
subsampling factors, destination size, and destination offset
are not taken into consideration, thus further clipping must take place. The computeRegions method performs all necessary clipping. 
Params:
param – the ImageReadParam being used, or
null.
srcWidth – the width of the source image.
srcHeight – the height of the source image.
Returns:
the source region as a Rectangle./**
     * A utility method that may be used by readers to compute the
     * region of the source image that should be read, taking into
     * account any source region and subsampling offset settings in
     * the supplied <code>ImageReadParam</code>.  The actual
     * subsampling factors, destination size, and destination offset
     * are <em>not</em> taken into consideration, thus further
     * clipping must take place.  The {@link #computeRegions
     * <code>computeRegions</code>} method performs all necessary
     * clipping.
     *
     * @param param the <code>ImageReadParam</code> being used, or
     * <code>null</code>.
     * @param srcWidth the width of the source image.
     * @param srcHeight the height of the source image.
     *
     * @return the source region as a <code>Rectangle</code>.
     */
    protected static Rectangle getSourceRegion(ImageReadParam param,
                                               int srcWidth,
                                               int srcHeight) {
        Rectangle sourceRegion = new Rectangle(0, 0, srcWidth, srcHeight);
        if (param != null) {
            Rectangle region = param.getSourceRegion();
            if (region != null) {
                sourceRegion = sourceRegion.intersection(region);
            }

            int subsampleXOffset = param.getSubsamplingXOffset();
            int subsampleYOffset = param.getSubsamplingYOffset();
            sourceRegion.x += subsampleXOffset;
            sourceRegion.y += subsampleYOffset;
            sourceRegion.width -= subsampleXOffset;
            sourceRegion.height -= subsampleYOffset;
        }

        return sourceRegion;
    }

    
Computes the source region of interest and the destination
region of interest, taking the width and height of the source
image, an optional destination image, and an optional
ImageReadParam into account.  The source region
begins with the entire source image.  Then that is clipped to
the source region specified in the ImageReadParam,
if one is specified.
 If either of the destination offsets are negative, the
source region is clipped so that its top left will coincide
with the top left of the destination image, taking subsampling
into account.  Then the result is clipped to the destination
image on the right and bottom, if one is specified, taking
subsampling and destination offsets into account.
 Similarly, the destination region begins with the source
image, is translated to the destination offset given in the
ImageReadParam if there is one, and finally is
clipped to the destination image, if there is one.
 If either the source or destination regions end up having a
width or height of 0, an IllegalArgumentException
is thrown.
 The getSourceRegion method may be used if only source clipping is desired. 
Params:
param – an ImageReadParam, or null.
srcWidth – the width of the source image.
srcHeight – the height of the source image.
image – a BufferedImage that will be the
destination image, or null.
srcRegion – a Rectangle that will be filled with
the source region of interest.
destRegion – a Rectangle that will be filled with
the destination region of interest.
Throws:
IllegalArgumentException – if srcRegion
is null.
IllegalArgumentException – if dstRegion
is null.
IllegalArgumentException – if the resulting source or
destination region is empty./**
     * Computes the source region of interest and the destination
     * region of interest, taking the width and height of the source
     * image, an optional destination image, and an optional
     * <code>ImageReadParam</code> into account.  The source region
     * begins with the entire source image.  Then that is clipped to
     * the source region specified in the <code>ImageReadParam</code>,
     * if one is specified.
     *
     * <p> If either of the destination offsets are negative, the
     * source region is clipped so that its top left will coincide
     * with the top left of the destination image, taking subsampling
     * into account.  Then the result is clipped to the destination
     * image on the right and bottom, if one is specified, taking
     * subsampling and destination offsets into account.
     *
     * <p> Similarly, the destination region begins with the source
     * image, is translated to the destination offset given in the
     * <code>ImageReadParam</code> if there is one, and finally is
     * clipped to the destination image, if there is one.
     *
     * <p> If either the source or destination regions end up having a
     * width or height of 0, an <code>IllegalArgumentException</code>
     * is thrown.
     *
     * <p> The {@link #getSourceRegion <code>getSourceRegion</code>}
     * method may be used if only source clipping is desired.
     *
     * @param param an <code>ImageReadParam</code>, or <code>null</code>.
     * @param srcWidth the width of the source image.
     * @param srcHeight the height of the source image.
     * @param image a <code>BufferedImage</code> that will be the
     * destination image, or <code>null</code>.
     * @param srcRegion a <code>Rectangle</code> that will be filled with
     * the source region of interest.
     * @param destRegion a <code>Rectangle</code> that will be filled with
     * the destination region of interest.
     * @exception IllegalArgumentException if <code>srcRegion</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if <code>dstRegion</code>
     * is <code>null</code>.
     * @exception IllegalArgumentException if the resulting source or
     * destination region is empty.
     */
    protected static void computeRegions(ImageReadParam param,
                                         int srcWidth,
                                         int srcHeight,
                                         BufferedImage image,
                                         Rectangle srcRegion,
                                         Rectangle destRegion) {
        if (srcRegion == null) {
            throw new IllegalArgumentException("srcRegion == null!");
        }
        if (destRegion == null) {
            throw new IllegalArgumentException("destRegion == null!");
        }

        // Start with the entire source image
        srcRegion.setBounds(0, 0, srcWidth, srcHeight);

        // Destination also starts with source image, as that is the
        // maximum extent if there is no subsampling
        destRegion.setBounds(0, 0, srcWidth, srcHeight);

        // Clip that to the param region, if there is one
        int periodX = 1;
        int periodY = 1;
        int gridX = 0;
        int gridY = 0;
        if (param != null) {
            Rectangle paramSrcRegion = param.getSourceRegion();
            if (paramSrcRegion != null) {
                srcRegion.setBounds(srcRegion.intersection(paramSrcRegion));
            }
            periodX = param.getSourceXSubsampling();
            periodY = param.getSourceYSubsampling();
            gridX = param.getSubsamplingXOffset();
            gridY = param.getSubsamplingYOffset();
            srcRegion.translate(gridX, gridY);
            srcRegion.width -= gridX;
            srcRegion.height -= gridY;
            destRegion.setLocation(param.getDestinationOffset());
        }

        // Now clip any negative destination offsets, i.e. clip
        // to the top and left of the destination image
        if (destRegion.x < 0) {
            int delta = -destRegion.x*periodX;
            srcRegion.x += delta;
            srcRegion.width -= delta;
            destRegion.x = 0;
        }
        if (destRegion.y < 0) {
            int delta = -destRegion.y*periodY;
            srcRegion.y += delta;
            srcRegion.height -= delta;
            destRegion.y = 0;
        }

        // Now clip the destination Region to the subsampled width and height
        int subsampledWidth = (srcRegion.width + periodX - 1)/periodX;
        int subsampledHeight = (srcRegion.height + periodY - 1)/periodY;
        destRegion.width = subsampledWidth;
        destRegion.height = subsampledHeight;

        // Now clip that to right and bottom of the destination image,
        // if there is one, taking subsampling into account
        if (image != null) {
            Rectangle destImageRect = new Rectangle(0, 0,
                                                    image.getWidth(),
                                                    image.getHeight());
            destRegion.setBounds(destRegion.intersection(destImageRect));
            if (destRegion.isEmpty()) {
                throw new IllegalArgumentException
                    ("Empty destination region!");
            }

            int deltaX = destRegion.x + subsampledWidth - image.getWidth();
            if (deltaX > 0) {
                srcRegion.width -= deltaX*periodX;
            }
            int deltaY =  destRegion.y + subsampledHeight - image.getHeight();
            if (deltaY > 0) {
                srcRegion.height -= deltaY*periodY;
            }
        }
        if (srcRegion.isEmpty() || destRegion.isEmpty()) {
            throw new IllegalArgumentException("Empty region!");
        }
    }

    
A utility method that may be used by readers to test the
validity of the source and destination band settings of an
ImageReadParam.  This method may be called as soon
as the reader knows both the number of bands of the source
image as it exists in the input stream, and the number of bands
of the destination image that being written.
 The method retrieves the source and destination band
setting arrays from param using the getSourceBands
and getDestinationBandsmethods (or considers them
to be null if param is
null).  If the source band setting array is
null, it is considered to be equal to the array
{ 0, 1, ..., numSrcBands - 1 }, and similarly for
the destination band setting array.
 The method then tests that both arrays are equal in length,
and that neither array contains a value larger than the largest
available band index.
 Any failure results in an
IllegalArgumentException being thrown; success
results in the method returning silently.
Params:
param – the ImageReadParam being used to read
the image.
numSrcBands – the number of bands of the image as it exists
int the input source.
numDstBands – the number of bands in the destination image
being written.
Throws:
IllegalArgumentException – if param
contains an invalid specification of a source and/or
destination band subset./**
     * A utility method that may be used by readers to test the
     * validity of the source and destination band settings of an
     * <code>ImageReadParam</code>.  This method may be called as soon
     * as the reader knows both the number of bands of the source
     * image as it exists in the input stream, and the number of bands
     * of the destination image that being written.
     *
     * <p> The method retrieves the source and destination band
     * setting arrays from param using the <code>getSourceBands</code>
     * and <code>getDestinationBands</code>methods (or considers them
     * to be <code>null</code> if <code>param</code> is
     * <code>null</code>).  If the source band setting array is
     * <code>null</code>, it is considered to be equal to the array
     * <code>{ 0, 1, ..., numSrcBands - 1 }</code>, and similarly for
     * the destination band setting array.
     *
     * <p> The method then tests that both arrays are equal in length,
     * and that neither array contains a value larger than the largest
     * available band index.
     *
     * <p> Any failure results in an
     * <code>IllegalArgumentException</code> being thrown; success
     * results in the method returning silently.
     *
     * @param param the <code>ImageReadParam</code> being used to read
     * the image.
     * @param numSrcBands the number of bands of the image as it exists
     * int the input source.
     * @param numDstBands the number of bands in the destination image
     * being written.
     *
     * @exception IllegalArgumentException if <code>param</code>
     * contains an invalid specification of a source and/or
     * destination band subset.
     */
    protected static void checkReadParamBandSettings(ImageReadParam param,
                                                     int numSrcBands,
                                                     int numDstBands) {
        // A null param is equivalent to srcBands == dstBands == null.
        int[] srcBands = null;
        int[] dstBands = null;
        if (param != null) {
            srcBands = param.getSourceBands();
            dstBands = param.getDestinationBands();
        }

        int paramSrcBandLength =
            (srcBands == null) ? numSrcBands : srcBands.length;
        int paramDstBandLength =
            (dstBands == null) ? numDstBands : dstBands.length;

        if (paramSrcBandLength != paramDstBandLength) {
            throw new IllegalArgumentException("ImageReadParam num source & dest bands differ!");
        }

        if (srcBands != null) {
            for (int i = 0; i < srcBands.length; i++) {
                if (srcBands[i] >= numSrcBands) {
                    throw new IllegalArgumentException("ImageReadParam source bands contains a value >= the number of source bands!");
                }
            }
        }

        if (dstBands != null) {
            for (int i = 0; i < dstBands.length; i++) {
                if (dstBands[i] >= numDstBands) {
                    throw new IllegalArgumentException("ImageReadParam dest bands contains a value >= the number of dest bands!");
                }
            }
        }
    }

    
Returns the BufferedImage to which decoded pixel
data should be written.  The image is determined by inspecting
the supplied ImageReadParam if it is
non-null; if its getDestination
method returns a non-null value, that image is
simply returned.  Otherwise,
param.getDestinationType method is called to
determine if a particular image type has been specified.  If
so, the returned ImageTypeSpecifier is used after
checking that it is equal to one of those included in
imageTypes.
 If param is null or the above
steps have not yielded an image or an
ImageTypeSpecifier, the first value obtained from
the imageTypes parameter is used.  Typically, the
caller will set imageTypes to the value of
getImageTypes(imageIndex).
 Next, the dimensions of the image are determined by a call
to computeRegions.  The actual width and height of
the image being decoded are passed in as the width
and height parameters.
Params:
param – an ImageReadParam to be used to get
the destination image or image type, or null.
imageTypes – an Iterator of
ImageTypeSpecifiers indicating the legal image
types, with the default first.
width – the true width of the image or tile begin decoded.
height – the true width of the image or tile being decoded.
Throws:
IIOException – if the ImageTypeSpecifier
specified by param does not match any of the legal
ones from imageTypes.
IllegalArgumentException – if imageTypes
is null or empty, or if an object not of type
ImageTypeSpecifier is retrieved from it.
IllegalArgumentException – if the resulting image would
have a width or height less than 1.
IllegalArgumentException – if the product of
width and height is greater than
Integer.MAX_VALUE.
Returns:
the BufferedImage to which decoded pixel
data should be written./**
     * Returns the <code>BufferedImage</code> to which decoded pixel
     * data should be written.  The image is determined by inspecting
     * the supplied <code>ImageReadParam</code> if it is
     * non-<code>null</code>; if its <code>getDestination</code>
     * method returns a non-<code>null</code> value, that image is
     * simply returned.  Otherwise,
     * <code>param.getDestinationType</code> method is called to
     * determine if a particular image type has been specified.  If
     * so, the returned <code>ImageTypeSpecifier</code> is used after
     * checking that it is equal to one of those included in
     * <code>imageTypes</code>.
     *
     * <p> If <code>param</code> is <code>null</code> or the above
     * steps have not yielded an image or an
     * <code>ImageTypeSpecifier</code>, the first value obtained from
     * the <code>imageTypes</code> parameter is used.  Typically, the
     * caller will set <code>imageTypes</code> to the value of
     * <code>getImageTypes(imageIndex)</code>.
     *
     * <p> Next, the dimensions of the image are determined by a call
     * to <code>computeRegions</code>.  The actual width and height of
     * the image being decoded are passed in as the <code>width</code>
     * and <code>height</code> parameters.
     *
     * @param param an <code>ImageReadParam</code> to be used to get
     * the destination image or image type, or <code>null</code>.
     * @param imageTypes an <code>Iterator</code> of
     * <code>ImageTypeSpecifier</code>s indicating the legal image
     * types, with the default first.
     * @param width the true width of the image or tile begin decoded.
     * @param height the true width of the image or tile being decoded.
     *
     * @return the <code>BufferedImage</code> to which decoded pixel
     * data should be written.
     *
     * @exception IIOException if the <code>ImageTypeSpecifier</code>
     * specified by <code>param</code> does not match any of the legal
     * ones from <code>imageTypes</code>.
     * @exception IllegalArgumentException if <code>imageTypes</code>
     * is <code>null</code> or empty, or if an object not of type
     * <code>ImageTypeSpecifier</code> is retrieved from it.
     * @exception IllegalArgumentException if the resulting image would
     * have a width or height less than 1.
     * @exception IllegalArgumentException if the product of
     * <code>width</code> and <code>height</code> is greater than
     * <code>Integer.MAX_VALUE</code>.
     */
    protected static BufferedImage
        getDestination(ImageReadParam param,
                       Iterator<ImageTypeSpecifier> imageTypes,
                       int width, int height)
        throws IIOException {
        if (imageTypes == null || !imageTypes.hasNext()) {
            throw new IllegalArgumentException("imageTypes null or empty!");
        }
        if ((long)width*height > Integer.MAX_VALUE) {
            throw new IllegalArgumentException
                ("width*height > Integer.MAX_VALUE!");
        }

        BufferedImage dest = null;
        ImageTypeSpecifier imageType = null;

        // If param is non-null, use it
        if (param != null) {
            // Try to get the image itself
            dest = param.getDestination();
            if (dest != null) {
                return dest;
            }

            // No image, get the image type
            imageType = param.getDestinationType();
        }

        // No info from param, use fallback image type
        if (imageType == null) {
            Object o = imageTypes.next();
            if (!(o instanceof ImageTypeSpecifier)) {
                throw new IllegalArgumentException
                    ("Non-ImageTypeSpecifier retrieved from imageTypes!");
            }
            imageType = (ImageTypeSpecifier)o;
        } else {
            boolean foundIt = false;
            while (imageTypes.hasNext()) {
                ImageTypeSpecifier type =
                    (ImageTypeSpecifier)imageTypes.next();
                if (type.equals(imageType)) {
                    foundIt = true;
                    break;
                }
            }

            if (!foundIt) {
                throw new IIOException
                    ("Destination type from ImageReadParam does not match!");
            }
        }

        Rectangle srcRegion = new Rectangle(0,0,0,0);
        Rectangle destRegion = new Rectangle(0,0,0,0);
        computeRegions(param,
                       width,
                       height,
                       null,
                       srcRegion,
                       destRegion);

        int destWidth = destRegion.x + destRegion.width;
        int destHeight = destRegion.y + destRegion.height;
        // Create a new image based on the type specifier
        return imageType.createBufferedImage(destWidth, destHeight);
    }
}