/*

 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.imageio;

import java.awt.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.

 *

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

 *

 * @see ImageReader

 * @see ImageWriteParam

 * @see javax.imageio.spi.IIORegistry

 * @see javax.imageio.spi.ImageWriterSpi

 *

 */

public abstract class ImageWriter implements ImageTranscoder {

    /**

     * 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 <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 <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 <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 <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 <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 <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 <code>true</code>, the current write operation should be

     * aborted.

     */

    private boolean abortFlag = false;

    /**

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

     * <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 <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 <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 : availableLocales.clone();

    }

    /**

     * 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 <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 <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 <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 <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 <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 <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 <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 <code>ImageOutputStream</code>, its existing

     * contents prior to the current seek position are not affected,