ImageWriter.java revision 2362
2362N/A * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * An abstract superclass for encoding and writing images. This class 0N/A * must be subclassed by classes that write out images in the context 0N/A * of the Java Image I/O framework. 0N/A * <p> <code>ImageWriter</code> objects are normally instantiated by 0N/A * the service provider class for the specific format. Service 0N/A * provider classes are registered with the <code>IIORegistry</code>, 0N/A * which uses them for format recognition and presentation of 0N/A * available format readers and writers. 0N/A * @see ImageWriteParam 0N/A * @see javax.imageio.spi.IIORegistry 0N/A * @see javax.imageio.spi.ImageWriterSpi 0N/A * The <code>ImageWriterSpi</code> that instantiated this object, 0N/A * or <code>null</code> if its identity is not known or none 0N/A * exists. By default it is initialized to <code>null</code>. 0N/A * The <code>ImageOutputStream</code> or other <code>Object</code> 0N/A * set by <code>setOutput</code> and retrieved by 0N/A * <code>getOutput</code>. By default it is initialized to 0N/A * <code>null</code>. 0N/A * An array of <code>Locale</code>s that may be used to localize 0N/A * warning messages and compression setting values, or 0N/A * <code>null</code> if localization is not supported. By default 0N/A * it is initialized to <code>null</code>. 0N/A * The current <code>Locale</code> to be used for localization, or 0N/A * <code>null</code> if none has been set. By default it is 0N/A * initialized to <code>null</code>. 0N/A * A <code>List</code> of currently registered 0N/A * <code>IIOWriteWarningListener</code>s, initialized by default to 0N/A * <code>null</code>, which is synonymous with an empty 0N/A * <code>List</code>. 0N/A * A <code>List</code> of <code>Locale</code>s, one for each 0N/A * element of <code>warningListeners</code>, initialized by default 0N/A * <code>null</code>, which is synonymous with an empty 0N/A * <code>List</code>. 0N/A * A <code>List</code> of currently registered 0N/A * <code>IIOWriteProgressListener</code>s, initialized by default 0N/A * <code>null</code>, which is synonymous with an empty 0N/A * <code>List</code>. 0N/A * If <code>true</code>, the current write operation should be 0N/A * Constructs an <code>ImageWriter</code> and sets its 0N/A * <code>originatingProvider</code> instance variable to the 0N/A * <p> Subclasses that make use of extensions should provide a 0N/A * constructor with signature <code>(ImageWriterSpi, 0N/A * Object)</code> in order to retrieve the extension object. If 0N/A * the extension object is unsuitable, an 0N/A * <code>IllegalArgumentException</code> should be thrown. 0N/A * @param originatingProvider the <code>ImageWriterSpi</code> that 0N/A * is constructing this object, or <code>null</code>. 0N/A * Returns the <code>ImageWriterSpi</code> object that created 0N/A * this <code>ImageWriter</code>, or <code>null</code> if this 0N/A * object was not created through the <code>IIORegistry</code>. 0N/A * <p> The default implementation returns the value of the 0N/A * <code>originatingProvider</code> instance variable. 0N/A * @return an <code>ImageWriterSpi</code>, or <code>null</code>. 0N/A * @see ImageWriterSpi 0N/A * Sets the destination to the given 0N/A * <code>ImageOutputStream</code> or other <code>Object</code>. 0N/A * The destination is assumed to be ready to accept data, and will 0N/A * not be closed at the end of each write. This allows distributed 0N/A * imaging applications to transmit a series of images over a 0N/A * single network connection. If <code>output</code> is 0N/A * <code>null</code>, any currently set output will be removed. 0N/A * <p> If <code>output</code> is an 0N/A * <code>ImageOutputStream</code>, calls to the 0N/A * <code>write</code>, <code>writeToSequence</code>, and 0N/A * <code>prepareWriteEmpty</code>/<code>endWriteEmpty</code> 0N/A * methods will preserve the existing contents of the stream. 0N/A * Other write methods, such as <code>writeInsert</code>, 0N/A * <code>replaceStreamMetadata</code>, 0N/A * <code>replaceImageMetadata</code>, <code>replacePixels</code>, 0N/A * <code>prepareInsertEmpty</code>/<code>endInsertEmpty</code>, 0N/A * and <code>endWriteSequence</code>, require the full contents 0N/A * of the stream to be readable and writable, and may alter any 0N/A * portion of the stream. 0N/A * <p> Use of a general <code>Object</code> other than an 0N/A * <code>ImageOutputStream</code> is intended for writers that 0N/A * interact directly with an output device or imaging protocol. 0N/A * The set of legal classes is advertised by the writer's service 0N/A * provider's <code>getOutputTypes</code> method; most writers 0N/A * will return a single-element array containing only 0N/A * <code>ImageOutputStream.class</code> to indicate that they 0N/A * accept only an <code>ImageOutputStream</code>. 0N/A * <p> The default implementation sets the <code>output</code> 0N/A * instance variable to the value of <code>output</code> after 0N/A * checking <code>output</code> against the set of classes 0N/A * advertised by the originating provider, if there is one. 0N/A * @param output the <code>ImageOutputStream</code> or other 0N/A * <code>Object</code> to use for future writing. 0N/A * @exception IllegalArgumentException if <code>output</code> is 0N/A * not an instance of one of the classes returned by the 0N/A * originating service provider's <code>getOutputTypes</code> 0N/A * Returns the <code>ImageOutputStream</code> or other 0N/A * <code>Object</code> set by the most recent call to the 0N/A * <code>setOutput</code> method. If no destination has been 0N/A * set, <code>null</code> is returned. 0N/A * <p> The default implementation returns the value of the 0N/A * <code>output</code> instance variable. 0N/A * @return the <code>Object</code> that was specified using 0N/A * <code>setOutput</code>, or <code>null</code>. 0N/A * Returns an array of <code>Locale</code>s that may be used to 0N/A * localize warning listeners and compression settings. A return 0N/A * value of <code>null</code> indicates that localization is not 0N/A * <p> The default implementation returns a clone of the 0N/A * <code>availableLocales</code> instance variable if it is 0N/A * non-<code>null</code>, or else returns <code>null</code>. 0N/A * @return an array of <code>Locale</code>s that may be used as 0N/A * arguments to <code>setLocale</code>, or <code>null</code>. 0N/A * Sets the current <code>Locale</code> of this 0N/A * <code>ImageWriter</code> to the given value. A value of 0N/A * <code>null</code> removes any previous setting, and indicates 0N/A * that the writer should localize as it sees fit. 0N/A * <p> The default implementation checks <code>locale</code> 0N/A * against the values returned by 0N/A * <code>getAvailableLocales</code>, and sets the 0N/A * <code>locale</code> instance variable if it is found. If 0N/A * <code>locale</code> is <code>null</code>, the instance variable 0N/A * is set to <code>null</code> without any checking. 0N/A * @param locale the desired <code>Locale</code>, or 0N/A * <code>null</code>. 0N/A * @exception IllegalArgumentException if <code>locale</code> is 0N/A * non-<code>null</code> but is not one of the values returned by 0N/A * <code>getAvailableLocales</code>. 0N/A * Returns the currently set <code>Locale</code>, or 0N/A * <code>null</code> if none has been set. 0N/A * <p> The default implementation returns the value of the 0N/A * <code>locale</code> instance variable. 0N/A * @return the current <code>Locale</code>, or <code>null</code>. 0N/A * Returns a new <code>ImageWriteParam</code> object of the 0N/A * appropriate type for this file format containing default 0N/A * values, that is, those values that would be used 0N/A * if no <code>ImageWriteParam</code> object were specified. This 0N/A * is useful as a starting point for tweaking just a few parameters 0N/A * and otherwise leaving the default settings alone. 0N/A * <p> The default implementation constructs and returns a new 0N/A * <code>ImageWriteParam</code> object that does not allow tiling, 0N/A * progressive encoding, or compression, and that will be 0N/A * localized for the current <code>Locale</code> (<i>i.e.</i>, 0N/A * what you would get by calling <code>new 0N/A * ImageWriteParam(getLocale())</code>. 0N/A * <p> Individual plug-ins may return an instance of 0N/A * <code>ImageWriteParam</code> with additional optional features 0N/A * enabled, or they may return an instance of a plug-in specific 0N/A * subclass of <code>ImageWriteParam</code>. 0N/A * @return a new <code>ImageWriteParam</code> object containing 0N/A * Returns an <code>IIOMetadata</code> object containing default 0N/A * values for encoding a stream of images. The contents of the 0N/A * object may be manipulated using either the XML tree structure 0N/A * returned by the <code>IIOMetadata.getAsTree</code> method, an 0N/A * <code>IIOMetadataController</code> object, or via plug-in 0N/A * specific interfaces, and the resulting data supplied to one of 0N/A * the <code>write</code> methods that take a stream metadata 0N/A * <p> An optional <code>ImageWriteParam</code> may be supplied 0N/A * for cases where it may affect the structure of the stream 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> Writers that do not make use of stream metadata 0N/A * (<i>e.g.</i>, writers for single-image formats) should return 0N/A * <code>null</code>. 0N/A * @param param an <code>ImageWriteParam</code> that will be used to 0N/A * encode the image, or <code>null</code>. 0N/A * @return an <code>IIOMetadata</code> object. 0N/A * Returns an <code>IIOMetadata</code> object containing default 0N/A * values for encoding an image of the given type. The contents 0N/A * of the object may be manipulated using either the XML tree 0N/A * structure returned by the <code>IIOMetadata.getAsTree</code> 0N/A * method, an <code>IIOMetadataController</code> object, or via 0N/A * plug-in specific interfaces, and the resulting data supplied to 0N/A * one of the <code>write</code> methods that take a stream 0N/A * metadata parameter. 0N/A * <p> An optional <code>ImageWriteParam</code> may be supplied 0N/A * for cases where it may affect the structure of the image 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * @param imageType an <code>ImageTypeSpecifier</code> indicating the 0N/A * format of the image to be written later. 0N/A * @param param an <code>ImageWriteParam</code> that will be used to 0N/A * encode the image, or <code>null</code>. 0N/A * @return an <code>IIOMetadata</code> object. 0N/A // comment inherited 0N/A // comment inherited 0N/A * Returns the number of thumbnails suported by the format being 0N/A * written, given the image type and any additional write 0N/A * parameters and metadata objects that will be used during 0N/A * encoding. A return value of <code>-1</code> indicates that 0N/A * insufficient information is available. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * for cases where it may affect thumbnail handling. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation returns 0. 0N/A * @param imageType an <code>ImageTypeSpecifier</code> indicating 0N/A * the type of image to be written, or <code>null</code>. 0N/A * @param param the <code>ImageWriteParam</code> that will be used for 0N/A * writing, or <code>null</code>. 0N/A * @param streamMetadata an <code>IIOMetadata</code> object that will 0N/A * be used for writing, or <code>null</code>. 0N/A * @param imageMetadata an <code>IIOMetadata</code> object that will 0N/A * be used for writing, or <code>null</code>. 0N/A * @return the number of thumbnails that may be written given the 0N/A * supplied parameters, or <code>-1</code> if insufficient 0N/A * information is available. 0N/A * Returns an array of <code>Dimension</code>s indicating the 0N/A * legal size ranges for thumbnail images as they will be encoded 0N/A * in the output file or stream. This information is merely 0N/A * advisory; the writer will resize any supplied thumbnails as 0N/A * <p> The information is returned as a set of pairs; the first 0N/A * element of a pair contains an (inclusive) minimum width and 0N/A * height, and the second element contains an (inclusive) maximum 0N/A * width and height. Together, each pair defines a valid range of 0N/A * sizes. To specify a fixed size, the same width and height will 0N/A * appear for both elements. A return value of <code>null</code> 0N/A * indicates that the size is arbitrary or unknown. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * for cases where it may affect thumbnail handling. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation returns <code>null</code>. 0N/A * @param imageType an <code>ImageTypeSpecifier</code> indicating the 0N/A * type of image to be written, or <code>null</code>. 0N/A * @param param the <code>ImageWriteParam</code> that will be used for 0N/A * writing, or <code>null</code>. 0N/A * @param streamMetadata an <code>IIOMetadata</code> object that will 0N/A * be used for writing, or <code>null</code>. 0N/A * @param imageMetadata an <code>IIOMetadata</code> object that will 0N/A * be used for writing, or <code>null</code>. 0N/A * @return an array of <code>Dimension</code>s with an even length 0N/A * of at least two, or <code>null</code>. 0N/A * Returns <code>true</code> if the methods that take an 0N/A * <code>IIOImage</code> parameter are capable of dealing with a 0N/A * <code>Raster</code> (as opposed to <code>RenderedImage</code>) 0N/A * source image. If this method returns <code>false</code>, then 0N/A * those methods will throw an 0N/A * <code>UnsupportedOperationException</code> if supplied with an 0N/A * <code>IIOImage</code> containing a <code>Raster</code>. 0N/A * <p> The default implementation returns <code>false</code>. 0N/A * @return <code>true</code> if <code>Raster</code> sources are 0N/A * Appends a complete image stream containing a single image and 0N/A * associated stream and image metadata and thumbnails to the 0N/A * output. Any necessary header information is included. If the 0N/A * output is an <code>ImageOutputStream</code>, its existing 0N/A * contents prior to the current seek position are not affected, 0N/A * and need not be readable or writable. 0N/A * <p> The output must have been set beforehand using the 0N/A * <code>setOutput</code> method. 0N/A * <p> Stream metadata may optionally be supplied; if it is 0N/A * <code>null</code>, default stream metadata will be used. 0N/A * <p> If <code>canWriteRasters</code> returns <code>true</code>, 0N/A * the <code>IIOImage</code> may contain a <code>Raster</code> 0N/A * source. Otherwise, it must contain a 0N/A * <code>RenderedImage</code> source. 0N/A * <p> The supplied thumbnails will be resized if needed, and any 0N/A * thumbnails in excess of the supported number will be ignored. 0N/A * If the format requires additional thumbnails that are not 0N/A * provided, the writer should generate them internally. 0N/A * <p> An <code>ImageWriteParam</code> may 0N/A * optionally be supplied to control the writing process. If 0N/A * <code>param</code> is <code>null</code>, a default write param 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * @param streamMetadata an <code>IIOMetadata</code> object representing 0N/A * stream metadata, or <code>null</code> to use default values. 0N/A * @param image an <code>IIOImage</code> object containing an 0N/A * image, thumbnails, and metadata to be written. 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if <code>image</code> 0N/A * contains a <code>Raster</code> and <code>canWriteRasters</code> 0N/A * returns <code>false</code>. 0N/A * @exception IllegalArgumentException if <code>image</code> is 0N/A * <code>null</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A * Appends a complete image stream containing a single image with 0N/A * default metadata and thumbnails to the output. This method is 0N/A * a shorthand for <code>write(null, image, null)</code>. 0N/A * @param image an <code>IIOImage</code> object containing an 0N/A * image, thumbnails, and metadata to be written. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IllegalArgumentException if <code>image</code> is 0N/A * <code>null</code>. 0N/A * @exception UnsupportedOperationException if <code>image</code> 0N/A * contains a <code>Raster</code> and <code>canWriteRasters</code> 0N/A * returns <code>false</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A * Appends a complete image stream consisting of a single image 0N/A * with default metadata and thumbnails to the output. This 0N/A * method is a shorthand for <code>write(null, new IIOImage(image, 0N/A * null, null), null)</code>. 0N/A * @param image a <code>RenderedImage</code> to be written. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IllegalArgumentException if <code>image</code> is 0N/A * <code>null</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A // Check that the output has been set, then throw an 0N/A // UnsupportedOperationException. 0N/A * Returns <code>true</code> if the writer is able to append an 0N/A * image to an image stream that already contains header 0N/A * information and possibly prior images. 0N/A * <p> If <code>canWriteSequence</code> returns <code>false</code>, 0N/A * <code>writeToSequence</code> and <code>endWriteSequence</code> 0N/A * will throw an <code>UnsupportedOperationException</code>. 0N/A * <p> The default implementation returns <code>false</code>. 0N/A * @return <code>true</code> if images may be appended sequentially. 0N/A * Prepares a stream to accept a series of subsequent 0N/A * <code>writeToSequence</code> calls, using the provided stream 0N/A * metadata object. The metadata will be written to the stream if 0N/A * it should precede the image data. If the argument is <code>null</code>, 0N/A * default stream metadata is used. 0N/A * <p> If the output is an <code>ImageOutputStream</code>, the existing 0N/A * contents of the output prior to the current seek position are 0N/A * flushed, and need not be readable or writable. If the format 0N/A * requires that <code>endWriteSequence</code> be able to rewind to 0N/A * patch up the header information, such as for a sequence of images 0N/A * in a single TIFF file, then the metadata written by this method 0N/A * must remain in a writable portion of the stream. Other formats 0N/A * may flush the stream after this method and after each image. 0N/A * <p> If <code>canWriteSequence</code> returns <code>false</code>, 0N/A * this method will throw an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * <p> The output must have been set beforehand using either 0N/A * the <code>setOutput</code> method. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param streamMetadata A stream metadata object, or <code>null</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteSequence</code> returns <code>false</code>. 0N/A * @exception IOException if an error occurs writing the stream 0N/A * Appends a single image and possibly associated metadata and 0N/A * thumbnails, to the output. If the output is an 0N/A * <code>ImageOutputStream</code>, the existing contents of the 0N/A * output prior to the current seek position may be flushed, and 0N/A * need not be readable or writable, unless the plug-in needs to 0N/A * be able to patch up the header information when 0N/A * <code>endWriteSequence</code> is called (<italic>e.g.</italic> TIFF). 0N/A * <p> If <code>canWriteSequence</code> returns <code>false</code>, 0N/A * this method will throw an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * <p> The output must have been set beforehand using 0N/A * the <code>setOutput</code> method. 0N/A * <p> <code>prepareWriteSequence</code> must have been called 0N/A * beforehand, or an <code>IllegalStateException</code> is thrown. 0N/A * <p> If <code>canWriteRasters</code> returns <code>true</code>, 0N/A * the <code>IIOImage</code> may contain a <code>Raster</code> 0N/A * source. Otherwise, it must contain a 0N/A * <code>RenderedImage</code> source. 0N/A * <p> The supplied thumbnails will be resized if needed, and any 0N/A * thumbnails in excess of the supported number will be ignored. 0N/A * If the format requires additional thumbnails that are not 0N/A * provided, the writer will generate them internally. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param image an <code>IIOImage</code> object containing an 0N/A * image, thumbnails, and metadata to be written. 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * been set, or <code>prepareWriteSequence</code> has not been called. 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteSequence</code> returns <code>false</code>. 0N/A * @exception IllegalArgumentException if <code>image</code> is 0N/A * <code>null</code>. 0N/A * @exception UnsupportedOperationException if <code>image</code> 0N/A * contains a <code>Raster</code> and <code>canWriteRasters</code> 0N/A * returns <code>false</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A * Completes the writing of a sequence of images begun with 0N/A * <code>prepareWriteSequence</code>. Any stream metadata that 0N/A * should come at the end of the sequence of images is written out, 0N/A * and any header information at the beginning of the sequence is 0N/A * patched up if necessary. If the output is an 0N/A * <code>ImageOutputStream</code>, data through the stream metadata 0N/A * at the end of the sequence are flushed and need not be readable 0N/A * <p> If <code>canWriteSequence</code> returns <code>false</code>, 0N/A * this method will throw an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * been set, or <code>prepareWriteSequence</code> has not been called. 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteSequence</code> returns <code>false</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A // Metadata replacement 0N/A * Returns <code>true</code> if it is possible to replace the 0N/A * stream metadata already present in the output. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code>. 0N/A * @return <code>true</code> if replacement of stream metadata is 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IOException if an I/O error occurs during the query. 0N/A * Replaces the stream metadata in the output with new 0N/A * information. If the output is an 0N/A * <code>ImageOutputStream</code>, the prior contents of the 0N/A * stream are examined and possibly edited to make room for the 0N/A * new data. All of the prior contents of the output must be 0N/A * available for reading and writing. 0N/A * <p> If <code>canReplaceStreamMetadata</code> returns 0N/A * <code>false</code>, an 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param streamMetadata an <code>IIOMetadata</code> object representing 0N/A * stream metadata, or <code>null</code> to use default values. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if the 0N/A * <code>canReplaceStreamMetadata</code> returns 0N/A * <code>false</code>. modes do not include 0N/A * @exception IOException if an error occurs during writing. 0N/A * Returns <code>true</code> if it is possible to replace the 0N/A * image metadata associated with an existing image with index 0N/A * <code>imageIndex</code>. If this method returns 0N/A * <code>false</code>, a call to 0N/A * <code>replaceImageMetadata(imageIndex)</code> will throw an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * <p> A writer that does not support any image metadata 0N/A * replacement may return <code>false</code> without performing 0N/A * bounds checking on the index. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code> 0N/A * without checking the value of <code>imageIndex</code>. 0N/A * @param imageIndex the index of the image whose metadata is to 0N/A * @return <code>true</code> if the image metadata of the given 0N/A * image can be replaced. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IndexOutOfBoundsException if the writer supports 0N/A * image metadata replacement in general, but 0N/A * <code>imageIndex</code> is less than 0 or greater than the 0N/A * largest available index. 0N/A * @exception IOException if an I/O error occurs during the query. 0N/A * Replaces the image metadata associated with an existing image. 0N/A * <p> If <code>canReplaceImageMetadata(imageIndex)</code> returns 0N/A * <code>false</code>, an 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param imageIndex the index of the image whose metadata is to 0N/A * @param imageMetadata an <code>IIOMetadata</code> object 0N/A * representing image metadata, or <code>null</code>. 0N/A * @exception IllegalStateException if the output has not been 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canReplaceImageMetadata</code> returns 0N/A * <code>false</code>. 0N/A * @exception IndexOutOfBoundsException if <code>imageIndex</code> 0N/A * is less than 0 or greater than the largest available index. 0N/A * @exception IOException if an error occurs during writing. 0N/A * Returns <code>true</code> if the writer supports the insertion 0N/A * of a new image at the given index. Existing images with 0N/A * indices greater than or equal to the insertion index will have 0N/A * their indices increased by 1. A value for 0N/A * <code>imageIndex</code> of <code>-1</code> may be used to 0N/A * signify an index one larger than the current largest index. 0N/A * <p> A writer that does not support any image insertion may 0N/A * return <code>false</code> without performing bounds checking on 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code> 0N/A * withour checking the value of <code>imageIndex</code>. 0N/A * @param imageIndex the index at which the image is to be 0N/A * @return <code>true</code> if an image may be inserted at the 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IndexOutOfBoundsException if the writer supports 0N/A * image insertion in general, but <code>imageIndex</code> is less 0N/A * than -1 or greater than the largest available index. 0N/A * @exception IOException if an I/O error occurs during the query. 0N/A * Inserts a new image into an existing image stream. Existing 0N/A * images with an index greater than <code>imageIndex</code> are 0N/A * preserved, and their indices are each increased by 1. A value 0N/A * for <code>imageIndex</code> of -1 may be used to signify an 0N/A * index one larger than the previous largest index; that is, it 0N/A * will cause the image to be logically appended to the end of the 0N/A * sequence. If the output is an <code>ImageOutputStream</code>, 0N/A * the entirety of the stream must be both readable and writeable. 0N/A * <p> If <code>canInsertImage(imageIndex)</code> returns 0N/A * <code>false</code>, an 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param imageIndex the index at which to write the image. 0N/A * @param image an <code>IIOImage</code> object containing an 0N/A * image, thumbnails, and metadata to be written. 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canInsertImage(imageIndex)</code> returns <code>false</code>. 0N/A * @exception IllegalArgumentException if <code>image</code> is 0N/A * <code>null</code>. 0N/A * @exception IndexOutOfBoundsException if <code>imageIndex</code> 0N/A * is less than -1 or greater than the largest available index. 0N/A * @exception UnsupportedOperationException if <code>image</code> 0N/A * contains a <code>Raster</code> and <code>canWriteRasters</code> 0N/A * returns <code>false</code>. 0N/A * @exception IOException if an error occurs during writing. 0N/A * Returns <code>true</code> if the writer supports the removal 0N/A * of an existing image at the given index. Existing images with 0N/A * indices greater than the insertion index will have 0N/A * their indices decreased by 1. 0N/A * <p> A writer that does not support any image removal may 0N/A * return <code>false</code> without performing bounds checking on 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code> 0N/A * without checking the value of <code>imageIndex</code>. 0N/A * @param imageIndex the index of the image to be removed. 0N/A * @return <code>true</code> if it is possible to remove the given 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception IndexOutOfBoundsException if the writer supports 0N/A * image removal in general, but <code>imageIndex</code> is less 0N/A * than 0 or greater than the largest available index. 0N/A * @exception IOException if an I/O error occurs during the 0N/A * Removes an image from the stream. 0N/A * <p> If <code>canRemoveImage(imageIndex)</code> returns false, 0N/A * an <code>UnsupportedOperationException</code>will be thrown. 0N/A * <p> The removal may or may not cause a reduction in the actual 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param imageIndex the index of the image to be removed. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canRemoveImage(imageIndex)</code> returns <code>false</code>. 0N/A * @exception IndexOutOfBoundsException if <code>imageIndex</code> 0N/A * is less than 0 or greater than the largest available index. 0N/A * @exception IOException if an I/O error occurs during the 0N/A * Returns <code>true</code> if the writer supports the writing of 0N/A * a complete image stream consisting of a single image with 0N/A * undefined pixel values and associated metadata and thumbnails 0N/A * to the output. The pixel values may be defined by future 0N/A * calls to the <code>replacePixels</code> methods. If the output 0N/A * is an <code>ImageOutputStream</code>, its existing contents 0N/A * prior to the current seek position are not affected, and need 0N/A * not be readable or writable. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code>. 0N/A * @return <code>true</code> if the writing of complete image 0N/A * stream with contents to be defined later is supported. 0N/A * @exception IllegalStateException if the output has not been 0N/A * @exception IOException if an I/O error occurs during the 0N/A * Begins the writing of a complete image stream, consisting of a 0N/A * single image with undefined pixel values and associated 0N/A * metadata and thumbnails, to the output. The pixel values will 0N/A * be defined by future calls to the <code>replacePixels</code> 0N/A * methods. If the output is an <code>ImageOutputStream</code>, 0N/A * its existing contents prior to the current seek position are 0N/A * not affected, and need not be readable or writable. 0N/A * <p> The writing is not complete until a call to 0N/A * <code>endWriteEmpty</code> occurs. Calls to 0N/A * <code>prepareReplacePixels</code>, <code>replacePixels</code>, 0N/A * and <code>endReplacePixels</code> may occur between calls to 0N/A * <code>prepareWriteEmpty</code> and <code>endWriteEmpty</code>. 0N/A * However, calls to <code>prepareWriteEmpty</code> cannot be 0N/A * nested, and calls to <code>prepareWriteEmpty</code> and 0N/A * <code>prepareInsertEmpty</code> may not be interspersed. 0N/A * <p> If <code>canWriteEmpty</code> returns <code>false</code>, 0N/A * an <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param streamMetadata an <code>IIOMetadata</code> object representing 0N/A * stream metadata, or <code>null</code> to use default values. 0N/A * @param imageType an <code>ImageTypeSpecifier</code> describing 0N/A * the layout of the image. 0N/A * @param width the width of the image. 0N/A * @param height the height of the image. 0N/A * @param imageMetadata an <code>IIOMetadata</code> object 0N/A * representing image metadata, or <code>null</code>. 0N/A * @param thumbnails a <code>List</code> of 0N/A * <code>BufferedImage</code> thumbnails for this image, or 0N/A * <code>null</code>. 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteEmpty</code> returns <code>false</code>. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareWriteEmpty</code> has been made without a 0N/A * corresponding call to <code>endWriteEmpty</code>. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareInsertEmpty</code> has been made without a 0N/A * corresponding call to <code>endInsertEmpty</code>. 0N/A * @exception IllegalArgumentException if <code>imageType</code> 0N/A * is <code>null</code> or <code>thumbnails</code> contains 0N/A * <code>null</code> references or objects other than 0N/A * <code>BufferedImage</code>s. 0N/A * @exception IllegalArgumentException if width or height are less 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Completes the writing of a new image that was begun with a 0N/A * prior call to <code>prepareWriteEmpty</code>. 0N/A * <p> If <code>canWriteEmpty()</code> returns <code>false</code>, 0N/A * an <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteEmpty(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareWriteEmpty</code> without a corresponding call to 0N/A * <code>endWriteEmpty</code> has not been made. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareInsertEmpty</code> without a corresponding call to 0N/A * <code>endInsertEmpty</code> has been made. 0N/A * @exception IllegalStateException if a call to 0N/A * <code>prepareReiplacePixels</code> has been made without a 0N/A * matching call to <code>endReplacePixels</code>. 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Returns <code>true</code> if the writer supports the insertion 0N/A * of a new, empty image at the given index. The pixel values of 0N/A * the image are undefined, and may be specified in pieces using 0N/A * the <code>replacePixels</code> methods. Existing images with 0N/A * indices greater than or equal to the insertion index will have 0N/A * their indices increased by 1. A value for 0N/A * <code>imageIndex</code> of <code>-1</code> may be used to 0N/A * signify an index one larger than the current largest index. 0N/A * <p> A writer that does not support insertion of empty images 0N/A * may return <code>false</code> without performing bounds 0N/A * checking on the index. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code> 0N/A * without checking the value of <code>imageIndex</code>. 0N/A * @param imageIndex the index at which the image is to be 0N/A * @return <code>true</code> if an empty image may be inserted at 0N/A * @exception IllegalStateException if the output has not been 0N/A * @exception IndexOutOfBoundsException if the writer supports 0N/A * empty image insertion in general, but <code>imageIndex</code> 0N/A * is less than -1 or greater than the largest available index. 0N/A * @exception IOException if an I/O error occurs during the 0N/A * Begins the insertion of a new image with undefined pixel values 0N/A * into an existing image stream. Existing images with an index 0N/A * greater than <code>imageIndex</code> are preserved, and their 0N/A * indices are each increased by 1. A value for 0N/A * <code>imageIndex</code> of -1 may be used to signify an index 0N/A * one larger than the previous largest index; that is, it will 0N/A * cause the image to be logically appended to the end of the 0N/A * sequence. If the output is an <code>ImageOutputStream</code>, 0N/A * the entirety of the stream must be both readable and writeable. 0N/A * <p> The image contents may be 0N/A * supplied later using the <code>replacePixels</code> method. 0N/A * The insertion is not complete until a call to 0N/A * <code>endInsertEmpty</code> occurs. Calls to 0N/A * <code>prepareReplacePixels</code>, <code>replacePixels</code>, 0N/A * and <code>endReplacePixels</code> may occur between calls to 0N/A * <code>prepareInsertEmpty</code> and 0N/A * <code>endInsertEmpty</code>. However, calls to 0N/A * <code>prepareInsertEmpty</code> cannot be nested, and calls to 0N/A * <code>prepareWriteEmpty</code> and 0N/A * <code>prepareInsertEmpty</code> may not be interspersed. 0N/A * <p> If <code>canInsertEmpty(imageIndex)</code> returns 0N/A * <code>false</code>, an 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param imageIndex the index at which to write the image. 0N/A * @param imageType an <code>ImageTypeSpecifier</code> describing 0N/A * the layout of the image. 0N/A * @param width the width of the image. 0N/A * @param height the height of the image. 0N/A * @param imageMetadata an <code>IIOMetadata</code> object 0N/A * representing image metadata, or <code>null</code>. 0N/A * @param thumbnails a <code>List</code> of 0N/A * <code>BufferedImage</code> thumbnails for this image, or 0N/A * <code>null</code>. 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canInsertEmpty(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IndexOutOfBoundsException if <code>imageIndex</code> 0N/A * is less than -1 or greater than the largest available index. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareInsertEmpty</code> has been made without a 0N/A * corresponding call to <code>endInsertEmpty</code>. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareWriteEmpty</code> has been made without a 0N/A * corresponding call to <code>endWriteEmpty</code>. 0N/A * @exception IllegalArgumentException if <code>imageType</code> 0N/A * is <code>null</code> or <code>thumbnails</code> contains 0N/A * <code>null</code> references or objects other than 0N/A * <code>BufferedImage</code>s. 0N/A * @exception IllegalArgumentException if width or height are less 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Completes the insertion of a new image that was begun with a 0N/A * prior call to <code>prepareInsertEmpty</code>. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canInsertEmpty(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareInsertEmpty</code> without a corresponding call to 0N/A * <code>endInsertEmpty</code> has not been made. 0N/A * @exception IllegalStateException if a previous call to 0N/A * <code>prepareWriteEmpty</code> without a corresponding call to 0N/A * <code>endWriteEmpty</code> has been made. 0N/A * @exception IllegalStateException if a call to 0N/A * <code>prepareReplacePixels</code> has been made without a 0N/A * matching call to <code>endReplacePixels</code>. 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A // Pixel replacement 0N/A * Returns <code>true</code> if the writer allows pixels of the 0N/A * given image to be replaced using the <code>replacePixels</code> 0N/A * <p> A writer that does not support any pixel replacement may 0N/A * return <code>false</code> without performing bounds checking on 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise returns <code>false</code> 0N/A * without checking the value of <code>imageIndex</code>. 0N/A * @param imageIndex the index of the image whose pixels are to be 0N/A * @return <code>true</code> if the pixels of the given 0N/A * image can be replaced. 0N/A * @exception IllegalStateException if the output has not been 0N/A * @exception IndexOutOfBoundsException if the writer supports 0N/A * pixel replacement in general, but <code>imageIndex</code> is 0N/A * less than 0 or greater than the largest available index. 0N/A * @exception IOException if an I/O error occurs during the query. 0N/A * Prepares the writer to handle a series of calls to the 0N/A * <code>replacePixels</code> methods. The affected pixel area 0N/A * will be clipped against the supplied 0N/A * <p> If <code>canReplacePixels</code> returns 0N/A * <code>false</code>, and 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param imageIndex the index of the image whose pixels are to be 0N/A * @param region a <code>Rectangle</code> that will be used to clip 0N/A * future pixel regions. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canReplacePixels(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IndexOutOfBoundsException if <code>imageIndex</code> 0N/A * is less than 0 or greater than the largest available index. 0N/A * @exception IllegalStateException if there is a previous call to 0N/A * <code>prepareReplacePixels</code> without a matching call to 0N/A * <code>endReplacePixels</code> (<i>i.e.</i>, nesting is not 0N/A * @exception IllegalArgumentException if <code>region</code> is 0N/A * <code>null</code> or has a width or height less than 1. 0N/A * @exception IOException if an I/O error occurs during the 0N/A * Replaces a portion of an image already present in the output 0N/A * with a portion of the given image. The image data must match, 0N/A * or be convertible to, the image layout of the existing image. 0N/A * <p> The destination region is specified in the 0N/A * <code>param</code> argument, and will be clipped to the image 0N/A * boundaries and the region supplied to 0N/A * <code>prepareReplacePixels</code>. At least one pixel of the 0N/A * source must not be clipped, or an exception is thrown. 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> This method may only be called after a call to 0N/A * <code>prepareReplacePixels</code>, or else an 0N/A * <code>IllegalStateException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param image a <code>RenderedImage</code> containing source 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canReplacePixels(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IllegalStateException if there is no previous call to 0N/A * <code>prepareReplacePixels</code> without a matching call to 0N/A * <code>endReplacePixels</code>. 0N/A * @exception IllegalArgumentException if any of the following are true: 0N/A * <li> <code>image</code> is <code>null</code>. 0N/A * <li> <code>param</code> is <code>null</code>. 0N/A * <li> the intersected region does not contain at least one pixel. 0N/A * <li> the layout of <code>image</code> does not match, or this 0N/A * writer cannot convert it to, the existing image layout. 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Replaces a portion of an image already present in the output 0N/A * with a portion of the given <code>Raster</code>. The image 0N/A * data must match, or be convertible to, the image layout of the 0N/A * <p> An <code>ImageWriteParam</code> may optionally be supplied 0N/A * to control the writing process. If <code>param</code> is 0N/A * <code>null</code>, a default write param will be used. 0N/A * <p> The destination region is specified in the 0N/A * <code>param</code> argument, and will be clipped to the image 0N/A * boundaries and the region supplied to 0N/A * <code>prepareReplacePixels</code>. At least one pixel of the 0N/A * source must not be clipped, or an exception is thrown. 0N/A * <p> If the supplied <code>ImageWriteParam</code> contains 0N/A * optional setting values not supported by this writer (<i>e.g.</i> 0N/A * progressive encoding or any format-specific settings), they 0N/A * <p> This method may only be called after a call to 0N/A * <code>prepareReplacePixels</code>, or else an 0N/A * <code>IllegalStateException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @param raster a <code>Raster</code> containing source 0N/A * @param param an <code>ImageWriteParam</code>, or 0N/A * <code>null</code> to use a default 0N/A * <code>ImageWriteParam</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canReplacePixels(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IllegalStateException if there is no previous call to 0N/A * <code>prepareReplacePixels</code> without a matching call to 0N/A * <code>endReplacePixels</code>. 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canWriteRasters</code> returns <code>false</code>. 0N/A * @exception IllegalArgumentException if any of the following are true: 0N/A * <li> <code>raster</code> is <code>null</code>. 0N/A * <li> <code>param</code> is <code>null</code>. 0N/A * <li> the intersected region does not contain at least one pixel. 0N/A * <li> the layout of <code>raster</code> does not match, or this 0N/A * writer cannot convert it to, the existing image layout. 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Terminates a sequence of calls to <code>replacePixels</code>. 0N/A * <p> If <code>canReplacePixels</code> returns 0N/A * <code>false</code>, and 0N/A * <code>UnsupportedOperationException</code> will be thrown. 0N/A * <p> The default implementation throws an 0N/A * <code>IllegalStateException</code> if the output is 0N/A * <code>null</code>, and otherwise throws an 0N/A * <code>UnsupportedOperationException</code>. 0N/A * @exception IllegalStateException if the output has not 0N/A * @exception UnsupportedOperationException if 0N/A * <code>canReplacePixels(imageIndex)</code> returns 0N/A * <code>false</code>. 0N/A * @exception IllegalStateException if there is no previous call 0N/A * to <code>prepareReplacePixels</code> without a matching call to 0N/A * <code>endReplacePixels</code>. 0N/A * @exception IOException if an I/O error occurs during writing. 0N/A * Requests that any current write operation be aborted. The 0N/A * contents of the output following the abort will be undefined. 0N/A * <p> Writers should call <code>clearAbortRequest</code> at the 0N/A * beginning of each write operation, and poll the value of 0N/A * <code>abortRequested</code> regularly during the write. 0N/A * Returns <code>true</code> if a request to abort the current 0N/A * write operation has been made since the writer was instantiated or 0N/A * <code>clearAbortRequest</code> was called. 0N/A * @return <code>true</code> if the current write operation should 0N/A * @see #clearAbortRequest 0N/A * Clears any previous abort request. After this method has been 0N/A * called, <code>abortRequested</code> will return 0N/A * <code>false</code>. 0N/A * @see #abortRequested 0N/A * Adds an <code>IIOWriteWarningListener</code> to the list of 0N/A * registered warning listeners. If <code>listener</code> is 0N/A * <code>null</code>, no exception will be thrown and no action 0N/A * will be taken. Messages sent to the given listener will be 0N/A * localized, if possible, to match the current 0N/A * <code>Locale</code>. If no <code>Locale</code> has been set, 0N/A * warning messages may be localized as the writer sees fit. 0N/A * @param listener an <code>IIOWriteWarningListener</code> to be 0N/A * @see #removeIIOWriteWarningListener 0N/A * Removes an <code>IIOWriteWarningListener</code> from the list 0N/A * of registered warning listeners. If the listener was not 0N/A * previously registered, or if <code>listener</code> is 0N/A * <code>null</code>, no exception will be thrown and no action 0N/A * @param listener an <code>IIOWriteWarningListener</code> to be 0N/A * @see #addIIOWriteWarningListener 0N/A * Removes all currently registered 0N/A * <code>IIOWriteWarningListener</code> objects. 0N/A * <p> The default implementation sets the 0N/A * <code>warningListeners</code> and <code>warningLocales</code> 0N/A * instance variables to <code>null</code>. 0N/A * Adds an <code>IIOWriteProgressListener</code> to the list of 0N/A * registered progress listeners. If <code>listener</code> is 0N/A * <code>null</code>, no exception will be thrown and no action 0N/A * @param listener an <code>IIOWriteProgressListener</code> to be 0N/A * @see #removeIIOWriteProgressListener 0N/A * Removes an <code>IIOWriteProgressListener</code> from the list 0N/A * of registered progress listeners. If the listener was not 0N/A * previously registered, or if <code>listener</code> is 0N/A * <code>null</code>, no exception will be thrown and no action 0N/A * @param listener an <code>IIOWriteProgressListener</code> to be 0N/A * @see #addIIOWriteProgressListener 0N/A * Removes all currently registered 0N/A * <code>IIOWriteProgressListener</code> objects. 0N/A * <p> The default implementation sets the 0N/A * <code>progressListeners</code> instance variable to 0N/A * <code>null</code>. 0N/A * Broadcasts the start of an image write to all registered 0N/A * <code>IIOWriteProgressListener</code>s by calling their 0N/A * <code>imageStarted</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * @param imageIndex the index of the image about to be written. 0N/A * Broadcasts the current percentage of image completion to all 0N/A * registered <code>IIOWriteProgressListener</code>s by calling 0N/A * their <code>imageProgress</code> method. Subclasses may use 0N/A * this method as a convenience. 0N/A * @param percentageDone the current percentage of completion, 0N/A * as a <code>float</code>. 0N/A * Broadcasts the completion of an image write to all registered 0N/A * <code>IIOWriteProgressListener</code>s by calling their 0N/A * <code>imageComplete</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * Broadcasts the start of a thumbnail write to all registered 0N/A * <code>IIOWriteProgressListener</code>s by calling their 0N/A * <code>thumbnailStarted</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * @param imageIndex the index of the image associated with the 0N/A * @param thumbnailIndex the index of the thumbnail. 0N/A * Broadcasts the current percentage of thumbnail completion to 0N/A * all registered <code>IIOWriteProgressListener</code>s by calling 0N/A * their <code>thumbnailProgress</code> method. Subclasses may 0N/A * use this method as a convenience. 0N/A * @param percentageDone the current percentage of completion, 0N/A * as a <code>float</code>. 0N/A * Broadcasts the completion of a thumbnail write to all registered 0N/A * <code>IIOWriteProgressListener</code>s by calling their 0N/A * <code>thumbnailComplete</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * Broadcasts that the write has been aborted to all registered 0N/A * <code>IIOWriteProgressListener</code>s by calling their 0N/A * <code>writeAborted</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * Broadcasts a warning message to all registered 0N/A * <code>IIOWriteWarningListener</code>s by calling their 0N/A * <code>warningOccurred</code> method. Subclasses may use this 0N/A * method as a convenience. 0N/A * @param imageIndex the index of the image on which the warning 0N/A * @param warning the warning message. 0N/A * @exception IllegalArgumentException if <code>warning</code> 0N/A * is <code>null</code>. 0N/A * Broadcasts a localized warning message to all registered 0N/A * <code>IIOWriteWarningListener</code>s by calling their 0N/A * <code>warningOccurred</code> method with a string taken 0N/A * from a <code>ResourceBundle</code>. Subclasses may use this 0N/A * method as a convenience. 0N/A * @param imageIndex the index of the image on which the warning 0N/A * @param baseName the base name of a set of 0N/A * <code>ResourceBundle</code>s containing localized warning 0N/A * @param keyword the keyword used to index the warning message 0N/A * within the set of <code>ResourceBundle</code>s. 0N/A * @exception IllegalArgumentException if <code>baseName</code> 0N/A * is <code>null</code>. 0N/A * @exception IllegalArgumentException if <code>keyword</code> 0N/A * is <code>null</code>. 0N/A * @exception IllegalArgumentException if no appropriate 0N/A * <code>ResourceBundle</code> may be located. 0N/A * @exception IllegalArgumentException if the named resource is 0N/A * not found in the located <code>ResourceBundle</code>. 0N/A * @exception IllegalArgumentException if the object retrieved 0N/A * from the <code>ResourceBundle</code> is not a 0N/A * <code>String</code>. 0N/A * If an applet supplies an implementation of ImageWriter and 0N/A * resource bundles, then the resource bundle will need to be 0N/A * accessed via the applet class loader. So first try the context 0N/A * class loader to locate the resource bundle. 0N/A * If that throws MissingResourceException, then try the 0N/A * system class loader. 0N/A * Restores the <code>ImageWriter</code> to its initial state. 0N/A * <p> The default implementation calls 0N/A * <code>setOutput(null)</code>, <code>setLocale(null)</code>, 0N/A * <code>removeAllIIOWriteWarningListeners()</code>, 0N/A * <code>removeAllIIOWriteProgressListeners()</code>, and 0N/A * <code>clearAbortRequest</code>. 0N/A * Allows any resources held by this object to be released. The 0N/A * result of calling any other method (other than 0N/A * <code>finalize</code>) subsequent to a call to this method 0N/A * <p>It is important for applications to call this method when they 0N/A * know they will no longer be using this <code>ImageWriter</code>. 0N/A * Otherwise, the writer may continue to hold on to resources 0N/A * <p>The default implementation of this method in the superclass does 0N/A * nothing. Subclass implementations should ensure that all resources, 0N/A * especially native resources, are released.