ImageTranscoder
public abstract class ImageWriter extends Object implements ImageTranscoder
ImageWriter
objects are normally instantiated by the service provider class for the specific format. Service provider classes are registered with the IIORegistry
, which uses them for format recognition and presentation of available format readers and writers.
Modifier and Type | Field | Description |
---|---|---|
protected Locale[] |
availableLocales |
An array of Locale s that may be used to localize warning messages and compression setting values, or null if localization is not supported. |
protected Locale |
locale |
The current Locale to be used for localization, or null if none has been set. |
protected ImageWriterSpi |
originatingProvider |
The ImageWriterSpi that instantiated this object, or null if its identity is not known or none exists. |
protected Object |
output |
The ImageOutputStream or other Object set by setOutput and retrieved by getOutput . |
protected List |
progressListeners |
A List of currently registered IIOWriteProgressListener s, initialized by default null , which is synonymous with an empty List . |
protected List |
warningListeners |
A List of currently registered IIOWriteWarningListener s, initialized by default to null , which is synonymous with an empty List . |
protected List |
warningLocales |
A List of Locale s, one for each element of warningListeners , initialized by default null , which is synonymous with an empty List . |
Modifier | Constructor | Description |
---|---|---|
protected |
Constructs an ImageWriter and sets its originatingProvider instance variable to the supplied value. |
Modifier and Type | Method | Description |
---|---|---|
void |
abort() |
Requests that any current write operation be aborted. |
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. |
void |
addIIOWriteProgressListener |
Adds an IIOWriteProgressListener to the list of registered progress listeners. |
void |
addIIOWriteWarningListener |
Adds an IIOWriteWarningListener to the list of registered warning listeners. |
boolean |
canInsertEmpty |
Returns true if the writer supports the insertion of a new, empty image at the given index. |
boolean |
canInsertImage |
Returns true if the writer supports the insertion of a new image at the given index. |
boolean |
canRemoveImage |
Returns true if the writer supports the removal of an existing image at the given index. |
boolean |
canReplaceImageMetadata |
Returns true if it is possible to replace the image metadata associated with an existing image with index imageIndex . |
boolean |
canReplacePixels |
Returns true if the writer allows pixels of the given image to be replaced using the replacePixels methods. |
boolean |
canReplaceStreamMetadata() |
Returns true if it is possible to replace the stream metadata already present in the output. |
boolean |
canWriteEmpty() |
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. |
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. |
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. |
protected void |
clearAbortRequest() |
Clears any previous abort request. |
void |
dispose() |
Allows any resources held by this object to be released. |
void |
endInsertEmpty() |
Completes the insertion of a new image that was begun with a prior call to prepareInsertEmpty . |
void |
endReplacePixels() |
Terminates a sequence of calls to replacePixels . |
void |
endWriteEmpty() |
Completes the writing of a new image that was begun with a prior call to prepareWriteEmpty . |
void |
endWriteSequence() |
Completes the writing of a sequence of images begun with prepareWriteSequence . |
Locale[] |
getAvailableLocales() |
Returns an array of Locale s that may be used to localize warning listeners and compression settings. |
abstract IIOMetadata |
getDefaultImageMetadata |
Returns an IIOMetadata object containing default values for encoding an image of the given type. |
abstract IIOMetadata |
getDefaultStreamMetadata |
Returns an IIOMetadata object containing default values for encoding a stream of images. |
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. |
Locale |
getLocale() |
Returns the currently set Locale , or null if none has been set. |
int |
getNumThumbnailsSupported |
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. |
ImageWriterSpi |
getOriginatingProvider() |
Returns the ImageWriterSpi object that created this ImageWriter , or null if this object was not created through the IIORegistry . |
Object |
getOutput() |
Returns the ImageOutputStream or other Object set by the most recent call to the setOutput method. |
Dimension[] |
getPreferredThumbnailSizes |
Returns an array of Dimension s indicating the legal size ranges for thumbnail images as they will be encoded in the output file or stream. |
void |
prepareInsertEmpty |
Begins the insertion of a new image with undefined pixel values into an existing image stream. |
void |
prepareReplacePixels |
Prepares the writer to handle a series of calls to the replacePixels methods. |
void |
prepareWriteEmpty |
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. |
void |
prepareWriteSequence |
Prepares a stream to accept a series of subsequent writeToSequence calls, using the provided stream metadata object. |
protected void |
processImageComplete() |
Broadcasts the completion of an image write to all registered IIOWriteProgressListener s by calling their imageComplete method. |
protected void |
processImageProgress |
Broadcasts the current percentage of image completion to all registered IIOWriteProgressListener s by calling their imageProgress method. |
protected void |
processImageStarted |
Broadcasts the start of an image write to all registered IIOWriteProgressListener s by calling their imageStarted method. |
protected void |
processThumbnailComplete() |
Broadcasts the completion of a thumbnail write to all registered IIOWriteProgressListener s by calling their thumbnailComplete method. |
protected void |
processThumbnailProgress |
Broadcasts the current percentage of thumbnail completion to all registered IIOWriteProgressListener s by calling their thumbnailProgress method. |
protected void |
processThumbnailStarted |
Broadcasts the start of a thumbnail write to all registered IIOWriteProgressListener s by calling their thumbnailStarted method. |
protected void |
processWarningOccurred |
Broadcasts a warning message to all registered IIOWriteWarningListener s by calling their warningOccurred method. |
protected void |
processWarningOccurred |
Broadcasts a localized warning message to all registered IIOWriteWarningListener s by calling their warningOccurred method with a string taken from a ResourceBundle . |
protected void |
processWriteAborted() |
Broadcasts that the write has been aborted to all registered IIOWriteProgressListener s by calling their writeAborted method. |
void |
removeAllIIOWriteProgressListeners() |
Removes all currently registered IIOWriteProgressListener objects. |
void |
removeAllIIOWriteWarningListeners() |
Removes all currently registered IIOWriteWarningListener objects. |
void |
removeIIOWriteProgressListener |
Removes an IIOWriteProgressListener from the list of registered progress listeners. |
void |
removeIIOWriteWarningListener |
Removes an IIOWriteWarningListener from the list of registered warning listeners. |
void |
removeImage |
Removes an image from the stream. |
void |
replaceImageMetadata |
Replaces the image metadata associated with an existing image. |
void |
replacePixels |
Replaces a portion of an image already present in the output with a portion of the given Raster . |
void |
replacePixels |
Replaces a portion of an image already present in the output with a portion of the given image. |
void |
replaceStreamMetadata |
Replaces the stream metadata in the output with new information. |
void |
reset() |
Restores the ImageWriter to its initial state. |
void |
setLocale |
Sets the current Locale of this ImageWriter to the given value. |
void |
setOutput |
Sets the destination to the given ImageOutputStream or other Object . |
void |
write |
Appends a complete image stream consisting of a single image with default metadata and thumbnails to the output. |
void |
write |
Appends a complete image stream containing a single image with default metadata and thumbnails to the output. |
abstract void |
write |
Appends a complete image stream containing a single image and associated stream and image metadata and thumbnails to the output. |
void |
writeInsert |
Inserts a new image into an existing image stream. |
void |
writeToSequence |
Appends a single image and possibly associated metadata and thumbnails, to the output. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
convertImageMetadata, convertStreamMetadata
protected ImageWriterSpi originatingProvider
ImageWriterSpi
that instantiated this object, or null
if its identity is not known or none exists. By default it is initialized to null
.protected Object output
ImageOutputStream
or other Object
set by setOutput
and retrieved by getOutput
. By default it is initialized to null
.protected Locale[] availableLocales
Locale
s that may be used to localize warning messages and compression setting values, or null
if localization is not supported. By default it is initialized to null
.protected Locale locale
Locale
to be used for localization, or null
if none has been set. By default it is initialized to null
.protected List<IIOWriteWarningListener> warningListeners
List
of currently registered IIOWriteWarningListener
s, initialized by default to null
, which is synonymous with an empty List
.protected List<Locale> warningLocales
List
of Locale
s, one for each element of warningListeners
, initialized by default null
, which is synonymous with an empty List
.protected List<IIOWriteProgressListener> progressListeners
List
of currently registered IIOWriteProgressListener
s, initialized by default null
, which is synonymous with an empty List
.protected ImageWriter(ImageWriterSpi originatingProvider)
ImageWriter
and sets its originatingProvider
instance variable to the supplied value. Subclasses that make use of extensions should provide a constructor with signature (ImageWriterSpi, Object)
in order to retrieve the extension object. If the extension object is unsuitable, an IllegalArgumentException
should be thrown.
originatingProvider
- the ImageWriterSpi
that is constructing this object, or null
.public ImageWriterSpi getOriginatingProvider()
ImageWriterSpi
object that created this ImageWriter
, or null
if this object was not created through the IIORegistry
. The default implementation returns the value of the originatingProvider
instance variable.
ImageWriterSpi
, or null
.public void setOutput(Object output)
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.
output
- the ImageOutputStream
or other Object
to use for future writing.IllegalArgumentException
- if output
is not an instance of one of the classes returned by the originating service provider's getOutputTypes
method.public Object getOutput()
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.
Object
that was specified using setOutput
, or null
.public Locale[] getAvailableLocales()
Locale
s 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
.
Locale
s that may be used as arguments to setLocale
, or null
.public void setLocale(Locale locale)
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.
locale
- the desired Locale
, or null
.IllegalArgumentException
- if locale
is non-null
but is not one of the values returned by getAvailableLocales
.public Locale getLocale()
Locale
, or null
if none has been set. The default implementation returns the value of the locale
instance variable.
Locale
, or null
.public ImageWriteParam getDefaultWriteParam()
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
.
ImageWriteParam
object containing default values.public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)
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
.
param
- an ImageWriteParam
that will be used to encode the image, or null
.IIOMetadata
object.public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param)
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.
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
.IIOMetadata
object.public int getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
-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.
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
.-1
if insufficient information is available.public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
Dimension
s indicating the legal size ranges for thumbnail images as they will be encoded in the output file or stream. This information is merely advisory; the writer will resize any supplied thumbnails as necessary. 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
.
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
.Dimension
s with an even length of at least two, or null
.public boolean canWriteRasters()
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
.
true
if Raster
sources are supported.public abstract void write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) throws IOException
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.
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
.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.public void write(IIOImage image) throws IOException
write(null, image, null)
.image
- an IIOImage
object containing an image, thumbnails, and metadata to be written.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.public void write(RenderedImage image) throws IOException
write(null, new IIOImage(image, null, null), null)
.image
- a RenderedImage
to be written.IllegalStateException
- if the output has not been set.IllegalArgumentException
- if image
is null
.IOException
- if an error occurs during writing.public boolean canWriteSequence()
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
.
true
if images may be appended sequentially.public void prepareWriteSequence(IIOMetadata streamMetadata) throws IOException
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
.
streamMetadata
- A stream metadata object, or null
.IllegalStateException
- if the output has not been set.UnsupportedOperationException
- if canWriteSequence
returns false
.IOException
- if an error occurs writing the stream metadata.public void writeToSequence(IIOImage image, ImageWriteParam param) throws IOException
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
.
image
- an IIOImage
object containing an image, thumbnails, and metadata to be written.param
- an ImageWriteParam
, or null
to use a default ImageWriteParam
.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.public void endWriteSequence() throws IOException
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
.
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.public boolean canReplaceStreamMetadata() throws IOException
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
.
true
if replacement of stream metadata is allowed.IllegalStateException
- if the output has not been set.IOException
- if an I/O error occurs during the query.public void replaceStreamMetadata(IIOMetadata streamMetadata) throws IOException
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
.
streamMetadata
- an IIOMetadata
object representing stream metadata, or null
to use default values.IllegalStateException
- if the output has not been set.UnsupportedOperationException
- if the canReplaceStreamMetadata
returns false
. modes do not includeIOException
- if an error occurs during writing.public boolean canReplaceImageMetadata(int imageIndex) throws IOException
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
.
imageIndex
- the index of the image whose metadata is to be replaced.true
if the image metadata of the given image can be replaced.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.public void replaceImageMetadata(int imageIndex, IIOMetadata imageMetadata) throws IOException
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
.
imageIndex
- the index of the image whose metadata is to be replaced.imageMetadata
- an IIOMetadata
object representing image metadata, or null
.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.public boolean canInsertImage(int imageIndex) throws IOException
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
.
imageIndex
- the index at which the image is to be inserted.true
if an image may be inserted at the given index.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.public void writeInsert(int imageIndex, IIOImage image, ImageWriteParam param) throws IOException
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
.
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
.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.public boolean canRemoveImage(int imageIndex) throws IOException
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
.
imageIndex
- the index of the image to be removed.true
if it is possible to remove the given image.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.public void removeImage(int imageIndex) throws IOException
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
.
imageIndex
- the index of the image to be removed.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.public boolean canWriteEmpty() throws IOException
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
.
true
if the writing of complete image stream with contents to be defined later is supported.IllegalStateException
- if the output has not been set.IOException
- if an I/O error occurs during the query.public void prepareWriteEmpty(IIOMetadata streamMetadata, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
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
.
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
.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 BufferedImage
s.IllegalArgumentException
- if width or height are less than 1.IOException
- if an I/O error occurs during writing.public void endWriteEmpty() throws IOException
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
.
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.public boolean canInsertEmpty(int imageIndex) throws IOException
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
.
imageIndex
- the index at which the image is to be inserted.true
if an empty image may be inserted at the given index.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.public void prepareInsertEmpty(int imageIndex, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
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
.
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
.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 BufferedImage
s.IllegalArgumentException
- if width or height are less than 1.IOException
- if an I/O error occurs during writing.public void endInsertEmpty() throws IOException
prepareInsertEmpty
. The default implementation throws an IllegalStateException
if the output is null
, and otherwise throws an UnsupportedOperationException
.
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.public boolean canReplacePixels(int imageIndex) throws IOException
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
.
imageIndex
- the index of the image whose pixels are to be replaced.true
if the pixels of the given image can be replaced.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.public void prepareReplacePixels(int imageIndex, Rectangle region) throws IOException
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
.
imageIndex
- the index of the image whose pixels are to be replaced.region
- a Rectangle
that will be used to clip future pixel regions.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.public void replacePixels(RenderedImage image, ImageWriteParam param) throws IOException
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
.
image
- a RenderedImage
containing source pixels.param
- an ImageWriteParam
, or null
to use a default ImageWriteParam
.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
. image
does not match, or this writer cannot convert it to, the existing image layout. IOException
- if an I/O error occurs during writing.public void replacePixels(Raster raster, ImageWriteParam param) throws IOException
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
.
raster
- a Raster
containing source pixels.param
- an ImageWriteParam
, or null
to use a default ImageWriteParam
.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
. raster
does not match, or this writer cannot convert it to, the existing image layout. IOException
- if an I/O error occurs during writing.public void endReplacePixels() throws IOException
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
.
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.public void abort()
Writers should call clearAbortRequest
at the beginning of each write operation, and poll the value of abortRequested
regularly during the write.
protected boolean abortRequested()
true
if a request to abort the current write operation has been made since the writer was instantiated or clearAbortRequest
was called.true
if the current write operation should be aborted.protected void clearAbortRequest()
abortRequested
will return false
.public void addIIOWriteWarningListener(IIOWriteWarningListener listener)
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.listener
- an IIOWriteWarningListener
to be registered.public void removeIIOWriteWarningListener(IIOWriteWarningListener listener)
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.listener
- an IIOWriteWarningListener
to be deregistered.public void removeAllIIOWriteWarningListeners()
IIOWriteWarningListener
objects. The default implementation sets the warningListeners
and warningLocales
instance variables to null
.
public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
IIOWriteProgressListener
to the list of registered progress listeners. If listener
is null
, no exception will be thrown and no action will be taken.listener
- an IIOWriteProgressListener
to be registered.public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)
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.listener
- an IIOWriteProgressListener
to be deregistered.public void removeAllIIOWriteProgressListeners()
IIOWriteProgressListener
objects. The default implementation sets the progressListeners
instance variable to null
.
protected void processImageStarted(int imageIndex)
IIOWriteProgressListener
s by calling their imageStarted
method. Subclasses may use this method as a convenience.imageIndex
- the index of the image about to be written.protected void processImageProgress(float percentageDone)
IIOWriteProgressListener
s by calling their imageProgress
method. Subclasses may use this method as a convenience.percentageDone
- the current percentage of completion, as a float
.protected void processImageComplete()
IIOWriteProgressListener
s by calling their imageComplete
method. Subclasses may use this method as a convenience.protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
IIOWriteProgressListener
s by calling their thumbnailStarted
method. Subclasses may use this method as a convenience.imageIndex
- the index of the image associated with the thumbnail.thumbnailIndex
- the index of the thumbnail.protected void processThumbnailProgress(float percentageDone)
IIOWriteProgressListener
s by calling their thumbnailProgress
method. Subclasses may use this method as a convenience.percentageDone
- the current percentage of completion, as a float
.protected void processThumbnailComplete()
IIOWriteProgressListener
s by calling their thumbnailComplete
method. Subclasses may use this method as a convenience.protected void processWriteAborted()
IIOWriteProgressListener
s by calling their writeAborted
method. Subclasses may use this method as a convenience.protected void processWarningOccurred(int imageIndex, String warning)
IIOWriteWarningListener
s by calling their warningOccurred
method. Subclasses may use this method as a convenience.imageIndex
- the index of the image on which the warning occurred.warning
- the warning message.IllegalArgumentException
- if warning
is null
.protected void processWarningOccurred(int imageIndex, String baseName, String keyword)
IIOWriteWarningListener
s by calling their warningOccurred
method with a string taken from a ResourceBundle
. Subclasses may use this method as a convenience.imageIndex
- the index of the image on which the warning occurred.baseName
- the base name of a set of ResourceBundle
s containing localized warning messages.keyword
- the keyword used to index the warning message within the set of ResourceBundle
s.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
.public void reset()
ImageWriter
to its initial state. The default implementation calls setOutput(null)
, setLocale(null)
, removeAllIIOWriteWarningListeners()
, removeAllIIOWriteProgressListeners()
, and clearAbortRequest
.
public void dispose()
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.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/imageio/ImageWriter.html