​ setOutput

public void setOutput(Object output)

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.
Parameters:
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()
​
​ getOutput
public Object getOutput()
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.
Returns:
the Object that was specified using setOutput, or null.
See Also:
​ setOutput(java.lang.Object)
​
​ getAvailableLocales
public Locale[] getAvailableLocales()
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.
​ setLocale
public void setLocale(Locale locale)
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.
Parameters:
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()
​
​ getLocale
public Locale getLocale()
Returns the currently set Locale, or null if none has been set.
The default implementation returns the value of the locale instance variable.
Returns:
the current Locale, or null.
See Also:
​ setLocale(java.util.Locale)
​
​ getDefaultWriteParam
public ImageWriteParam getDefaultWriteParam()
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.
​ getDefaultStreamMetadata
public abstract IIOMetadata
getDefaultStreamMetadata(ImageWriteParam param)
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.
Parameters:
param - an ImageWriteParam that will be used to encode the image, or null.
Returns:
an IIOMetadata object.

​ getDefaultImageMetadata
public abstract IIOMetadata
getDefaultImageMetadata(ImageTypeSpecifier imageType,
​ 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.
Parameters:
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.

​ getNumThumbnailsSupported
public int getNumThumbnailsSupported(ImageTypeSpecifier
imageType,

​ ImageWriteParam param,

​ IIOMetadata streamMetadata,
​ IIOMetadata imageMetadata)
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.
Parameters:
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.

​ getPreferredThumbnailSizes
public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier
imageType,

​ ImageWriteParam param,

​ IIOMetadata streamMetadata,
​ IIOMetadata imageMetadata)
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.
Parameters:
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.
​ canWriteRasters
public boolean canWriteRasters()
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.

​ write
public abstract void write(IIOMetadata streamMetadata,

​ IIOImage image,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.

​ write
public void write(IIOImage image)
​ 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).
Parameters:
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.

​ write
public void write(RenderedImage image)
​ throws IOException
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).
 Parameters:
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.
​ canWriteSequence
public boolean canWriteSequence()
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.

​ prepareWriteSequence
public void prepareWriteSequence(IIOMetadata streamMetadata)
​ throws IOException
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.
Parameters:
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.

​ writeToSequence
public void writeToSequence(IIOImage image,
​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.

​ endWriteSequence
public void endWriteSequence()
​ throws IOException
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.

​ canReplaceStreamMetadata
public boolean canReplaceStreamMetadata()
​ throws IOException
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.
Returns:
true if replacement of stream metadata is allowed.
Throws:
IllegalStateException - if the output has not been set.
IOException - if an I/O error occurs during the query.

​ replaceStreamMetadata
public void replaceStreamMetadata(IIOMetadata streamMetadata)
​ throws IOException
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.
Parameters:
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.

​ canReplaceImageMetadata
public boolean canReplaceImageMetadata(int imageIndex)
​ throws IOException
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.
Parameters:
imageIndex - the index of the image whose metadata is to be replaced.
Returns:
true if the image metadata of the given image can 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.

​ replaceImageMetadata
public void replaceImageMetadata(int imageIndex,

​ IIOMetadata imageMetadata)
​ throws IOException
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.
Parameters:
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.

​ canInsertImage
public boolean canInsertImage(int imageIndex)
​ throws IOException
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.
Parameters:
imageIndex - the index at which the image is to be inserted.
Returns:
true if an image may be inserted at the given index.
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.

​ writeInsert
public void writeInsert(int imageIndex,

​ IIOImage image,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.

​ canRemoveImage
public boolean canRemoveImage(int imageIndex)
​ throws IOException
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.
Parameters:
imageIndex - the index of the image to be removed.
Returns:
true if it is possible to remove the given image.
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.

​ removeImage
public void removeImage(int imageIndex)
​ throws IOException
Removes an image from the stream.
If canRemoveImage(imageIndex) returns false, an
UnsupportedOperationException will 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.
Parameters:
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.

​ canWriteEmpty
public boolean canWriteEmpty()
​ throws IOException
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.
Returns:
true if the writing of complete image stream with contents to be defined later is
supported.
Throws:
IllegalStateException - if the output has not been set.
IOException - if an I/O error occurs during the query.

​ prepareWriteEmpty
public void prepareWriteEmpty(IIOMetadata streamMetadata,

​ ImageTypeSpecifier imageType,

​ int width,

​ int height,

​ IIOMetadata imageMetadata,
​ List<? extends BufferedImage> thumbnails,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.

​ endWriteEmpty
public void endWriteEmpty()
​ throws IOException
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.

​ canInsertEmpty
public boolean canInsertEmpty(int imageIndex)
​ throws IOException
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.
Parameters:
imageIndex - the index at which the image is to be inserted.
Returns:
true if an empty image may be inserted at the given index.
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.

​ prepareInsertEmpty
public void prepareInsertEmpty(int imageIndex,

​ ImageTypeSpecifier imageType,

​ int width,

​ int height,

​ IIOMetadata imageMetadata,

​ List<? extends BufferedImage> thumbnails,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.

​ endInsertEmpty
public void endInsertEmpty()
​ throws IOException
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.

​ canReplacePixels
public boolean canReplacePixels(int imageIndex)
​ throws IOException
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.
Parameters:
imageIndex - the index of the image whose pixels are to be replaced.
Returns:
true if the pixels of the given image can 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.

​ prepareReplacePixels
public void prepareReplacePixels(int imageIndex,

​ Rectangle region)
​ throws IOException
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.
Parameters:
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.
​ replacePixels
public void replacePixels(RenderedImage image,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.
​ 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.

​ replacePixels
public void replacePixels(Raster raster,

​ ImageWriteParam param)
​ throws IOException
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.
Parameters:
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.
​ 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.

​ endReplacePixels
public void endReplacePixels()
​ throws IOException
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.
​ abort
public void 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.
​ abortRequested
protected boolean abortRequested()
Returns true if a request to abort the current write operation has been made since the
writer was instantiated or clearAbortRequest was called.
Returns:
true if the current write operation should be aborted.
See Also:
​ abort()
​ clearAbortRequest()
​
​ clearAbortRequest
protected void clearAbortRequest()
Clears any previous abort request. After this method has been called,
abortRequested will return false.
See Also:
​ abort()
​ abortRequested()
​
​ addIIOWriteWarningListener
public void addIIOWriteWarningListener(IIOWriteWarningListener
listener)
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.
Parameters:
 listener - an IIOWriteWarningListener to be registered.
See Also:
​ removeIIOWriteWarningListener(javax.imageio.event.IIOWrite
WarningListener)
​
​ removeIIOWriteWarningListener
public void
removeIIOWriteWarningListener(IIOWriteWarningListener listener)
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.
Parameters:
listener - an IIOWriteWarningListener to be deregistered.
See Also:
​ addIIOWriteWarningListener(javax.imageio.event.IIOWriteWar
ningListener)
​
​ removeAllIIOWriteWarningListeners
public void removeAllIIOWriteWarningListeners()
Removes all currently registered IIOWriteWarningListener objects.
The default implementation sets the warningListeners and warningLocales
instance variables to null.
​ addIIOWriteProgressListener
public void addIIOWriteProgressListener(IIOWriteProgressListener
listener)
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.
Parameters:
listener - an IIOWriteProgressListener to be registered.
See Also:
​ removeIIOWriteProgressListener(javax.imageio.event.IIOWrit
eProgressListener)
​
​ removeIIOWriteProgressListener
public void
removeIIOWriteProgressListener(IIOWriteProgressListener
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.
Parameters:
 listener - an IIOWriteProgressListener to be deregistered.
See Also:
​ addIIOWriteProgressListener(javax.imageio.event.IIOWritePr
ogressListener)
​
​ removeAllIIOWriteProgressListeners
public void removeAllIIOWriteProgressListeners()
Removes all currently registered IIOWriteProgressListener objects.
The default implementation sets the progressListeners instance variable to null.
​ processImageStarted
protected void processImageStarted(int imageIndex)
Broadcasts the start of an image write to all registered IIOWriteProgressListeners
by calling their imageStarted method. Subclasses may use this method as a
convenience.
Parameters:
imageIndex - the index of the image about to be written.
​ processImageProgress
protected void processImageProgress(float percentageDone)
Broadcasts the current percentage of image completion to all registered
IIOWriteProgressListeners by calling their imageProgress method. Subclasses
may use this method as a convenience.
Parameters:
percentageDone - the current percentage of completion, as a float.
​ processImageComplete
protected void processImageComplete()
Broadcasts the completion of an image write to all registered
IIOWriteProgressListeners by calling their imageComplete method. Subclasses
may use this method as a convenience.

​ processThumbnailStarted
protected void processThumbnailStarted(int imageIndex,
​ int thumbnailIndex)
Broadcasts the start of a thumbnail write to all registered
IIOWriteProgressListeners by calling their thumbnailStarted method.
Subclasses may use this method as a convenience.
Parameters:
imageIndex - the index of the image associated with the thumbnail.
thumbnailIndex - the index of the thumbnail.
​ processThumbnailProgress
protected void processThumbnailProgress(float percentageDone)
Broadcasts the current percentage of thumbnail completion to all registered
 IIOWriteProgressListeners by calling their thumbnailProgress method.
Subclasses may use this method as a convenience.
Parameters:
percentageDone - the current percentage of completion, as a float.
​ processThumbnailComplete
protected void processThumbnailComplete()
Broadcasts the completion of a thumbnail write to all registered
IIOWriteProgressListeners by calling their thumbnailComplete method.
Subclasses may use this method as a convenience.
​ processWriteAborted
protected void processWriteAborted()
Broadcasts that the write has been aborted to all registered
IIOWriteProgressListeners by calling their writeAborted method. Subclasses
may use this method as a convenience.

​ processWarningOccurred
protected void processWarningOccurred(int imageIndex,
​ String warning)
Broadcasts a warning message to all registered IIOWriteWarningListeners by calling
their warningOccurred method. Subclasses may use this method as a convenience.
Parameters:
imageIndex - the index of the image on which the warning occurred.
warning - the warning message.
Throws:
IllegalArgumentException - if warning is null.

​ processWarningOccurred
protected void processWarningOccurred(int imageIndex,

​ String baseName,
​ String keyword)
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.
Parameters:
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.
​ reset
public void reset()
Restores the ImageWriter to its initial state.
The default implementation calls setOutput(null), setLocale(null),
removeAllIIOWriteWarningListeners(),
removeAllIIOWriteProgressListeners(), and clearAbortRequest.
​ dispose
public void dispose()
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.