- All Implemented Interfaces:
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.
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionprotected Locale[]
An array ofLocale
s that may be used to localize warning messages and compression setting values, ornull
if localization is not supported.protected Locale
The currentLocale
to be used for localization, ornull
if none has been set.protected ImageWriterSpi
TheImageWriterSpi
that instantiated this object, ornull
if its identity is not known or none exists.protected Object
TheImageOutputStream
or otherObject
set bysetOutput
and retrieved bygetOutput
.protected List
<IIOWriteProgressListener> AList
of currently registeredIIOWriteProgressListener
s, initialized by defaultnull
, which is synonymous with an emptyList
.protected List
<IIOWriteWarningListener> AList
of currently registeredIIOWriteWarningListener
s, initialized by default tonull
, which is synonymous with an emptyList
.AList
ofLocale
s, one for each element ofwarningListeners
, initialized by defaultnull
, which is synonymous with an emptyList
. -
Constructor Summary
ModifierConstructorDescriptionprotected
ImageWriter
(ImageWriterSpi originatingProvider) Constructs anImageWriter
and sets itsoriginatingProvider
instance variable to the supplied value. -
Method Summary
Modifier and TypeMethodDescriptionvoid
abort()
Requests that any current write operation be aborted.protected boolean
Returnstrue
if a request to abort the current write operation has been made since the writer was instantiated orclearAbortRequest
was called.void
Adds anIIOWriteProgressListener
to the list of registered progress listeners.void
Adds anIIOWriteWarningListener
to the list of registered warning listeners.boolean
canInsertEmpty
(int imageIndex) Returnstrue
if the writer supports the insertion of a new, empty image at the given index.boolean
canInsertImage
(int imageIndex) Returnstrue
if the writer supports the insertion of a new image at the given index.boolean
canRemoveImage
(int imageIndex) Returnstrue
if the writer supports the removal of an existing image at the given index.boolean
canReplaceImageMetadata
(int imageIndex) Returnstrue
if it is possible to replace the image metadata associated with an existing image with indeximageIndex
.boolean
canReplacePixels
(int imageIndex) Returnstrue
if the writer allows pixels of the given image to be replaced using thereplacePixels
methods.boolean
Returnstrue
if it is possible to replace the stream metadata already present in the output.boolean
Returnstrue
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
Returnstrue
if the methods that take anIIOImage
parameter are capable of dealing with aRaster
(as opposed toRenderedImage
) source image.boolean
Returnstrue
if the writer is able to append an image to an image stream that already contains header information and possibly prior images.protected void
Clears any previous abort request.void
dispose()
Allows any resources held by this object to be released.void
Completes the insertion of a new image that was begun with a prior call toprepareInsertEmpty
.void
Terminates a sequence of calls toreplacePixels
.void
Completes the writing of a new image that was begun with a prior call toprepareWriteEmpty
.void
Completes the writing of a sequence of images begun withprepareWriteSequence
.Locale[]
Returns an array ofLocale
s that may be used to localize warning listeners and compression settings.abstract IIOMetadata
getDefaultImageMetadata
(ImageTypeSpecifier imageType, ImageWriteParam param) Returns anIIOMetadata
object containing default values for encoding an image of the given type.abstract IIOMetadata
Returns anIIOMetadata
object containing default values for encoding a stream of images.Returns a newImageWriteParam
object of the appropriate type for this file format containing default values, that is, those values that would be used if noImageWriteParam
object were specified.Returns the currently setLocale
, ornull
if none has been set.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.Returns theImageWriterSpi
object that created thisImageWriter
, ornull
if this object was not created through theIIORegistry
.Returns theImageOutputStream
or otherObject
set by the most recent call to thesetOutput
method.getPreferredThumbnailSizes
(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata) Returns an array ofDimension
s indicating the legal size ranges for thumbnail images as they will be encoded in the output file or stream.void
prepareInsertEmpty
(int imageIndex, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) Begins the insertion of a new image with undefined pixel values into an existing image stream.void
prepareReplacePixels
(int imageIndex, Rectangle region) Prepares the writer to handle a series of calls to thereplacePixels
methods.void
prepareWriteEmpty
(IIOMetadata streamMetadata, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) 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
(IIOMetadata streamMetadata) Prepares a stream to accept a series of subsequentwriteToSequence
calls, using the provided stream metadata object.protected void
Broadcasts the completion of an image write to all registeredIIOWriteProgressListener
s by calling theirimageComplete
method.protected void
processImageProgress
(float percentageDone) Broadcasts the current percentage of image completion to all registeredIIOWriteProgressListener
s by calling theirimageProgress
method.protected void
processImageStarted
(int imageIndex) Broadcasts the start of an image write to all registeredIIOWriteProgressListener
s by calling theirimageStarted
method.protected void
Broadcasts the completion of a thumbnail write to all registeredIIOWriteProgressListener
s by calling theirthumbnailComplete
method.protected void
processThumbnailProgress
(float percentageDone) Broadcasts the current percentage of thumbnail completion to all registeredIIOWriteProgressListener
s by calling theirthumbnailProgress
method.protected void
processThumbnailStarted
(int imageIndex, int thumbnailIndex) Broadcasts the start of a thumbnail write to all registeredIIOWriteProgressListener
s by calling theirthumbnailStarted
method.protected void
processWarningOccurred
(int imageIndex, String warning) Broadcasts a warning message to all registeredIIOWriteWarningListener
s by calling theirwarningOccurred
method.protected void
processWarningOccurred
(int imageIndex, String baseName, String keyword) Broadcasts a localized warning message to all registeredIIOWriteWarningListener
s by calling theirwarningOccurred
method with a string taken from aResourceBundle
.protected void
Broadcasts that the write has been aborted to all registeredIIOWriteProgressListener
s by calling theirwriteAborted
method.void
Removes all currently registeredIIOWriteProgressListener
objects.void
Removes all currently registeredIIOWriteWarningListener
objects.void
Removes anIIOWriteProgressListener
from the list of registered progress listeners.void
Removes anIIOWriteWarningListener
from the list of registered warning listeners.void
removeImage
(int imageIndex) Removes an image from the stream.void
replaceImageMetadata
(int imageIndex, IIOMetadata imageMetadata) Replaces the image metadata associated with an existing image.void
replacePixels
(Raster raster, ImageWriteParam param) Replaces a portion of an image already present in the output with a portion of the givenRaster
.void
replacePixels
(RenderedImage image, ImageWriteParam param) Replaces a portion of an image already present in the output with a portion of the given image.void
replaceStreamMetadata
(IIOMetadata streamMetadata) Replaces the stream metadata in the output with new information.void
reset()
Restores theImageWriter
to its initial state.void
Sets the currentLocale
of thisImageWriter
to the given value.void
Sets the destination to the givenImageOutputStream
or otherObject
.void
write
(RenderedImage image) Appends a complete image stream consisting of a single image with default metadata and thumbnails to the output.void
Appends a complete image stream containing a single image with default metadata and thumbnails to the output.abstract void
write
(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) Appends a complete image stream containing a single image and associated stream and image metadata and thumbnails to the output.void
writeInsert
(int imageIndex, IIOImage image, ImageWriteParam param) Inserts a new image into an existing image stream.void
writeToSequence
(IIOImage image, ImageWriteParam param) Appends a single image and possibly associated metadata and thumbnails, to the output.Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods declared in interface javax.imageio.ImageTranscoder
convertImageMetadata, convertStreamMetadata
-
Field Details
-
originatingProvider
TheImageWriterSpi
that instantiated this object, ornull
if its identity is not known or none exists. By default it is initialized tonull
. -
output
TheImageOutputStream
or otherObject
set bysetOutput
and retrieved bygetOutput
. By default it is initialized tonull
. -
availableLocales
An array ofLocale
s that may be used to localize warning messages and compression setting values, ornull
if localization is not supported. By default it is initialized tonull
. -
locale
The currentLocale
to be used for localization, ornull
if none has been set. By default it is initialized tonull
. -
warningListeners
AList
of currently registeredIIOWriteWarningListener
s, initialized by default tonull
, which is synonymous with an emptyList
. -
warningLocales
AList
ofLocale
s, one for each element ofwarningListeners
, initialized by defaultnull
, which is synonymous with an emptyList
. -
progressListeners
AList
of currently registeredIIOWriteProgressListener
s, initialized by defaultnull
, which is synonymous with an emptyList
.
-
-
Constructor Details
-
ImageWriter
Constructs anImageWriter
and sets itsoriginatingProvider
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, anIllegalArgumentException
should be thrown.- Parameters:
originatingProvider
- theImageWriterSpi
that is constructing this object, ornull
.
-
-
Method Details
-
getOriginatingProvider
Returns theImageWriterSpi
object that created thisImageWriter
, ornull
if this object was not created through theIIORegistry
.The default implementation returns the value of the
originatingProvider
instance variable.- Returns:
- an
ImageWriterSpi
, ornull
. - See Also:
-
setOutput
Sets the destination to the givenImageOutputStream
or otherObject
. 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. Ifoutput
isnull
, any currently set output will be removed.If
output
is anImageOutputStream
, calls to thewrite
,writeToSequence
, andprepareWriteEmpty
/endWriteEmpty
methods will preserve the existing contents of the stream. Other write methods, such aswriteInsert
,replaceStreamMetadata
,replaceImageMetadata
,replacePixels
,prepareInsertEmpty
/endInsertEmpty
, andendWriteSequence
, 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 anImageOutputStream
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'sgetOutputTypes
method; most writers will return a single-element array containing onlyImageOutputStream.class
to indicate that they accept only anImageOutputStream
.The default implementation sets the
output
instance variable to the value ofoutput
after checkingoutput
against the set of classes advertised by the originating provider, if there is one.- Parameters:
output
- theImageOutputStream
or otherObject
to use for future writing.- Throws:
IllegalArgumentException
- ifoutput
is not an instance of one of the classes returned by the originating service provider'sgetOutputTypes
method.- See Also:
-
getOutput
Returns theImageOutputStream
or otherObject
set by the most recent call to thesetOutput
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 usingsetOutput
, ornull
. - See Also:
-
getAvailableLocales
Returns an array ofLocale
s that may be used to localize warning listeners and compression settings. A return value ofnull
indicates that localization is not supported.The default implementation returns a clone of the
availableLocales
instance variable if it is non-null
, or else returnsnull
.- Returns:
- an array of
Locale
s that may be used as arguments tosetLocale
, ornull
.
-
setLocale
Sets the currentLocale
of thisImageWriter
to the given value. A value ofnull
removes any previous setting, and indicates that the writer should localize as it sees fit.The default implementation checks
locale
against the values returned bygetAvailableLocales
, and sets thelocale
instance variable if it is found. Iflocale
isnull
, the instance variable is set tonull
without any checking.- Parameters:
locale
- the desiredLocale
, ornull
.- Throws:
IllegalArgumentException
- iflocale
is non-null
but is not one of the values returned bygetAvailableLocales
.- See Also:
-
getLocale
Returns the currently setLocale
, ornull
if none has been set.The default implementation returns the value of the
locale
instance variable.- Returns:
- the current
Locale
, ornull
. - See Also:
-
getDefaultWriteParam
Returns a newImageWriteParam
object of the appropriate type for this file format containing default values, that is, those values that would be used if noImageWriteParam
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 currentLocale
(i.e., what you would get by callingnew 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 ofImageWriteParam
.- Returns:
- a new
ImageWriteParam
object containing default values.
-
getDefaultStreamMetadata
Returns anIIOMetadata
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 theIIOMetadata.getAsTree
method, anIIOMetadataController
object, or via plug-in specific interfaces, and the resulting data supplied to one of thewrite
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
- anImageWriteParam
that will be used to encode the image, ornull
.- Returns:
- an
IIOMetadata
object.
-
getDefaultImageMetadata
public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param) Returns anIIOMetadata
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 theIIOMetadata.getAsTree
method, anIIOMetadataController
object, or via plug-in specific interfaces, and the resulting data supplied to one of thewrite
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
- anImageTypeSpecifier
indicating the format of the image to be written later.param
- anImageWriteParam
that will be used to encode the image, ornull
.- 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
- anImageTypeSpecifier
indicating the type of image to be written, ornull
.param
- theImageWriteParam
that will be used for writing, ornull
.streamMetadata
- anIIOMetadata
object that will be used for writing, ornull
.imageMetadata
- anIIOMetadata
object that will be used for writing, ornull
.- 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 ofDimension
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
.- Parameters:
imageType
- anImageTypeSpecifier
indicating the type of image to be written, ornull
.param
- theImageWriteParam
that will be used for writing, ornull
.streamMetadata
- anIIOMetadata
object that will be used for writing, ornull
.imageMetadata
- anIIOMetadata
object that will be used for writing, ornull
.- Returns:
- an array of
Dimension
s with an even length of at least two, ornull
.
-
canWriteRasters
public boolean canWriteRasters()Returnstrue
if the methods that take anIIOImage
parameter are capable of dealing with aRaster
(as opposed toRenderedImage
) source image. If this method returnsfalse
, then those methods will throw anUnsupportedOperationException
if supplied with anIIOImage
containing aRaster
.The default implementation returns
false
.- Returns:
true
ifRaster
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 anImageOutputStream
, 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
returnstrue
, theIIOImage
may contain aRaster
source. Otherwise, it must contain aRenderedImage
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. Ifparam
isnull
, 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
- anIIOMetadata
object representing stream metadata, ornull
to use default values.image
- anIIOImage
object containing an image, thumbnails, and metadata to be written.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifimage
contains aRaster
andcanWriteRasters
returnsfalse
.IllegalArgumentException
- ifimage
isnull
.IOException
- if an error occurs during writing.
-
write
Appends a complete image stream containing a single image with default metadata and thumbnails to the output. This method is a shorthand forwrite(null, image, null)
.- Parameters:
image
- anIIOImage
object containing an image, thumbnails, and metadata to be written.- Throws:
IllegalStateException
- if the output has not been set.IllegalArgumentException
- ifimage
isnull
.UnsupportedOperationException
- ifimage
contains aRaster
andcanWriteRasters
returnsfalse
.IOException
- if an error occurs during writing.
-
write
Appends a complete image stream consisting of a single image with default metadata and thumbnails to the output. This method is a shorthand forwrite(null, new IIOImage(image, null, null), null)
.- Parameters:
image
- aRenderedImage
to be written.- Throws:
IllegalStateException
- if the output has not been set.IllegalArgumentException
- ifimage
isnull
.IOException
- if an error occurs during writing.
-
canWriteSequence
public boolean canWriteSequence()Returnstrue
if the writer is able to append an image to an image stream that already contains header information and possibly prior images.If
canWriteSequence
returnsfalse
,writeToSequence
andendWriteSequence
will throw anUnsupportedOperationException
.The default implementation returns
false
.- Returns:
true
if images may be appended sequentially.
-
prepareWriteSequence
Prepares a stream to accept a series of subsequentwriteToSequence
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 isnull
, 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 thatendWriteSequence
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
returnsfalse
, this method will throw anUnsupportedOperationException
.The output must have been set beforehand using either the
setOutput
method.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
streamMetadata
- A stream metadata object, ornull
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanWriteSequence
returnsfalse
.IOException
- if an error occurs writing the stream metadata.
-
writeToSequence
Appends a single image and possibly associated metadata and thumbnails, to the output. If the output is anImageOutputStream
, 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 whenendWriteSequence
is called (e.g. TIFF).If
canWriteSequence
returnsfalse
, this method will throw anUnsupportedOperationException
.The output must have been set beforehand using the
setOutput
method.prepareWriteSequence
must have been called beforehand, or anIllegalStateException
is thrown.If
canWriteRasters
returnstrue
, theIIOImage
may contain aRaster
source. Otherwise, it must contain aRenderedImage
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. Ifparam
isnull
, 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 isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
image
- anIIOImage
object containing an image, thumbnails, and metadata to be written.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set, orprepareWriteSequence
has not been called.UnsupportedOperationException
- ifcanWriteSequence
returnsfalse
.IllegalArgumentException
- ifimage
isnull
.UnsupportedOperationException
- ifimage
contains aRaster
andcanWriteRasters
returnsfalse
.IOException
- if an error occurs during writing.
-
endWriteSequence
Completes the writing of a sequence of images begun withprepareWriteSequence
. 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 anImageOutputStream
, data through the stream metadata at the end of the sequence are flushed and need not be readable or writable.If
canWriteSequence
returnsfalse
, this method will throw anUnsupportedOperationException
.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Throws:
IllegalStateException
- if the output has not been set, orprepareWriteSequence
has not been called.UnsupportedOperationException
- ifcanWriteSequence
returnsfalse
.IOException
- if an error occurs during writing.
-
canReplaceStreamMetadata
Returnstrue
if it is possible to replace the stream metadata already present in the output.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise returnsfalse
.- 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
Replaces the stream metadata in the output with new information. If the output is anImageOutputStream
, 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
returnsfalse
, anUnsupportedOperationException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
streamMetadata
- anIIOMetadata
object representing stream metadata, ornull
to use default values.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- if thecanReplaceStreamMetadata
returnsfalse
. modes do not includeIOException
- if an error occurs during writing.
-
canReplaceImageMetadata
Returnstrue
if it is possible to replace the image metadata associated with an existing image with indeximageIndex
. If this method returnsfalse
, a call toreplaceImageMetadata(imageIndex)
will throw anUnsupportedOperationException
.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 isnull
, and otherwise returnsfalse
without checking the value ofimageIndex
.- 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, butimageIndex
is less than 0 or greater than the largest available index.IOException
- if an I/O error occurs during the query.
-
replaceImageMetadata
Replaces the image metadata associated with an existing image.If
canReplaceImageMetadata(imageIndex)
returnsfalse
, anUnsupportedOperationException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
imageIndex
- the index of the image whose metadata is to be replaced.imageMetadata
- anIIOMetadata
object representing image metadata, ornull
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanReplaceImageMetadata
returnsfalse
.IndexOutOfBoundsException
- ifimageIndex
is less than 0 or greater than the largest available index.IOException
- if an error occurs during writing.
-
canInsertImage
Returnstrue
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 forimageIndex
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 isnull
, and otherwise returnsfalse
without checking the value ofimageIndex
.- 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, butimageIndex
is less than -1 or greater than the largest available index.IOException
- if an I/O error occurs during the query.
-
writeInsert
Inserts a new image into an existing image stream. Existing images with an index greater thanimageIndex
are preserved, and their indices are each increased by 1. A value forimageIndex
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 anImageOutputStream
, the entirety of the stream must be both readable and writeable.If
canInsertImage(imageIndex)
returnsfalse
, anUnsupportedOperationException
will be thrown.An
ImageWriteParam
may optionally be supplied to control the writing process. Ifparam
isnull
, 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 isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
imageIndex
- the index at which to write the image.image
- anIIOImage
object containing an image, thumbnails, and metadata to be written.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanInsertImage(imageIndex)
returnsfalse
.IllegalArgumentException
- ifimage
isnull
.IndexOutOfBoundsException
- ifimageIndex
is less than -1 or greater than the largest available index.UnsupportedOperationException
- ifimage
contains aRaster
andcanWriteRasters
returnsfalse
.IOException
- if an error occurs during writing.
-
canRemoveImage
Returnstrue
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 isnull
, and otherwise returnsfalse
without checking the value ofimageIndex
.- 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, butimageIndex
is less than 0 or greater than the largest available index.IOException
- if an I/O error occurs during the query.
-
removeImage
Removes an image from the stream.If
canRemoveImage(imageIndex)
returns false, anUnsupportedOperationException
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 isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
imageIndex
- the index of the image to be removed.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanRemoveImage(imageIndex)
returnsfalse
.IndexOutOfBoundsException
- ifimageIndex
is less than 0 or greater than the largest available index.IOException
- if an I/O error occurs during the removal.
-
canWriteEmpty
Returnstrue
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 thereplacePixels
methods. If the output is anImageOutputStream
, 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 isnull
, and otherwise returnsfalse
.- 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 thereplacePixels
methods. If the output is anImageOutputStream
, 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 toprepareReplacePixels
,replacePixels
, andendReplacePixels
may occur between calls toprepareWriteEmpty
andendWriteEmpty
. However, calls toprepareWriteEmpty
cannot be nested, and calls toprepareWriteEmpty
andprepareInsertEmpty
may not be interspersed.If
canWriteEmpty
returnsfalse
, anUnsupportedOperationException
will be thrown.An
ImageWriteParam
may optionally be supplied to control the writing process. Ifparam
isnull
, 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 isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
streamMetadata
- anIIOMetadata
object representing stream metadata, ornull
to use default values.imageType
- anImageTypeSpecifier
describing the layout of the image.width
- the width of the image.height
- the height of the image.imageMetadata
- anIIOMetadata
object representing image metadata, ornull
.thumbnails
- aList
ofBufferedImage
thumbnails for this image, ornull
.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanWriteEmpty
returnsfalse
.IllegalStateException
- if a previous call toprepareWriteEmpty
has been made without a corresponding call toendWriteEmpty
.IllegalStateException
- if a previous call toprepareInsertEmpty
has been made without a corresponding call toendInsertEmpty
.IllegalArgumentException
- ifimageType
isnull
orthumbnails
containsnull
references or objects other thanBufferedImage
s.IllegalArgumentException
- if width or height are less than 1.IOException
- if an I/O error occurs during writing.
-
endWriteEmpty
Completes the writing of a new image that was begun with a prior call toprepareWriteEmpty
.If
canWriteEmpty()
returnsfalse
, anUnsupportedOperationException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanWriteEmpty(imageIndex)
returnsfalse
.IllegalStateException
- if a previous call toprepareWriteEmpty
without a corresponding call toendWriteEmpty
has not been made.IllegalStateException
- if a previous call toprepareInsertEmpty
without a corresponding call toendInsertEmpty
has been made.IllegalStateException
- if a call toprepareReiplacePixels
has been made without a matching call toendReplacePixels
.IOException
- if an I/O error occurs during writing.
-
canInsertEmpty
Returnstrue
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 thereplacePixels
methods. Existing images with indices greater than or equal to the insertion index will have their indices increased by 1. A value forimageIndex
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 isnull
, and otherwise returnsfalse
without checking the value ofimageIndex
.- 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, butimageIndex
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 thanimageIndex
are preserved, and their indices are each increased by 1. A value forimageIndex
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 anImageOutputStream
, 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 toendInsertEmpty
occurs. Calls toprepareReplacePixels
,replacePixels
, andendReplacePixels
may occur between calls toprepareInsertEmpty
andendInsertEmpty
. However, calls toprepareInsertEmpty
cannot be nested, and calls toprepareWriteEmpty
andprepareInsertEmpty
may not be interspersed.If
canInsertEmpty(imageIndex)
returnsfalse
, anUnsupportedOperationException
will be thrown.An
ImageWriteParam
may optionally be supplied to control the writing process. Ifparam
isnull
, 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 isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
imageIndex
- the index at which to write the image.imageType
- anImageTypeSpecifier
describing the layout of the image.width
- the width of the image.height
- the height of the image.imageMetadata
- anIIOMetadata
object representing image metadata, ornull
.thumbnails
- aList
ofBufferedImage
thumbnails for this image, ornull
.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanInsertEmpty(imageIndex)
returnsfalse
.IndexOutOfBoundsException
- ifimageIndex
is less than -1 or greater than the largest available index.IllegalStateException
- if a previous call toprepareInsertEmpty
has been made without a corresponding call toendInsertEmpty
.IllegalStateException
- if a previous call toprepareWriteEmpty
has been made without a corresponding call toendWriteEmpty
.IllegalArgumentException
- ifimageType
isnull
orthumbnails
containsnull
references or objects other thanBufferedImage
s.IllegalArgumentException
- if width or height are less than 1.IOException
- if an I/O error occurs during writing.
-
endInsertEmpty
Completes the insertion of a new image that was begun with a prior call toprepareInsertEmpty
.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanInsertEmpty(imageIndex)
returnsfalse
.IllegalStateException
- if a previous call toprepareInsertEmpty
without a corresponding call toendInsertEmpty
has not been made.IllegalStateException
- if a previous call toprepareWriteEmpty
without a corresponding call toendWriteEmpty
has been made.IllegalStateException
- if a call toprepareReplacePixels
has been made without a matching call toendReplacePixels
.IOException
- if an I/O error occurs during writing.
-
canReplacePixels
Returnstrue
if the writer allows pixels of the given image to be replaced using thereplacePixels
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 isnull
, and otherwise returnsfalse
without checking the value ofimageIndex
.- 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, butimageIndex
is less than 0 or greater than the largest available index.IOException
- if an I/O error occurs during the query.
-
prepareReplacePixels
Prepares the writer to handle a series of calls to thereplacePixels
methods. The affected pixel area will be clipped against the suppliedIf
canReplacePixels
returnsfalse
, andUnsupportedOperationException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
imageIndex
- the index of the image whose pixels are to be replaced.region
- aRectangle
that will be used to clip future pixel regions.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanReplacePixels(imageIndex)
returnsfalse
.IndexOutOfBoundsException
- ifimageIndex
is less than 0 or greater than the largest available index.IllegalStateException
- if there is a previous call toprepareReplacePixels
without a matching call toendReplacePixels
(i.e., nesting is not allowed).IllegalArgumentException
- ifregion
isnull
or has a width or height less than 1.IOException
- if an I/O error occurs during the preparation.
-
replacePixels
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 toprepareReplacePixels
. 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. Ifparam
isnull
, 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 anIllegalStateException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
image
- aRenderedImage
containing source pixels.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanReplacePixels(imageIndex)
returnsfalse
.IllegalStateException
- if there is no previous call toprepareReplacePixels
without a matching call toendReplacePixels
.IllegalArgumentException
- if any of the following are true:-
image
isnull
. - 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
Replaces a portion of an image already present in the output with a portion of the givenRaster
. 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. Ifparam
isnull
, 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 toprepareReplacePixels
. 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 anIllegalStateException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Parameters:
raster
- aRaster
containing source pixels.param
- anImageWriteParam
, ornull
to use a defaultImageWriteParam
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanReplacePixels(imageIndex)
returnsfalse
.IllegalStateException
- if there is no previous call toprepareReplacePixels
without a matching call toendReplacePixels
.UnsupportedOperationException
- ifcanWriteRasters
returnsfalse
.IllegalArgumentException
- if any of the following are true:-
raster
isnull
. - 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
Terminates a sequence of calls toreplacePixels
.If
canReplacePixels
returnsfalse
, andUnsupportedOperationException
will be thrown.The default implementation throws an
IllegalStateException
if the output isnull
, and otherwise throws anUnsupportedOperationException
.- Throws:
IllegalStateException
- if the output has not been set.UnsupportedOperationException
- ifcanReplacePixels(imageIndex)
returnsfalse
.IllegalStateException
- if there is no previous call toprepareReplacePixels
without a matching call toendReplacePixels
.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 ofabortRequested
regularly during the write. -
abortRequested
protected boolean abortRequested()Returnstrue
if a request to abort the current write operation has been made since the writer was instantiated orclearAbortRequest
was called.- Returns:
true
if the current write operation should be aborted.- See Also:
-
clearAbortRequest
protected void clearAbortRequest()Clears any previous abort request. After this method has been called,abortRequested
will returnfalse
.- See Also:
-
addIIOWriteWarningListener
Adds anIIOWriteWarningListener
to the list of registered warning listeners. Iflistener
isnull
, 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 currentLocale
. If noLocale
has been set, warning messages may be localized as the writer sees fit.- Parameters:
listener
- anIIOWriteWarningListener
to be registered.- See Also:
-
removeIIOWriteWarningListener
Removes anIIOWriteWarningListener
from the list of registered warning listeners. If the listener was not previously registered, or iflistener
isnull
, no exception will be thrown and no action will be taken.- Parameters:
listener
- anIIOWriteWarningListener
to be deregistered.- See Also:
-
removeAllIIOWriteWarningListeners
public void removeAllIIOWriteWarningListeners()Removes all currently registeredIIOWriteWarningListener
objects.The default implementation sets the
warningListeners
andwarningLocales
instance variables tonull
. -
addIIOWriteProgressListener
Adds anIIOWriteProgressListener
to the list of registered progress listeners. Iflistener
isnull
, no exception will be thrown and no action will be taken.- Parameters:
listener
- anIIOWriteProgressListener
to be registered.- See Also:
-
removeIIOWriteProgressListener
Removes anIIOWriteProgressListener
from the list of registered progress listeners. If the listener was not previously registered, or iflistener
isnull
, no exception will be thrown and no action will be taken.- Parameters:
listener
- anIIOWriteProgressListener
to be deregistered.- See Also:
-
removeAllIIOWriteProgressListeners
public void removeAllIIOWriteProgressListeners()Removes all currently registeredIIOWriteProgressListener
objects.The default implementation sets the
progressListeners
instance variable tonull
. -
processImageStarted
protected void processImageStarted(int imageIndex) Broadcasts the start of an image write to all registeredIIOWriteProgressListener
s by calling theirimageStarted
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 registeredIIOWriteProgressListener
s by calling theirimageProgress
method. Subclasses may use this method as a convenience.- Parameters:
percentageDone
- the current percentage of completion, as afloat
.
-
processImageComplete
protected void processImageComplete()Broadcasts the completion of an image write to all registeredIIOWriteProgressListener
s by calling theirimageComplete
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 registeredIIOWriteProgressListener
s by calling theirthumbnailStarted
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 registeredIIOWriteProgressListener
s by calling theirthumbnailProgress
method. Subclasses may use this method as a convenience.- Parameters:
percentageDone
- the current percentage of completion, as afloat
.
-
processThumbnailComplete
protected void processThumbnailComplete()Broadcasts the completion of a thumbnail write to all registeredIIOWriteProgressListener
s by calling theirthumbnailComplete
method. Subclasses may use this method as a convenience. -
processWriteAborted
protected void processWriteAborted()Broadcasts that the write has been aborted to all registeredIIOWriteProgressListener
s by calling theirwriteAborted
method. Subclasses may use this method as a convenience. -
processWarningOccurred
Broadcasts a warning message to all registeredIIOWriteWarningListener
s by calling theirwarningOccurred
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
- ifwarning
isnull
.
-
processWarningOccurred
Broadcasts a localized warning message to all registeredIIOWriteWarningListener
s by calling theirwarningOccurred
method with a string taken from aResourceBundle
. 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 ofResourceBundle
s containing localized warning messages.keyword
- the keyword used to index the warning message within the set ofResourceBundle
s.- Throws:
IllegalArgumentException
- ifbaseName
isnull
.IllegalArgumentException
- ifkeyword
isnull
.IllegalArgumentException
- if no appropriateResourceBundle
may be located.IllegalArgumentException
- if the named resource is not found in the locatedResourceBundle
.IllegalArgumentException
- if the object retrieved from theResourceBundle
is not aString
.
-
reset
public void reset()Restores theImageWriter
to its initial state.The default implementation calls
setOutput(null)
,setLocale(null)
,removeAllIIOWriteWarningListeners()
,removeAllIIOWriteProgressListeners()
, andclearAbortRequest
. -
dispose
public void dispose()Allows any resources held by this object to be released. The result of calling any other method (other thanfinalize
) 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.
-