/*
 * Copyright (c) 1999, 2013, 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.Dimension;
import java.awt.Rectangle;
import java.awt.image.BufferedImage;
import java.awt.image.RenderedImage;
import java.awt.image.Raster;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
import javax.imageio.event.IIOWriteWarningListener;
import javax.imageio.event.IIOWriteProgressListener;
import javax.imageio.metadata.IIOMetadata;
import javax.imageio.stream.ImageOutputStream;
import javax.imageio.spi.ImageWriterSpi;

An abstract superclass for encoding and writing images.  This class
must be subclassed by classes that write out images in the context
of the Java Image I/O framework.
 ImageWriter objects are normally instantiated by
the service provider class for the specific format.  Service
provider classes are registered with the IIORegistry,
which uses them for format recognition and presentation of
available format readers and writers.

See Also:
ImageReader
ImageWriteParam
IIORegistry
ImageWriterSpi/**
 * An abstract superclass for encoding and writing images.  This class
 * must be subclassed by classes that write out images in the context
 * of the Java Image I/O framework.
 *
 * <p> <code>ImageWriter</code> objects are normally instantiated by
 * the service provider class for the specific format.  Service
 * provider classes are registered with the <code>IIORegistry</code>,
 * which uses them for format recognition and presentation of
 * available format readers and writers.
 *
 * <p>
 *
 * @see ImageReader
 * @see ImageWriteParam
 * @see javax.imageio.spi.IIORegistry
 * @see javax.imageio.spi.ImageWriterSpi
 *
 */
public abstract class ImageWriter implements ImageTranscoder {

    
The ImageWriterSpi that instantiated this object,
or null if its identity is not known or none
exists.  By default it is initialized to null.
/**
     * The <code>ImageWriterSpi</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 ImageWriterSpi originatingProvider = null;

    
The ImageOutputStream or other Object
set by setOutput and retrieved by
getOutput.  By default it is initialized to
null.
/**
     * The <code>ImageOutputStream</code> or other <code>Object</code>
     * set by <code>setOutput</code> and retrieved by
     * <code>getOutput</code>.  By default it is initialized to
     * <code>null</code>.
     */
    protected Object output = null;

    
An array of Locales that may be used to localize
warning messages and compression setting values, or
null if localization is not supported.  By default
it is initialized to null.
/**
     * An array of <code>Locale</code>s that may be used to localize
     * warning messages and compression setting values, or
     * <code>null</code> if localization is not supported.  By default
     * it is initialized to <code>null</code>.
     */
    protected Locale[] availableLocales = null;

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

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

    
A List of Locales, one for each
element of warningListeners, initialized by default
null, which is synonymous with an empty
List.
/**
     * A <code>List</code> of <code>Locale</code>s, one for each
     * element of <code>warningListeners</code>, initialized by default
     * <code>null</code>, which is synonymous with an empty
     * <code>List</code>.
     */
    protected List<Locale> warningLocales = null;

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

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

    
Constructs an ImageWriter and sets its
originatingProvider instance variable to the
supplied value.
 Subclasses that make use of extensions should provide a
constructor with signature (ImageWriterSpi,
Object) in order to retrieve the extension object.  If
the extension object is unsuitable, an
IllegalArgumentException should be thrown.
Params:
originatingProvider – the ImageWriterSpi that
is constructing this object, or null./**
     * Constructs an <code>ImageWriter</code> and sets its
     * <code>originatingProvider</code> instance variable to the
     * supplied value.
     *
     * <p> Subclasses that make use of extensions should provide a
     * constructor with signature <code>(ImageWriterSpi,
     * 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>ImageWriterSpi</code> that
     * is constructing this object, or <code>null</code>.
     */
    protected ImageWriter(ImageWriterSpi originatingProvider) {
        this.originatingProvider = originatingProvider;
    }

    
Returns the ImageWriterSpi object that created
this ImageWriter, or null if this
object was not created through the IIORegistry.
 The default implementation returns the value of the
originatingProvider instance variable.
See Also:
ImageWriterSpi
Returns:
an ImageWriterSpi, or null./**
     * Returns the <code>ImageWriterSpi</code> object that created
     * this <code>ImageWriter</code>, or <code>null</code> if this
     * object was not created through the <code>IIORegistry</code>.
     *
     * <p> The default implementation returns the value of the
     * <code>originatingProvider</code> instance variable.
     *
     * @return an <code>ImageWriterSpi</code>, or <code>null</code>.
     *
     * @see ImageWriterSpi
     */
    public ImageWriterSpi getOriginatingProvider() {
        return originatingProvider;
    }

    
Sets the destination to the given
ImageOutputStream or other Object.
The destination is assumed to be ready to accept data, and will
not be closed at the end of each write. This allows distributed
imaging applications to transmit a series of images over a
single network connection.  If output is
null, any currently set output will be removed.
 If output is an
ImageOutputStream, calls to the
write, writeToSequence, and
prepareWriteEmpty/endWriteEmpty
methods will preserve the existing contents of the stream.
Other write methods, such as writeInsert,
replaceStreamMetadata,
replaceImageMetadata, replacePixels,
prepareInsertEmpty/endInsertEmpty,
and endWriteSequence, require the full contents
of the stream to be readable and writable, and may alter any
portion of the stream.
 Use of a general Object other than an
ImageOutputStream is intended for writers that
interact directly with an output device or imaging protocol.
The set of legal classes is advertised by the writer's service
provider's getOutputTypes method; most writers
will return a single-element array containing only
ImageOutputStream.class to indicate that they
accept only an ImageOutputStream.
 The default implementation sets the output
instance variable to the value of output after
checking output against the set of classes
advertised by the originating provider, if there is one.
Params:
output – the ImageOutputStream or other
Object to use for future writing.
Throws:
IllegalArgumentException – if output is
not an instance of one of the classes returned by the
originating service provider's getOutputTypes
method.
See Also:
getOutput/**
     * Sets the destination to the given
     * <code>ImageOutputStream</code> or other <code>Object</code>.
     * The destination is assumed to be ready to accept data, and will
     * not be closed at the end of each write. This allows distributed
     * imaging applications to transmit a series of images over a
     * single network connection.  If <code>output</code> is
     * <code>null</code>, any currently set output will be removed.
     *
     * <p> If <code>output</code> is an
     * <code>ImageOutputStream</code>, calls to the
     * <code>write</code>, <code>writeToSequence</code>, and
     * <code>prepareWriteEmpty</code>/<code>endWriteEmpty</code>
     * methods will preserve the existing contents of the stream.
     * Other write methods, such as <code>writeInsert</code>,
     * <code>replaceStreamMetadata</code>,
     * <code>replaceImageMetadata</code>, <code>replacePixels</code>,
     * <code>prepareInsertEmpty</code>/<code>endInsertEmpty</code>,
     * and <code>endWriteSequence</code>, require the full contents
     * of the stream to be readable and writable, and may alter any
     * portion of the stream.
     *
     * <p> Use of a general <code>Object</code> other than an
     * <code>ImageOutputStream</code> is intended for writers that
     * interact directly with an output device or imaging protocol.
     * The set of legal classes is advertised by the writer's service
     * provider's <code>getOutputTypes</code> method; most writers
     * will return a single-element array containing only
     * <code>ImageOutputStream.class</code> to indicate that they
     * accept only an <code>ImageOutputStream</code>.
     *
     * <p> The default implementation sets the <code>output</code>
     * instance variable to the value of <code>output</code> after
     * checking <code>output</code> against the set of classes
     * advertised by the originating provider, if there is one.
     *
     * @param output the <code>ImageOutputStream</code> or other
     * <code>Object</code> to use for future writing.
     *
     * @exception IllegalArgumentException if <code>output</code> is
     * not an instance of one of the classes returned by the
     * originating service provider's <code>getOutputTypes</code>
     * method.
     *
     * @see #getOutput
     */
    public void setOutput(Object output) {
        if (output != null) {
            ImageWriterSpi provider = getOriginatingProvider();
            if (provider != null) {
                Class[] classes = provider.getOutputTypes();
                boolean found = false;
                for (int i = 0; i < classes.length; i++) {
                    if (classes[i].isInstance(output)) {
                        found = true;
                        break;
                    }
                }
                if (!found) {
                    throw new IllegalArgumentException("Illegal output type!");
                }
            }
        }

        this.output = output;
    }

    
Returns the ImageOutputStream or other
Object set by the most recent call to the
setOutput method.  If no destination has been
set, null is returned.
 The default implementation returns the value of the
output instance variable.
See Also:
setOutput
Returns:
the Object that was specified using
setOutput, or null./**
     * Returns the <code>ImageOutputStream</code> or other
     * <code>Object</code> set by the most recent call to the
     * <code>setOutput</code> method.  If no destination has been
     * set, <code>null</code> is returned.
     *
     * <p> The default implementation returns the value of the
     * <code>output</code> instance variable.
     *
     * @return the <code>Object</code> that was specified using
     * <code>setOutput</code>, or <code>null</code>.
     *
     * @see #setOutput
     */
    public Object getOutput() {
        return output;
    }

    // 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() {
        return (availableLocales == null) ?
            null : (Locale[])availableLocales.clone();
    }

    
Sets the current Locale of this
ImageWriter to the given value.  A value of
null removes any previous setting, and indicates
that the writer should localize as it sees fit.
 The default implementation checks locale
against the values returned by
getAvailableLocales, and sets the
locale instance variable if it is found.  If
locale is null, the instance variable
is set to null without any checking.
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>ImageWriter</code> to the given value.  A value of
     * <code>null</code> removes any previous setting, and indicates
     * that the writer should localize as it sees fit.
     *
     * <p> The default implementation checks <code>locale</code>
     * against the values returned by
     * <code>getAvailableLocales</code>, and sets the
     * <code>locale</code> instance variable if it is found.  If
     * <code>locale</code> is <code>null</code>, the instance variable
     * is set to <code>null</code> without any checking.
     *
     * @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.
 The default implementation returns the value of the
locale instance variable.
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.
     *
     * <p> The default implementation returns the value of the
     * <code>locale</code> instance variable.
     *
     * @return the current <code>Locale</code>, or <code>null</code>.
     *
     * @see #setLocale
     */
    public Locale getLocale() {
        return locale;
    }

    // Write params

    
Returns a new ImageWriteParam object of the
appropriate type for this file format containing default
values, that is, those values that would be used
if no ImageWriteParam object were specified.  This
is useful as a starting point for tweaking just a few parameters
and otherwise leaving the default settings alone.
 The default implementation constructs and returns a new
ImageWriteParam object that does not allow tiling,
progressive encoding, or compression, and that will be
localized for the current Locale (i.e.,
what you would get by calling new
ImageWriteParam(getLocale()).
 Individual plug-ins may return an instance of
ImageWriteParam with additional optional features
enabled, or they may return an instance of a plug-in specific
subclass of ImageWriteParam.
Returns:
a new ImageWriteParam object containing
default values./**
     * Returns a new <code>ImageWriteParam</code> object of the
     * appropriate type for this file format containing default
     * values, that is, those values that would be used
     * if no <code>ImageWriteParam</code> object were specified.  This
     * is useful as a starting point for tweaking just a few parameters
     * and otherwise leaving the default settings alone.
     *
     * <p> The default implementation constructs and returns a new
     * <code>ImageWriteParam</code> object that does not allow tiling,
     * progressive encoding, or compression, and that will be
     * localized for the current <code>Locale</code> (<i>i.e.</i>,
     * what you would get by calling <code>new
     * ImageWriteParam(getLocale())</code>.
     *
     * <p> Individual plug-ins may return an instance of
     * <code>ImageWriteParam</code> with additional optional features
     * enabled, or they may return an instance of a plug-in specific
     * subclass of <code>ImageWriteParam</code>.
     *
     * @return a new <code>ImageWriteParam</code> object containing
     * default values.
     */
    public ImageWriteParam getDefaultWriteParam() {
        return new ImageWriteParam(getLocale());
    }

    // Metadata

    
Returns an IIOMetadata object containing default
values for encoding a stream of images.  The contents of the
object may be manipulated using either the XML tree structure
returned by the IIOMetadata.getAsTree method, an
IIOMetadataController object, or via plug-in
specific interfaces, and the resulting data supplied to one of
the write methods that take a stream metadata
parameter.
 An optional ImageWriteParam may be supplied
for cases where it may affect the structure of the stream
metadata.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 Writers that do not make use of stream metadata
(e.g., writers for single-image formats) should return
null.
Params:
param – an ImageWriteParam that will be used to
encode the image, or null.
Returns:
an IIOMetadata object./**
     * Returns an <code>IIOMetadata</code> object containing default
     * values for encoding a stream of images.  The contents of the
     * object may be manipulated using either the XML tree structure
     * returned by the <code>IIOMetadata.getAsTree</code> method, an
     * <code>IIOMetadataController</code> object, or via plug-in
     * specific interfaces, and the resulting data supplied to one of
     * the <code>write</code> methods that take a stream metadata
     * parameter.
     *
     * <p> An optional <code>ImageWriteParam</code> may be supplied
     * for cases where it may affect the structure of the stream
     * metadata.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> Writers that do not make use of stream metadata
     * (<i>e.g.</i>, writers for single-image formats) should return
     * <code>null</code>.
     *
     * @param param an <code>ImageWriteParam</code> that will be used to
     * encode the image, or <code>null</code>.
     *
     * @return an <code>IIOMetadata</code> object.
     */
    public abstract IIOMetadata
        getDefaultStreamMetadata(ImageWriteParam param);

    
Returns an IIOMetadata object containing default
values for encoding an image of the given type.  The contents
of the object may be manipulated using either the XML tree
structure returned by the IIOMetadata.getAsTree
method, an IIOMetadataController object, or via
plug-in specific interfaces, and the resulting data supplied to
one of the write methods that take a stream
metadata parameter.
 An optional ImageWriteParam may be supplied
for cases where it may affect the structure of the image
metadata.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
Params:
imageType – an ImageTypeSpecifier indicating the
format of the image to be written later.
param – an ImageWriteParam that will be used to
encode the image, or null.
Returns:
an IIOMetadata object./**
     * Returns an <code>IIOMetadata</code> object containing default
     * values for encoding an image of the given type.  The contents
     * of the object may be manipulated using either the XML tree
     * structure returned by the <code>IIOMetadata.getAsTree</code>
     * method, an <code>IIOMetadataController</code> object, or via
     * plug-in specific interfaces, and the resulting data supplied to
     * one of the <code>write</code> methods that take a stream
     * metadata parameter.
     *
     * <p> An optional <code>ImageWriteParam</code> may be supplied
     * for cases where it may affect the structure of the image
     * metadata.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * @param imageType an <code>ImageTypeSpecifier</code> indicating the
     * format of the image to be written later.
     * @param param an <code>ImageWriteParam</code> that will be used to
     * encode the image, or <code>null</code>.
     *
     * @return an <code>IIOMetadata</code> object.
     */
    public abstract IIOMetadata
        getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                ImageWriteParam param);

    // comment inherited
    public abstract IIOMetadata convertStreamMetadata(IIOMetadata inData,
                                                      ImageWriteParam param);

    // comment inherited
    public abstract IIOMetadata
        convertImageMetadata(IIOMetadata inData,
                             ImageTypeSpecifier imageType,
                             ImageWriteParam param);

    // Thumbnails

    
Returns the number of thumbnails supported by the format being
written, given the image type and any additional write
parameters and metadata objects that will be used during
encoding.  A return value of -1 indicates that
insufficient information is available.
 An ImageWriteParam may optionally be supplied
for cases where it may affect thumbnail handling.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation returns 0.
Params:
imageType – an ImageTypeSpecifier indicating
the type of image to be written, or null.
param – the ImageWriteParam that will be used for
writing, or null.
streamMetadata – an IIOMetadata object that will
be used for writing, or null.
imageMetadata – an IIOMetadata object that will
be used for writing, or null.
Returns:
the number of thumbnails that may be written given the
supplied parameters, or -1 if insufficient
information is available./**
     * Returns the number of thumbnails supported by the format being
     * written, given the image type and any additional write
     * parameters and metadata objects that will be used during
     * encoding.  A return value of <code>-1</code> indicates that
     * insufficient information is available.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * for cases where it may affect thumbnail handling.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation returns 0.
     *
     * @param imageType an <code>ImageTypeSpecifier</code> indicating
     * the type of image to be written, or <code>null</code>.
     * @param param the <code>ImageWriteParam</code> that will be used for
     * writing, or <code>null</code>.
     * @param streamMetadata an <code>IIOMetadata</code> object that will
     * be used for writing, or <code>null</code>.
     * @param imageMetadata an <code>IIOMetadata</code> object that will
     * be used for writing, or <code>null</code>.
     *
     * @return the number of thumbnails that may be written given the
     * supplied parameters, or <code>-1</code> if insufficient
     * information is available.
     */
    public int getNumThumbnailsSupported(ImageTypeSpecifier imageType,
                                         ImageWriteParam param,
                                         IIOMetadata streamMetadata,
                                         IIOMetadata imageMetadata) {
        return 0;
    }

    
Returns an array of Dimensions indicating the
legal size ranges for thumbnail images as they will be encoded
in the output file or stream.  This information is merely
advisory; the writer will resize any supplied thumbnails as
necessary.
 The information is returned as a set of pairs; the first
element of a pair contains an (inclusive) minimum width and
height, and the second element contains an (inclusive) maximum
width and height.  Together, each pair defines a valid range of
sizes.  To specify a fixed size, the same width and height will
appear for both elements.  A return value of null
indicates that the size is arbitrary or unknown.
 An ImageWriteParam may optionally be supplied
for cases where it may affect thumbnail handling.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation returns null.
Params:
imageType – an ImageTypeSpecifier indicating the
type of image to be written, or null.
param – the ImageWriteParam that will be used for
writing, or null.
streamMetadata – an IIOMetadata object that will
be used for writing, or null.
imageMetadata – an IIOMetadata object that will
be used for writing, or null.
Returns:
an array of Dimensions with an even length
of at least two, or null./**
     * Returns an array of <code>Dimension</code>s indicating the
     * legal size ranges for thumbnail images as they will be encoded
     * in the output file or stream.  This information is merely
     * advisory; the writer will resize any supplied thumbnails as
     * necessary.
     *
     * <p> The information is returned as a set of pairs; the first
     * element of a pair contains an (inclusive) minimum width and
     * height, and the second element contains an (inclusive) maximum
     * width and height.  Together, each pair defines a valid range of
     * sizes.  To specify a fixed size, the same width and height will
     * appear for both elements.  A return value of <code>null</code>
     * indicates that the size is arbitrary or unknown.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * for cases where it may affect thumbnail handling.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation returns <code>null</code>.
     *
     * @param imageType an <code>ImageTypeSpecifier</code> indicating the
     * type of image to be written, or <code>null</code>.
     * @param param the <code>ImageWriteParam</code> that will be used for
     * writing, or <code>null</code>.
     * @param streamMetadata an <code>IIOMetadata</code> object that will
     * be used for writing, or <code>null</code>.
     * @param imageMetadata an <code>IIOMetadata</code> object that will
     * be used for writing, or <code>null</code>.
     *
     * @return an array of <code>Dimension</code>s with an even length
     * of at least two, or <code>null</code>.
     */
    public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
                                                  ImageWriteParam param,
                                                  IIOMetadata streamMetadata,
                                                  IIOMetadata imageMetadata) {
        return null;
    }

    
Returns true if the methods that take an
IIOImage parameter are capable of dealing with a
Raster (as opposed to RenderedImage)
source image.  If this method returns false, then
those methods will throw an
UnsupportedOperationException if supplied with an
IIOImage containing a Raster.
 The default implementation returns false.
Returns:
true if Raster sources are
supported./**
     * Returns <code>true</code> if the methods that take an
     * <code>IIOImage</code> parameter are capable of dealing with a
     * <code>Raster</code> (as opposed to <code>RenderedImage</code>)
     * source image.  If this method returns <code>false</code>, then
     * those methods will throw an
     * <code>UnsupportedOperationException</code> if supplied with an
     * <code>IIOImage</code> containing a <code>Raster</code>.
     *
     * <p> The default implementation returns <code>false</code>.
     *
     * @return <code>true</code> if <code>Raster</code> sources are
     * supported.
     */
    public boolean canWriteRasters() {
        return false;
    }

    
Appends a complete image stream containing a single image and
associated stream and image metadata and thumbnails to the
output.  Any necessary header information is included.  If the
output is an ImageOutputStream, its existing
contents prior to the current seek position are not affected,
and need not be readable or writable.
 The output must have been set beforehand using the
setOutput method.
 Stream metadata may optionally be supplied; if it is
null, default stream metadata will be used.
 If canWriteRasters returns true,
the IIOImage may contain a Raster
source.  Otherwise, it must contain a
RenderedImage source.
 The supplied thumbnails will be resized if needed, and any
thumbnails in excess of the supported number will be ignored.
If the format requires additional thumbnails that are not
provided, the writer should generate them internally.
  An ImageWriteParam may
optionally be supplied to control the writing process.  If
param is null, a default write param
will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
Params:
streamMetadata – an IIOMetadata object representing
stream metadata, or null to use default values.
image – an IIOImage object containing an
image, thumbnails, and metadata to be written.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if image
contains a Raster and canWriteRasters
returns false.
IllegalArgumentException – if image is
null.
IOException – if an error occurs during writing./**
     * Appends a complete image stream containing a single image and
     * associated stream and image metadata and thumbnails to the
     * output.  Any necessary header information is included.  If the
     * output is an <code>ImageOutputStream</code>, its existing
     * contents prior to the current seek position are not affected,
     * and need not be readable or writable.
     *
     * <p> The output must have been set beforehand using the
     * <code>setOutput</code> method.
     *
     * <p> Stream metadata may optionally be supplied; if it is
     * <code>null</code>, default stream metadata will be used.
     *
     * <p> If <code>canWriteRasters</code> returns <code>true</code>,
     * the <code>IIOImage</code> may contain a <code>Raster</code>
     * source.  Otherwise, it must contain a
     * <code>RenderedImage</code> source.
     *
     * <p> The supplied thumbnails will be resized if needed, and any
     * thumbnails in excess of the supported number will be ignored.
     * If the format requires additional thumbnails that are not
     * provided, the writer should generate them internally.
     *
     * <p>  An <code>ImageWriteParam</code> may
     * optionally be supplied to control the writing process.  If
     * <code>param</code> is <code>null</code>, a default write param
     * will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * @param streamMetadata an <code>IIOMetadata</code> object representing
     * stream metadata, or <code>null</code> to use default values.
     * @param image an <code>IIOImage</code> object containing an
     * image, thumbnails, and metadata to be written.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if <code>image</code>
     * contains a <code>Raster</code> and <code>canWriteRasters</code>
     * returns <code>false</code>.
     * @exception IllegalArgumentException if <code>image</code> is
     * <code>null</code>.
     * @exception IOException if an error occurs during writing.
     */
    public abstract void write(IIOMetadata streamMetadata,
                               IIOImage image,
                               ImageWriteParam param) throws IOException;

    
Appends a complete image stream containing a single image with
default metadata and thumbnails to the output.  This method is
a shorthand for write(null, image, null).
Params:
image – an IIOImage object containing an
image, thumbnails, and metadata to be written.
Throws:
IllegalStateException – if the output has not
been set.
IllegalArgumentException – if image is
null.
UnsupportedOperationException – if image
contains a Raster and canWriteRasters
returns false.
IOException – if an error occurs during writing./**
     * Appends a complete image stream containing a single image with
     * default metadata and thumbnails to the output.  This method is
     * a shorthand for <code>write(null, image, null)</code>.
     *
     * @param image an <code>IIOImage</code> object containing an
     * image, thumbnails, and metadata to be written.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IllegalArgumentException if <code>image</code> is
     * <code>null</code>.
     * @exception UnsupportedOperationException if <code>image</code>
     * contains a <code>Raster</code> and <code>canWriteRasters</code>
     * returns <code>false</code>.
     * @exception IOException if an error occurs during writing.
     */
    public void write(IIOImage image) throws IOException {
        write(null, image, null);
    }

    
Appends a complete image stream consisting of a single image
with default metadata and thumbnails to the output.  This
method is a shorthand for write(null, new IIOImage(image,
null, null), null).
Params:
image – a RenderedImage to be written.
Throws:
IllegalStateException – if the output has not
been set.
IllegalArgumentException – if image is
null.
IOException – if an error occurs during writing./**
     * Appends a complete image stream consisting of a single image
     * with default metadata and thumbnails to the output.  This
     * method is a shorthand for <code>write(null, new IIOImage(image,
     * null, null), null)</code>.
     *
     * @param image a <code>RenderedImage</code> to be written.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IllegalArgumentException if <code>image</code> is
     * <code>null</code>.
     * @exception IOException if an error occurs during writing.
     */
    public void write(RenderedImage image) throws IOException {
        write(null, new IIOImage(image, null, null), null);
    }

    // Check that the output has been set, then throw an
    // UnsupportedOperationException.
    private void unsupported() {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        throw new UnsupportedOperationException("Unsupported write variant!");
    }

    // Sequence writes

    
Returns true if the writer is able to append an
image to an image stream that already contains header
information and possibly prior images.
 If canWriteSequence returns false,
writeToSequence and endWriteSequence
will throw an UnsupportedOperationException.
 The default implementation returns false.
Returns:
true if images may be appended sequentially./**
     * Returns <code>true</code> if the writer is able to append an
     * image to an image stream that already contains header
     * information and possibly prior images.
     *
     * <p> If <code>canWriteSequence</code> returns <code>false</code>,
     * <code>writeToSequence</code> and <code>endWriteSequence</code>
     * will throw an <code>UnsupportedOperationException</code>.
     *
     * <p> The default implementation returns <code>false</code>.
     *
     * @return <code>true</code> if images may be appended sequentially.
     */
    public boolean canWriteSequence() {
        return false;
    }

    
Prepares a stream to accept a series of subsequent
writeToSequence calls, using the provided stream
metadata object.  The metadata will be written to the stream if
it should precede the image data.  If the argument is null,
default stream metadata is used.
 If the output is an ImageOutputStream, the existing
contents of the output prior to the current seek position are
flushed, and need not be readable or writable.  If the format
requires that endWriteSequence be able to rewind to
patch up the header information, such as for a sequence of images
in a single TIFF file, then the metadata written by this method
must remain in a writable portion of the stream.  Other formats
may flush the stream after this method and after each image.
 If canWriteSequence returns false,
this method will throw an
UnsupportedOperationException.
 The output must have been set beforehand using either
the setOutput method.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
streamMetadata – A stream metadata object, or null.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canWriteSequence returns false.
IOException – if an error occurs writing the stream
metadata./**
     * Prepares a stream to accept a series of subsequent
     * <code>writeToSequence</code> calls, using the provided stream
     * metadata object.  The metadata will be written to the stream if
     * it should precede the image data.  If the argument is <code>null</code>,
     * default stream metadata is used.
     *
     * <p> If the output is an <code>ImageOutputStream</code>, the existing
     * contents of the output prior to the current seek position are
     * flushed, and need not be readable or writable.  If the format
     * requires that <code>endWriteSequence</code> be able to rewind to
     * patch up the header information, such as for a sequence of images
     * in a single TIFF file, then the metadata written by this method
     * must remain in a writable portion of the stream.  Other formats
     * may flush the stream after this method and after each image.
     *
     * <p> If <code>canWriteSequence</code> returns <code>false</code>,
     * this method will throw an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> The output must have been set beforehand using either
     * the <code>setOutput</code> method.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param streamMetadata A stream metadata object, or <code>null</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canWriteSequence</code> returns <code>false</code>.
     * @exception IOException if an error occurs writing the stream
     * metadata.
     */
    public void prepareWriteSequence(IIOMetadata streamMetadata)
        throws IOException {
        unsupported();
    }

    
Appends a single image and possibly associated metadata and
thumbnails, to the output.  If the output is an
ImageOutputStream, the existing contents of the
output prior to the current seek position may be flushed, and
need not be readable or writable, unless the plug-in needs to
be able to patch up the header information when
endWriteSequence is called (e.g. TIFF).
 If canWriteSequence returns false,
this method will throw an
UnsupportedOperationException.
 The output must have been set beforehand using
the setOutput method.
 prepareWriteSequence must have been called
beforehand, or an IllegalStateException is thrown.
 If canWriteRasters returns true,
the IIOImage may contain a Raster
source.  Otherwise, it must contain a
RenderedImage source.
 The supplied thumbnails will be resized if needed, and any
thumbnails in excess of the supported number will be ignored.
If the format requires additional thumbnails that are not
provided, the writer will generate them internally.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
image – an IIOImage object containing an
image, thumbnails, and metadata to be written.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set, or prepareWriteSequence has not been called.
UnsupportedOperationException – if
canWriteSequence returns false.
IllegalArgumentException – if image is
null.
UnsupportedOperationException – if image
contains a Raster and canWriteRasters
returns false.
IOException – if an error occurs during writing./**
     * Appends a single image and possibly associated metadata and
     * thumbnails, to the output.  If the output is an
     * <code>ImageOutputStream</code>, the existing contents of the
     * output prior to the current seek position may be flushed, and
     * need not be readable or writable, unless the plug-in needs to
     * be able to patch up the header information when
     * <code>endWriteSequence</code> is called (<i>e.g.</i> TIFF).
     *
     * <p> If <code>canWriteSequence</code> returns <code>false</code>,
     * this method will throw an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> The output must have been set beforehand using
     * the <code>setOutput</code> method.
     *
     * <p> <code>prepareWriteSequence</code> must have been called
     * beforehand, or an <code>IllegalStateException</code> is thrown.
     *
     * <p> If <code>canWriteRasters</code> returns <code>true</code>,
     * the <code>IIOImage</code> may contain a <code>Raster</code>
     * source.  Otherwise, it must contain a
     * <code>RenderedImage</code> source.
     *
     * <p> The supplied thumbnails will be resized if needed, and any
     * thumbnails in excess of the supported number will be ignored.
     * If the format requires additional thumbnails that are not
     * provided, the writer will generate them internally.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param image an <code>IIOImage</code> object containing an
     * image, thumbnails, and metadata to be written.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set, or <code>prepareWriteSequence</code> has not been called.
     * @exception UnsupportedOperationException if
     * <code>canWriteSequence</code> returns <code>false</code>.
     * @exception IllegalArgumentException if <code>image</code> is
     * <code>null</code>.
     * @exception UnsupportedOperationException if <code>image</code>
     * contains a <code>Raster</code> and <code>canWriteRasters</code>
     * returns <code>false</code>.
     * @exception IOException if an error occurs during writing.
     */
    public void writeToSequence(IIOImage image, ImageWriteParam param)
        throws IOException {
        unsupported();
    }

    
Completes the writing of a sequence of images begun with
prepareWriteSequence.  Any stream metadata that
should come at the end of the sequence of images is written out,
and any header information at the beginning of the sequence is
patched up if necessary.  If the output is an
ImageOutputStream, data through the stream metadata
at the end of the sequence are flushed and need not be readable
or writable.
 If canWriteSequence returns false,
this method will throw an
UnsupportedOperationException.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Throws:
IllegalStateException – if the output has not
been set, or prepareWriteSequence has not been called.
UnsupportedOperationException – if
canWriteSequence returns false.
IOException – if an error occurs during writing./**
     * Completes the writing of a sequence of images begun with
     * <code>prepareWriteSequence</code>.  Any stream metadata that
     * should come at the end of the sequence of images is written out,
     * and any header information at the beginning of the sequence is
     * patched up if necessary.  If the output is an
     * <code>ImageOutputStream</code>, data through the stream metadata
     * at the end of the sequence are flushed and need not be readable
     * or writable.
     *
     * <p> If <code>canWriteSequence</code> returns <code>false</code>,
     * this method will throw an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set, or <code>prepareWriteSequence</code> has not been called.
     * @exception UnsupportedOperationException if
     * <code>canWriteSequence</code> returns <code>false</code>.
     * @exception IOException if an error occurs during writing.
     */
    public void endWriteSequence() throws IOException {
        unsupported();
    }

    // Metadata replacement

    
Returns true if it is possible to replace the
stream metadata already present in the output.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false.
Throws:
IllegalStateException – if the output has not
been set.
IOException – if an I/O error occurs during the query.
Returns:
true if replacement of stream metadata is
allowed./**
     * Returns <code>true</code> if it is possible to replace the
     * stream metadata already present in the output.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>.
     *
     * @return <code>true</code> if replacement of stream metadata is
     * allowed.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IOException if an I/O error occurs during the query.
     */
    public boolean canReplaceStreamMetadata() throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Replaces the stream metadata in the output with new
information.  If the output is an
ImageOutputStream, the prior contents of the
stream are examined and possibly edited to make room for the
new data.  All of the prior contents of the output must be
available for reading and writing.
 If canReplaceStreamMetadata returns
false, an
UnsupportedOperationException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
streamMetadata – an IIOMetadata object representing
stream metadata, or null to use default values.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if the
canReplaceStreamMetadata returns
false.  modes do not include
IOException – if an error occurs during writing./**
     * Replaces the stream metadata in the output with new
     * information.  If the output is an
     * <code>ImageOutputStream</code>, the prior contents of the
     * stream are examined and possibly edited to make room for the
     * new data.  All of the prior contents of the output must be
     * available for reading and writing.
     *
     * <p> If <code>canReplaceStreamMetadata</code> returns
     * <code>false</code>, an
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param streamMetadata an <code>IIOMetadata</code> object representing
     * stream metadata, or <code>null</code> to use default values.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if the
     * <code>canReplaceStreamMetadata</code> returns
     * <code>false</code>.  modes do not include
     * @exception IOException if an error occurs during writing.
     */
    public void replaceStreamMetadata(IIOMetadata streamMetadata)
        throws IOException {
        unsupported();
    }

    
Returns true if it is possible to replace the
image metadata associated with an existing image with index
imageIndex.  If this method returns
false, a call to
replaceImageMetadata(imageIndex) will throw an
UnsupportedOperationException.
 A writer that does not support any image metadata
replacement may return false without performing
bounds checking on the index.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false
without checking the value of imageIndex.
Params:
imageIndex – the index of the image whose metadata is to
be replaced.
Throws:
IllegalStateException – if the output has not
been set.
IndexOutOfBoundsException – if the writer supports
image metadata replacement in general, but
imageIndex is less than 0 or greater than the
largest available index.
IOException – if an I/O error occurs during the query.
Returns:
true if the image metadata of the given
image can be replaced./**
     * Returns <code>true</code> if it is possible to replace the
     * image metadata associated with an existing image with index
     * <code>imageIndex</code>.  If this method returns
     * <code>false</code>, a call to
     * <code>replaceImageMetadata(imageIndex)</code> will throw an
     * <code>UnsupportedOperationException</code>.
     *
     * <p> A writer that does not support any image metadata
     * replacement may return <code>false</code> without performing
     * bounds checking on the index.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>
     * without checking the value of <code>imageIndex</code>.
     *
     * @param imageIndex the index of the image whose metadata is to
     * be replaced.
     *
     * @return <code>true</code> if the image metadata of the given
     * image can be replaced.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IndexOutOfBoundsException if the writer supports
     * image metadata replacement in general, but
     * <code>imageIndex</code> is less than 0 or greater than the
     * largest available index.
     * @exception IOException if an I/O error occurs during the query.
     */
    public boolean canReplaceImageMetadata(int imageIndex)
        throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Replaces the image metadata associated with an existing image.
 If canReplaceImageMetadata(imageIndex) returns
false, an
UnsupportedOperationException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
imageIndex – the index of the image whose metadata is to
be replaced.
imageMetadata – an IIOMetadata object
representing image metadata, or null.
Throws:
IllegalStateException – if the output has not been
set.
UnsupportedOperationException – if
canReplaceImageMetadata returns
false.
IndexOutOfBoundsException – if imageIndex
is less than 0 or greater than the largest available index.
IOException – if an error occurs during writing./**
     * Replaces the image metadata associated with an existing image.
     *
     * <p> If <code>canReplaceImageMetadata(imageIndex)</code> returns
     * <code>false</code>, an
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index of the image whose metadata is to
     * be replaced.
     * @param imageMetadata an <code>IIOMetadata</code> object
     * representing image metadata, or <code>null</code>.
     *
     * @exception IllegalStateException if the output has not been
     * set.
     * @exception UnsupportedOperationException if
     * <code>canReplaceImageMetadata</code> returns
     * <code>false</code>.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is less than 0 or greater than the largest available index.
     * @exception IOException if an error occurs during writing.
     */
    public void replaceImageMetadata(int imageIndex,
                                     IIOMetadata imageMetadata)
        throws IOException {
        unsupported();
    }

    // Image insertion

    
Returns true if the writer supports the insertion
of a new image at the given index.  Existing images with
indices greater than or equal to the insertion index will have
their indices increased by 1.  A value for
imageIndex of -1 may be used to
signify an index one larger than the current largest index.
 A writer that does not support any image insertion may
return false without performing bounds checking on
the index.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false
without checking the value of imageIndex.
Params:
imageIndex – the index at which the image is to be
inserted.
Throws:
IllegalStateException – if the output has not
been set.
IndexOutOfBoundsException – if the writer supports
image insertion in general, but imageIndex is less
than -1 or greater than the largest available index.
IOException – if an I/O error occurs during the query.
Returns:
true if an image may be inserted at the
given index./**
     * Returns <code>true</code> if the writer supports the insertion
     * of a new image at the given index.  Existing images with
     * indices greater than or equal to the insertion index will have
     * their indices increased by 1.  A value for
     * <code>imageIndex</code> of <code>-1</code> may be used to
     * signify an index one larger than the current largest index.
     *
     * <p> A writer that does not support any image insertion may
     * return <code>false</code> without performing bounds checking on
     * the index.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>
     * without checking the value of <code>imageIndex</code>.
     *
     * @param imageIndex the index at which the image is to be
     * inserted.
     *
     * @return <code>true</code> if an image may be inserted at the
     * given index.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IndexOutOfBoundsException if the writer supports
     * image insertion in general, but <code>imageIndex</code> is less
     * than -1 or greater than the largest available index.
     * @exception IOException if an I/O error occurs during the query.
     */
    public boolean canInsertImage(int imageIndex) throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Inserts a new image into an existing image stream.  Existing
images with an index greater than imageIndex are
preserved, and their indices are each increased by 1.  A value
for imageIndex of -1 may be used to signify an
index one larger than the previous largest index; that is, it
will cause the image to be logically appended to the end of the
sequence.  If the output is an ImageOutputStream,
the entirety of the stream must be both readable and writeable.
 If canInsertImage(imageIndex) returns
false, an
UnsupportedOperationException will be thrown.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
imageIndex – the index at which to write the image.
image – an IIOImage object containing an
image, thumbnails, and metadata to be written.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canInsertImage(imageIndex) returns false.
IllegalArgumentException – if image is
null.
IndexOutOfBoundsException – if imageIndex
is less than -1 or greater than the largest available index.
UnsupportedOperationException – if image
contains a Raster and canWriteRasters
returns false.
IOException – if an error occurs during writing./**
     * Inserts a new image into an existing image stream.  Existing
     * images with an index greater than <code>imageIndex</code> are
     * preserved, and their indices are each increased by 1.  A value
     * for <code>imageIndex</code> of -1 may be used to signify an
     * index one larger than the previous largest index; that is, it
     * will cause the image to be logically appended to the end of the
     * sequence.  If the output is an <code>ImageOutputStream</code>,
     * the entirety of the stream must be both readable and writeable.
     *
     * <p> If <code>canInsertImage(imageIndex)</code> returns
     * <code>false</code>, an
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index at which to write the image.
     * @param image an <code>IIOImage</code> object containing an
     * image, thumbnails, and metadata to be written.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canInsertImage(imageIndex)</code> returns <code>false</code>.
     * @exception IllegalArgumentException if <code>image</code> is
     * <code>null</code>.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is less than -1 or greater than the largest available index.
     * @exception UnsupportedOperationException if <code>image</code>
     * contains a <code>Raster</code> and <code>canWriteRasters</code>
     * returns <code>false</code>.
     * @exception IOException if an error occurs during writing.
     */
    public void writeInsert(int imageIndex,
                            IIOImage image,
                            ImageWriteParam param) throws IOException {
        unsupported();
    }

    // Image removal

    
Returns true if the writer supports the removal
of an existing image at the given index.  Existing images with
indices greater than the insertion index will have
their indices decreased by 1.
 A writer that does not support any image removal may
return false without performing bounds checking on
the index.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false
without checking the value of imageIndex.
Params:
imageIndex – the index of the image to be removed.
Throws:
IllegalStateException – if the output has not
been set.
IndexOutOfBoundsException – if the writer supports
image removal in general, but imageIndex is less
than 0 or greater than the largest available index.
IOException – if an I/O error occurs during the
query.
Returns:
true if it is possible to remove the given
image./**
     * Returns <code>true</code> if the writer supports the removal
     * of an existing image at the given index.  Existing images with
     * indices greater than the insertion index will have
     * their indices decreased by 1.
     *
     * <p> A writer that does not support any image removal may
     * return <code>false</code> without performing bounds checking on
     * the index.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>
     * without checking the value of <code>imageIndex</code>.
     *
     * @param imageIndex the index of the image to be removed.
     *
     * @return <code>true</code> if it is possible to remove the given
     * image.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception IndexOutOfBoundsException if the writer supports
     * image removal in general, but <code>imageIndex</code> is less
     * than 0 or greater than the largest available index.
     * @exception IOException if an I/O error occurs during the
     * query.
     */
    public boolean canRemoveImage(int imageIndex) throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Removes an image from the stream.
 If canRemoveImage(imageIndex) returns false,
an UnsupportedOperationExceptionwill be thrown.
 The removal may or may not cause a reduction in the actual
file size.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
imageIndex – the index of the image to be removed.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canRemoveImage(imageIndex) returns false.
IndexOutOfBoundsException – if imageIndex
is less than 0 or greater than the largest available index.
IOException – if an I/O error occurs during the
removal./**
     * Removes an image from the stream.
     *
     * <p> If <code>canRemoveImage(imageIndex)</code> returns false,
     * an <code>UnsupportedOperationException</code>will be thrown.
     *
     * <p> The removal may or may not cause a reduction in the actual
     * file size.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index of the image to be removed.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canRemoveImage(imageIndex)</code> returns <code>false</code>.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is less than 0 or greater than the largest available index.
     * @exception IOException if an I/O error occurs during the
     * removal.
     */
    public void removeImage(int imageIndex) throws IOException {
        unsupported();
    }

    // Empty images

    
Returns true if the writer supports the writing of
a complete image stream consisting of a single image with
undefined pixel values and associated metadata and thumbnails
to the output.  The pixel values may be defined by future
calls to the replacePixels methods.  If the output
is an ImageOutputStream, its existing contents
prior to the current seek position are not affected, and need
not be readable or writable.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false.
Throws:
IllegalStateException – if the output has not been
set.
IOException – if an I/O error occurs during the
query.
Returns:
true if the writing of complete image
stream with contents to be defined later is supported./**
     * Returns <code>true</code> if the writer supports the writing of
     * a complete image stream consisting of a single image with
     * undefined pixel values and associated metadata and thumbnails
     * to the output.  The pixel values may be defined by future
     * calls to the <code>replacePixels</code> methods.  If the output
     * is an <code>ImageOutputStream</code>, its existing contents
     * prior to the current seek position are not affected, and need
     * not be readable or writable.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>.
     *
     * @return <code>true</code> if the writing of complete image
     * stream with contents to be defined later is supported.
     *
     * @exception IllegalStateException if the output has not been
     * set.
     * @exception IOException if an I/O error occurs during the
     * query.
     */
    public boolean canWriteEmpty() throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Begins the writing of a complete image stream, consisting of a
single image with undefined pixel values and associated
metadata and thumbnails, to the output.  The pixel values will
be defined by future calls to the replacePixels
methods.  If the output is an ImageOutputStream,
its existing contents prior to the current seek position are
not affected, and need not be readable or writable.
 The writing is not complete until a call to
endWriteEmpty occurs.  Calls to
prepareReplacePixels, replacePixels,
and endReplacePixels may occur between calls to
prepareWriteEmpty and endWriteEmpty.
However, calls to prepareWriteEmpty cannot be
nested, and calls to prepareWriteEmpty and
prepareInsertEmpty may not be interspersed.
 If canWriteEmpty returns false,
an UnsupportedOperationException will be thrown.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
streamMetadata – an IIOMetadata object representing
stream metadata, or null to use default values.
imageType – an ImageTypeSpecifier describing
the layout of the image.
width – the width of the image.
height – the height of the image.
imageMetadata – an IIOMetadata object
representing image metadata, or null.
thumbnails – a List of
BufferedImage thumbnails for this image, or
null.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canWriteEmpty returns false.
IllegalStateException – if a previous call to
prepareWriteEmpty has been made without a
corresponding call to endWriteEmpty.
IllegalStateException – if a previous call to
prepareInsertEmpty has been made without a
corresponding call to endInsertEmpty.
IllegalArgumentException – if imageType
is null or thumbnails contains
null references or objects other than
BufferedImages.
IllegalArgumentException – if width or height are less
than 1.
IOException – if an I/O error occurs during writing./**
     * Begins the writing of a complete image stream, consisting of a
     * single image with undefined pixel values and associated
     * metadata and thumbnails, to the output.  The pixel values will
     * be defined by future calls to the <code>replacePixels</code>
     * methods.  If the output is an <code>ImageOutputStream</code>,
     * its existing contents prior to the current seek position are
     * not affected, and need not be readable or writable.
     *
     * <p> The writing is not complete until a call to
     * <code>endWriteEmpty</code> occurs.  Calls to
     * <code>prepareReplacePixels</code>, <code>replacePixels</code>,
     * and <code>endReplacePixels</code> may occur between calls to
     * <code>prepareWriteEmpty</code> and <code>endWriteEmpty</code>.
     * However, calls to <code>prepareWriteEmpty</code> cannot be
     * nested, and calls to <code>prepareWriteEmpty</code> and
     * <code>prepareInsertEmpty</code> may not be interspersed.
     *
     * <p> If <code>canWriteEmpty</code> returns <code>false</code>,
     * an <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param streamMetadata an <code>IIOMetadata</code> object representing
     * stream metadata, or <code>null</code> to use default values.
     * @param imageType an <code>ImageTypeSpecifier</code> describing
     * the layout of the image.
     * @param width the width of the image.
     * @param height the height of the image.
     * @param imageMetadata an <code>IIOMetadata</code> object
     * representing image metadata, or <code>null</code>.
     * @param thumbnails a <code>List</code> of
     * <code>BufferedImage</code> thumbnails for this image, or
     * <code>null</code>.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canWriteEmpty</code> returns <code>false</code>.
     * @exception IllegalStateException if a previous call to
     * <code>prepareWriteEmpty</code> has been made without a
     * corresponding call to <code>endWriteEmpty</code>.
     * @exception IllegalStateException if a previous call to
     * <code>prepareInsertEmpty</code> has been made without a
     * corresponding call to <code>endInsertEmpty</code>.
     * @exception IllegalArgumentException if <code>imageType</code>
     * is <code>null</code> or <code>thumbnails</code> contains
     * <code>null</code> references or objects other than
     * <code>BufferedImage</code>s.
     * @exception IllegalArgumentException if width or height are less
     * than 1.
     * @exception IOException if an I/O error occurs during writing.
     */
    public void prepareWriteEmpty(IIOMetadata streamMetadata,
                                  ImageTypeSpecifier imageType,
                                  int width, int height,
                                  IIOMetadata imageMetadata,
                                  List<? extends BufferedImage> thumbnails,
                                  ImageWriteParam param) throws IOException {
        unsupported();
    }

    
Completes the writing of a new image that was begun with a
prior call to prepareWriteEmpty.
 If canWriteEmpty() returns false,
an UnsupportedOperationException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canWriteEmpty(imageIndex) returns
false.
IllegalStateException – if a previous call to
prepareWriteEmpty without a corresponding call to
endWriteEmpty has not been made.
IllegalStateException – if a previous call to
prepareInsertEmpty without a corresponding call to
endInsertEmpty has been made.
IllegalStateException – if a call to
prepareReiplacePixels has been made without a
matching call to endReplacePixels.
IOException – if an I/O error occurs during writing./**
     * Completes the writing of a new image that was begun with a
     * prior call to <code>prepareWriteEmpty</code>.
     *
     * <p> If <code>canWriteEmpty()</code> returns <code>false</code>,
     * an <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canWriteEmpty(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IllegalStateException if a previous call to
     * <code>prepareWriteEmpty</code> without a corresponding call to
     * <code>endWriteEmpty</code> has not been made.
     * @exception IllegalStateException if a previous call to
     * <code>prepareInsertEmpty</code> without a corresponding call to
     * <code>endInsertEmpty</code> has been made.
     * @exception IllegalStateException if a call to
     * <code>prepareReiplacePixels</code> has been made without a
     * matching call to <code>endReplacePixels</code>.
     * @exception IOException if an I/O error occurs during writing.
     */
    public void endWriteEmpty() throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        throw new IllegalStateException("No call to prepareWriteEmpty!");
    }

    
Returns true if the writer supports the insertion
of a new, empty image at the given index.  The pixel values of
the image are undefined, and may be specified in pieces using
the replacePixels methods.  Existing images with
indices greater than or equal to the insertion index will have
their indices increased by 1.  A value for
imageIndex of -1 may be used to
signify an index one larger than the current largest index.
 A writer that does not support insertion of empty images
may return false without performing bounds
checking on the index.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false
without checking the value of imageIndex.
Params:
imageIndex – the index at which the image is to be
inserted.
Throws:
IllegalStateException – if the output has not been
set.
IndexOutOfBoundsException – if the writer supports
empty image insertion in general, but imageIndex
is less than -1 or greater than the largest available index.
IOException – if an I/O error occurs during the
query.
Returns:
true if an empty image may be inserted at
the given index./**
     * Returns <code>true</code> if the writer supports the insertion
     * of a new, empty image at the given index.  The pixel values of
     * the image are undefined, and may be specified in pieces using
     * the <code>replacePixels</code> methods.  Existing images with
     * indices greater than or equal to the insertion index will have
     * their indices increased by 1.  A value for
     * <code>imageIndex</code> of <code>-1</code> may be used to
     * signify an index one larger than the current largest index.
     *
     * <p> A writer that does not support insertion of empty images
     * may return <code>false</code> without performing bounds
     * checking on the index.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>
     * without checking the value of <code>imageIndex</code>.
     *
     * @param imageIndex the index at which the image is to be
     * inserted.
     *
     * @return <code>true</code> if an empty image may be inserted at
     * the given index.
     *
     * @exception IllegalStateException if the output has not been
     * set.
     * @exception IndexOutOfBoundsException if the writer supports
     * empty image insertion in general, but <code>imageIndex</code>
     * is less than -1 or greater than the largest available index.
     * @exception IOException if an I/O error occurs during the
     * query.
     */
    public boolean canInsertEmpty(int imageIndex) throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Begins the insertion of a new image with undefined pixel values
into an existing image stream.  Existing images with an index
greater than imageIndex are preserved, and their
indices are each increased by 1.  A value for
imageIndex of -1 may be used to signify an index
one larger than the previous largest index; that is, it will
cause the image to be logically appended to the end of the
sequence.  If the output is an ImageOutputStream,
the entirety of the stream must be both readable and writeable.
 The image contents may be
supplied later using the replacePixels method.
The insertion is not complete until a call to
endInsertEmpty occurs.  Calls to
prepareReplacePixels, replacePixels,
and endReplacePixels may occur between calls to
prepareInsertEmpty and
endInsertEmpty.  However, calls to
prepareInsertEmpty cannot be nested, and calls to
prepareWriteEmpty and
prepareInsertEmpty may not be interspersed.
 If canInsertEmpty(imageIndex) returns
false, an
UnsupportedOperationException will be thrown.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
imageIndex – the index at which to write the image.
imageType – an ImageTypeSpecifier describing
the layout of the image.
width – the width of the image.
height – the height of the image.
imageMetadata – an IIOMetadata object
representing image metadata, or null.
thumbnails – a List of
BufferedImage thumbnails for this image, or
null.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canInsertEmpty(imageIndex) returns
false.
IndexOutOfBoundsException – if imageIndex
is less than -1 or greater than the largest available index.
IllegalStateException – if a previous call to
prepareInsertEmpty has been made without a
corresponding call to endInsertEmpty.
IllegalStateException – if a previous call to
prepareWriteEmpty has been made without a
corresponding call to endWriteEmpty.
IllegalArgumentException – if imageType
is null or thumbnails contains
null references or objects other than
BufferedImages.
IllegalArgumentException – if width or height are less
than 1.
IOException – if an I/O error occurs during writing./**
     * Begins the insertion of a new image with undefined pixel values
     * into an existing image stream.  Existing images with an index
     * greater than <code>imageIndex</code> are preserved, and their
     * indices are each increased by 1.  A value for
     * <code>imageIndex</code> of -1 may be used to signify an index
     * one larger than the previous largest index; that is, it will
     * cause the image to be logically appended to the end of the
     * sequence.  If the output is an <code>ImageOutputStream</code>,
     * the entirety of the stream must be both readable and writeable.
     *
     * <p> The image contents may be
     * supplied later using the <code>replacePixels</code> method.
     * The insertion is not complete until a call to
     * <code>endInsertEmpty</code> occurs.  Calls to
     * <code>prepareReplacePixels</code>, <code>replacePixels</code>,
     * and <code>endReplacePixels</code> may occur between calls to
     * <code>prepareInsertEmpty</code> and
     * <code>endInsertEmpty</code>.  However, calls to
     * <code>prepareInsertEmpty</code> cannot be nested, and calls to
     * <code>prepareWriteEmpty</code> and
     * <code>prepareInsertEmpty</code> may not be interspersed.
     *
     * <p> If <code>canInsertEmpty(imageIndex)</code> returns
     * <code>false</code>, an
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index at which to write the image.
     * @param imageType an <code>ImageTypeSpecifier</code> describing
     * the layout of the image.
     * @param width the width of the image.
     * @param height the height of the image.
     * @param imageMetadata an <code>IIOMetadata</code> object
     * representing image metadata, or <code>null</code>.
     * @param thumbnails a <code>List</code> of
     * <code>BufferedImage</code> thumbnails for this image, or
     * <code>null</code>.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canInsertEmpty(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is less than -1 or greater than the largest available index.
     * @exception IllegalStateException if a previous call to
     * <code>prepareInsertEmpty</code> has been made without a
     * corresponding call to <code>endInsertEmpty</code>.
     * @exception IllegalStateException if a previous call to
     * <code>prepareWriteEmpty</code> has been made without a
     * corresponding call to <code>endWriteEmpty</code>.
     * @exception IllegalArgumentException if <code>imageType</code>
     * is <code>null</code> or <code>thumbnails</code> contains
     * <code>null</code> references or objects other than
     * <code>BufferedImage</code>s.
     * @exception IllegalArgumentException if width or height are less
     * than 1.
     * @exception IOException if an I/O error occurs during writing.
     */
    public void prepareInsertEmpty(int imageIndex,
                                   ImageTypeSpecifier imageType,
                                   int width, int height,
                                   IIOMetadata imageMetadata,
                                   List<? extends BufferedImage> thumbnails,
                                   ImageWriteParam param) throws IOException {
        unsupported();
    }

    
Completes the insertion of a new image that was begun with a
prior call to prepareInsertEmpty.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canInsertEmpty(imageIndex) returns
false.
IllegalStateException – if a previous call to
prepareInsertEmpty without a corresponding call to
endInsertEmpty has not been made.
IllegalStateException – if a previous call to
prepareWriteEmpty without a corresponding call to
endWriteEmpty has been made.
IllegalStateException – if a call to
prepareReplacePixels has been made without a
matching call to endReplacePixels.
IOException – if an I/O error occurs during writing./**
     * Completes the insertion of a new image that was begun with a
     * prior call to <code>prepareInsertEmpty</code>.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canInsertEmpty(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IllegalStateException if a previous call to
     * <code>prepareInsertEmpty</code> without a corresponding call to
     * <code>endInsertEmpty</code> has not been made.
     * @exception IllegalStateException if a previous call to
     * <code>prepareWriteEmpty</code> without a corresponding call to
     * <code>endWriteEmpty</code> has been made.
     * @exception IllegalStateException if a call to
     * <code>prepareReplacePixels</code> has been made without a
     * matching call to <code>endReplacePixels</code>.
     * @exception IOException if an I/O error occurs during writing.
     */
    public void endInsertEmpty() throws IOException {
        unsupported();
    }

    // Pixel replacement

    
Returns true if the writer allows pixels of the
given image to be replaced using the replacePixels
methods.
 A writer that does not support any pixel replacement may
return false without performing bounds checking on
the index.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise returns false
without checking the value of imageIndex.
Params:
imageIndex – the index of the image whose pixels are to be
replaced.
Throws:
IllegalStateException – if the output has not been
set.
IndexOutOfBoundsException – if the writer supports
pixel replacement in general, but imageIndex is
less than 0 or greater than the largest available index.
IOException – if an I/O error occurs during the query.
Returns:
true if the pixels of the given
image can be replaced./**
     * Returns <code>true</code> if the writer allows pixels of the
     * given image to be replaced using the <code>replacePixels</code>
     * methods.
     *
     * <p> A writer that does not support any pixel replacement may
     * return <code>false</code> without performing bounds checking on
     * the index.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise returns <code>false</code>
     * without checking the value of <code>imageIndex</code>.
     *
     * @param imageIndex the index of the image whose pixels are to be
     * replaced.
     *
     * @return <code>true</code> if the pixels of the given
     * image can be replaced.
     *
     * @exception IllegalStateException if the output has not been
     * set.
     * @exception IndexOutOfBoundsException if the writer supports
     * pixel replacement in general, but <code>imageIndex</code> is
     * less than 0 or greater than the largest available index.
     * @exception IOException if an I/O error occurs during the query.
     */
    public boolean canReplacePixels(int imageIndex) throws IOException {
        if (getOutput() == null) {
            throw new IllegalStateException("getOutput() == null!");
        }
        return false;
    }

    
Prepares the writer to handle a series of calls to the
replacePixels methods.  The affected pixel area
will be clipped against the supplied
 If canReplacePixels returns
false, and
UnsupportedOperationException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
imageIndex – the index of the image whose pixels are to be
replaced.
region – a Rectangle that will be used to clip
future pixel regions.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canReplacePixels(imageIndex) returns
false.
IndexOutOfBoundsException – if imageIndex
is less than 0 or greater than the largest available index.
IllegalStateException – if there is a previous call to
prepareReplacePixels without a matching call to
endReplacePixels (i.e., nesting is not
allowed).
IllegalArgumentException – if region is
null or has a width or height less than 1.
IOException – if an I/O error occurs during the
preparation./**
     * Prepares the writer to handle a series of calls to the
     * <code>replacePixels</code> methods.  The affected pixel area
     * will be clipped against the supplied
     *
     * <p> If <code>canReplacePixels</code> returns
     * <code>false</code>, and
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param imageIndex the index of the image whose pixels are to be
     * replaced.
     * @param region a <code>Rectangle</code> that will be used to clip
     * future pixel regions.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canReplacePixels(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IndexOutOfBoundsException if <code>imageIndex</code>
     * is less than 0 or greater than the largest available index.
     * @exception IllegalStateException if there is a previous call to
     * <code>prepareReplacePixels</code> without a matching call to
     * <code>endReplacePixels</code> (<i>i.e.</i>, nesting is not
     * allowed).
     * @exception IllegalArgumentException if <code>region</code> is
     * <code>null</code> or has a width or height less than 1.
     * @exception IOException if an I/O error occurs during the
     * preparation.
     */
    public void prepareReplacePixels(int imageIndex,
                                     Rectangle region)  throws IOException {
        unsupported();
    }

    
Replaces a portion of an image already present in the output
with a portion of the given image.  The image data must match,
or be convertible to, the image layout of the existing image.
 The destination region is specified in the
param argument, and will be clipped to the image
boundaries and the region supplied to
prepareReplacePixels.  At least one pixel of the
source must not be clipped, or an exception is thrown.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 This method may only be called after a call to
prepareReplacePixels, or else an
IllegalStateException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
image – a RenderedImage containing source
pixels.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canReplacePixels(imageIndex) returns
false.
IllegalStateException – if there is no previous call to
prepareReplacePixels without a matching call to
endReplacePixels.
IllegalArgumentException – if any of the following are true:

 image is null.
 param is null.
 the intersected region does not contain at least one pixel.
 the layout of image does not match, or this
writer cannot convert it to, the existing image layout.
IOException – if an I/O error occurs during writing./**
     * Replaces a portion of an image already present in the output
     * with a portion of the given image.  The image data must match,
     * or be convertible to, the image layout of the existing image.
     *
     * <p> The destination region is specified in the
     * <code>param</code> argument, and will be clipped to the image
     * boundaries and the region supplied to
     * <code>prepareReplacePixels</code>.  At least one pixel of the
     * source must not be clipped, or an exception is thrown.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> This method may only be called after a call to
     * <code>prepareReplacePixels</code>, or else an
     * <code>IllegalStateException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param image a <code>RenderedImage</code> containing source
     * pixels.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canReplacePixels(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IllegalStateException if there is no previous call to
     * <code>prepareReplacePixels</code> without a matching call to
     * <code>endReplacePixels</code>.
     * @exception IllegalArgumentException if any of the following are true:
     * <ul>
     * <li> <code>image</code> is <code>null</code>.
     * <li> <code>param</code> is <code>null</code>.
     * <li> the intersected region does not contain at least one pixel.
     * <li> the layout of <code>image</code> does not match, or this
     * writer cannot convert it to, the existing image layout.
     * </ul>
     * @exception IOException if an I/O error occurs during writing.
     */
    public void replacePixels(RenderedImage image, ImageWriteParam param)
        throws IOException {
        unsupported();
    }

    
Replaces a portion of an image already present in the output
with a portion of the given Raster.  The image
data must match, or be convertible to, the image layout of the
existing image.
 An ImageWriteParam may optionally be supplied
to control the writing process.  If param is
null, a default write param will be used.
 The destination region is specified in the
param argument, and will be clipped to the image
boundaries and the region supplied to
prepareReplacePixels.  At least one pixel of the
source must not be clipped, or an exception is thrown.
 If the supplied ImageWriteParam contains
optional setting values not supported by this writer (e.g.
progressive encoding or any format-specific settings), they
will be ignored.
 This method may only be called after a call to
prepareReplacePixels, or else an
IllegalStateException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Params:
raster – a Raster containing source
pixels.
param – an ImageWriteParam, or
null to use a default
ImageWriteParam.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canReplacePixels(imageIndex) returns
false.
IllegalStateException – if there is no previous call to
prepareReplacePixels without a matching call to
endReplacePixels.
UnsupportedOperationException – if
canWriteRasters returns false.
IllegalArgumentException – if any of the following are true:

 raster is null.
 param is null.
 the intersected region does not contain at least one pixel.
 the layout of raster does not match, or this
writer cannot convert it to, the existing image layout.
IOException – if an I/O error occurs during writing./**
     * Replaces a portion of an image already present in the output
     * with a portion of the given <code>Raster</code>.  The image
     * data must match, or be convertible to, the image layout of the
     * existing image.
     *
     * <p> An <code>ImageWriteParam</code> may optionally be supplied
     * to control the writing process.  If <code>param</code> is
     * <code>null</code>, a default write param will be used.
     *
     * <p> The destination region is specified in the
     * <code>param</code> argument, and will be clipped to the image
     * boundaries and the region supplied to
     * <code>prepareReplacePixels</code>.  At least one pixel of the
     * source must not be clipped, or an exception is thrown.
     *
     * <p> If the supplied <code>ImageWriteParam</code> contains
     * optional setting values not supported by this writer (<i>e.g.</i>
     * progressive encoding or any format-specific settings), they
     * will be ignored.
     *
     * <p> This method may only be called after a call to
     * <code>prepareReplacePixels</code>, or else an
     * <code>IllegalStateException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @param raster a <code>Raster</code> containing source
     * pixels.
     * @param param an <code>ImageWriteParam</code>, or
     * <code>null</code> to use a default
     * <code>ImageWriteParam</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canReplacePixels(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IllegalStateException if there is no previous call to
     * <code>prepareReplacePixels</code> without a matching call to
     * <code>endReplacePixels</code>.
     * @exception UnsupportedOperationException if
     * <code>canWriteRasters</code> returns <code>false</code>.
     * @exception IllegalArgumentException if any of the following are true:
     * <ul>
     * <li> <code>raster</code> is <code>null</code>.
     * <li> <code>param</code> is <code>null</code>.
     * <li> the intersected region does not contain at least one pixel.
     * <li> the layout of <code>raster</code> does not match, or this
     * writer cannot convert it to, the existing image layout.
     * </ul>
     * @exception IOException if an I/O error occurs during writing.
     */
    public void replacePixels(Raster raster, ImageWriteParam param)
        throws IOException {
        unsupported();
    }

    
Terminates a sequence of calls to replacePixels.
 If canReplacePixels returns
false, and
UnsupportedOperationException will be thrown.
 The default implementation throws an
IllegalStateException if the output is
null, and otherwise throws an
UnsupportedOperationException.
Throws:
IllegalStateException – if the output has not
been set.
UnsupportedOperationException – if
canReplacePixels(imageIndex) returns
false.
IllegalStateException – if there is no previous call
to prepareReplacePixels without a matching call to
endReplacePixels.
IOException – if an I/O error occurs during writing./**
     * Terminates a sequence of calls to <code>replacePixels</code>.
     *
     * <p> If <code>canReplacePixels</code> returns
     * <code>false</code>, and
     * <code>UnsupportedOperationException</code> will be thrown.
     *
     * <p> The default implementation throws an
     * <code>IllegalStateException</code> if the output is
     * <code>null</code>, and otherwise throws an
     * <code>UnsupportedOperationException</code>.
     *
     * @exception IllegalStateException if the output has not
     * been set.
     * @exception UnsupportedOperationException if
     * <code>canReplacePixels(imageIndex)</code> returns
     * <code>false</code>.
     * @exception IllegalStateException if there is no previous call
     * to <code>prepareReplacePixels</code> without a matching call to
     * <code>endReplacePixels</code>.
     * @exception IOException if an I/O error occurs during writing.
     */
    public void endReplacePixels() throws IOException {
        unsupported();
    }

    // Abort

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

    
Returns true if a request to abort the current
write operation has been made since the writer was instantiated or
clearAbortRequest was called.
See Also:
abort
clearAbortRequest
Returns:
true if the current write operation should
be aborted./**
     * Returns <code>true</code> if a request to abort the current
     * write operation has been made since the writer was instantiated or
     * <code>clearAbortRequest</code> was called.
     *
     * @return <code>true</code> if the current write 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

    
Adds an IIOWriteWarningListener 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 writer sees fit.
Params:
listener – an IIOWriteWarningListener to be
registered.
See Also:
removeIIOWriteWarningListener/**
     * Adds an <code>IIOWriteWarningListener</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 writer sees fit.
     *
     * @param listener an <code>IIOWriteWarningListener</code> to be
     * registered.
     *
     * @see #removeIIOWriteWarningListener
     */
    public void addIIOWriteWarningListener(IIOWriteWarningListener listener) {
        if (listener == null) {
            return;
        }
        warningListeners = ImageReader.addToList(warningListeners, listener);
        warningLocales = ImageReader.addToList(warningLocales, getLocale());
    }

    
Removes an IIOWriteWarningListener from the list
of registered warning 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 IIOWriteWarningListener to be
deregistered.
See Also:
addIIOWriteWarningListener/**
     * Removes an <code>IIOWriteWarningListener</code> from the list
     * of registered warning 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 <code>IIOWriteWarningListener</code> to be
     * deregistered.
     *
     * @see #addIIOWriteWarningListener
     */
    public
        void removeIIOWriteWarningListener(IIOWriteWarningListener 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
IIOWriteWarningListener objects.
 The default implementation sets the
warningListeners and warningLocales
instance variables to null.
/**
     * Removes all currently registered
     * <code>IIOWriteWarningListener</code> objects.
     *
     * <p> The default implementation sets the
     * <code>warningListeners</code> and <code>warningLocales</code>
     * instance variables to <code>null</code>.
     */
    public void removeAllIIOWriteWarningListeners() {
        this.warningListeners = null;
        this.warningLocales = null;
    }

    
Adds an IIOWriteProgressListener 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 IIOWriteProgressListener to be
registered.
See Also:
removeIIOWriteProgressListener/**
     * Adds an <code>IIOWriteProgressListener</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 <code>IIOWriteProgressListener</code> to be
     * registered.
     *
     * @see #removeIIOWriteProgressListener
     */
    public void
        addIIOWriteProgressListener(IIOWriteProgressListener listener) {
        if (listener == null) {
            return;
        }
        progressListeners = ImageReader.addToList(progressListeners, listener);
    }

    
Removes an IIOWriteProgressListener 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 IIOWriteProgressListener to be
deregistered.
See Also:
addIIOWriteProgressListener/**
     * Removes an <code>IIOWriteProgressListener</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 <code>IIOWriteProgressListener</code> to be
     * deregistered.
     *
     * @see #addIIOWriteProgressListener
     */
    public void
        removeIIOWriteProgressListener(IIOWriteProgressListener listener) {
        if (listener == null || progressListeners == null) {
            return;
        }
        progressListeners =
            ImageReader.removeFromList(progressListeners, listener);
    }

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

    
Broadcasts the start of an image write to all registered
IIOWriteProgressListeners by calling their
imageStarted method.  Subclasses may use this
method as a convenience.
Params:
imageIndex – the index of the image about to be written./**
     * Broadcasts the start of an image write to all registered
     * <code>IIOWriteProgressListener</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 written.
     */
    protected void processImageStarted(int imageIndex) {
        if (progressListeners == null) {
            return;
        }
        int numListeners = progressListeners.size();
        for (int i = 0; i < numListeners; i++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.imageStarted(this, imageIndex);
        }
    }

    
Broadcasts the current percentage of image completion to all
registered IIOWriteProgressListeners 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>IIOWriteProgressListener</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++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.imageProgress(this, percentageDone);
        }
    }

    
Broadcasts the completion of an image write to all registered
IIOWriteProgressListeners by calling their
imageComplete method.  Subclasses may use this
method as a convenience.
/**
     * Broadcasts the completion of an image write to all registered
     * <code>IIOWriteProgressListener</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++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.imageComplete(this);
        }
    }

    
Broadcasts the start of a thumbnail write to all registered
IIOWriteProgressListeners 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 write to all registered
     * <code>IIOWriteProgressListener</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++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.thumbnailStarted(this, imageIndex, thumbnailIndex);
        }
    }

    
Broadcasts the current percentage of thumbnail completion to
all registered IIOWriteProgressListeners 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>IIOWriteProgressListener</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++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.thumbnailProgress(this, percentageDone);
        }
    }

    
Broadcasts the completion of a thumbnail write to all registered
IIOWriteProgressListeners by calling their
thumbnailComplete method.  Subclasses may use this
method as a convenience.
/**
     * Broadcasts the completion of a thumbnail write to all registered
     * <code>IIOWriteProgressListener</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++) {
            IIOWriteProgressListener listener =
                (IIOWriteProgressListener)progressListeners.get(i);
            listener.thumbnailComplete(this);
        }
    }

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

    
Broadcasts a warning message to all registered
IIOWriteWarningListeners by calling their
warningOccurred method.  Subclasses may use this
method as a convenience.
Params:
imageIndex – the index of the image on which the warning
occurred.
warning – the warning message.
Throws:
IllegalArgumentException – if warning
is null./**
     * Broadcasts a warning message to all registered
     * <code>IIOWriteWarningListener</code>s by calling their
     * <code>warningOccurred</code> method.  Subclasses may use this
     * method as a convenience.
     *
     * @param imageIndex the index of the image on which the warning
     * occurred.
     * @param warning the warning message.
     *
     * @exception IllegalArgumentException if <code>warning</code>
     * is <code>null</code>.
     */
    protected void processWarningOccurred(int imageIndex,
                                          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++) {
            IIOWriteWarningListener listener =
                (IIOWriteWarningListener)warningListeners.get(i);

            listener.warningOccurred(this, imageIndex, warning);
        }
    }

    
Broadcasts a localized warning message to all registered
IIOWriteWarningListeners by calling their
warningOccurred method with a string taken
from a ResourceBundle.  Subclasses may use this
method as a convenience.
Params:
imageIndex – the index of the image on which the warning
occurred.
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>IIOWriteWarningListener</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 imageIndex the index of the image on which the warning
     * occurred.
     * @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(int imageIndex,
                                          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++) {
            IIOWriteWarningListener listener =
                (IIOWriteWarningListener)warningListeners.get(i);
            Locale locale = (Locale)warningLocales.get(i);
            if (locale == null) {
                locale = Locale.getDefault();
            }

            /**
             * If an applet supplies an implementation of ImageWriter 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, imageIndex, warning);
        }
    }

    // State management

    
Restores the ImageWriter to its initial state.
 The default implementation calls
setOutput(null), setLocale(null),
removeAllIIOWriteWarningListeners(),
removeAllIIOWriteProgressListeners(), and
clearAbortRequest.
/**
     * Restores the <code>ImageWriter</code> to its initial state.
     *
     * <p> The default implementation calls
     * <code>setOutput(null)</code>, <code>setLocale(null)</code>,
     * <code>removeAllIIOWriteWarningListeners()</code>,
     * <code>removeAllIIOWriteProgressListeners()</code>, and
     * <code>clearAbortRequest</code>.
     */
    public void reset() {
        setOutput(null);
        setLocale(null);
        removeAllIIOWriteWarningListeners();
        removeAllIIOWriteProgressListeners();
        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 ImageWriter.
Otherwise, the writer 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>ImageWriter</code>.
     * Otherwise, the writer 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() {
    }
}