Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

javax.imageio
Class ImageWriter

java.lang.Object
  javax.imageio.ImageWriter

public abstract class ImageWriter

extends java.lang.Object

An abstract superclass for encoding and writing images.

See Also:

ImageReader, ImageWriteParam

Field Summary

protected java.util.Locale[]	availableLocales An array of Locales that may be used to localize warning messages and compression setting values, or null if localization is not supported.
protected java.util.Locale	locale The current Locale to be used for localization, or null if none has been set.
protected java.lang.Object	output The ImageOutputStream or other Object set by setOutput and retrieved by getOutput.
protected java.util.List	progressListeners A List of currently registered IIOWriteProgressListeners, initialized by default null, which is synonymous with an empty List.
protected java.util.List	warningListeners A List of currently registered IIOWriteWarningListeners, initialized by default to null, which is synonymous with an empty List.
protected java.util.List	warningLocales A List of Locales, one for each element of warningListeners, initialized by default null, which is synonymous with an empty List.

Method Summary

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(IIOWriteProgressListener listener) Adds an IIOWriteProgressListener to the list of registered progress listeners.
void	addIIOWriteWarningListener(IIOWriteWarningListener listener) Adds an IIOWriteWarningListener to the list of registered warning listeners.
boolean	canInsertEmpty(int imageIndex) Returns true if the writer supports the insertion of a new, empty image at the given index.
boolean	canInsertImage(int imageIndex) Returns true if the writer supports the insertion of a new image at the given index.
boolean	canRemoveImage(int imageIndex) Returns true if the writer supports the removal of an existing image at the given index.
boolean	canReplacePixels(int imageIndex) Returns true if the writer allows pixels of the given image to be replaced using the replacePixels methods.
protected void	clearAbortRequest() Clears any previous abort request.
void	dispose() Allows any resources held by this object to be released.
void	endReplacePixels() Terminates a sequence of calls to replacePixels.
java.util.Locale[]	getAvailableLocales() Returns an array of Locales that may be used to localize warning listeners and compression settings.
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.
java.util.Locale	getLocale() Returns the currently set Locale, or null if none has been set.
java.lang.Object	getOutput() Returns the ImageOutputStream or other Object set by the most recent call to the setOutput method.
void	prepareReplacePixels(int imageIndex, Rectangle region) Prepares the writer to handle a series of calls to the replacePixels methods.
protected void	processImageComplete() Broadcasts the completion of an image write to all registered IIOWriteProgressListeners by calling their imageComplete method.
protected void	processImageProgress(float percentageDone) Broadcasts the current percentage of image completion to all registered IIOWriteProgressListeners by calling their imageProgress method.
protected void	processImageStarted(int imageIndex) Broadcasts the start of an image write to all registered IIOWriteProgressListeners by calling their imageStarted method.
protected void	processWarningOccurred(int imageIndex, java.lang.String warning) Broadcasts a warning message to all registered IIOWriteWarningListeners by calling their warningOccurred method.
protected void	processWarningOccurred(int imageIndex, java.lang.String baseName, java.lang.String keyword) Broadcasts a localized warning message to all registered IIOWriteWarningListeners 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 IIOWriteProgressListeners by calling their writeAborted method.
void	removeAllIIOWriteProgressListeners() Removes all currently registered IIOWriteProgressListener objects.
void	removeAllIIOWriteWarningListeners() Removes all currently registered IIOWriteWarningListener objects.
void	removeIIOWriteProgressListener(IIOWriteProgressListener listener) Removes an IIOWriteProgressListener from the list of registered progress listeners.
void	removeIIOWriteWarningListener(IIOWriteWarningListener listener) Removes an IIOWriteWarningListener from the list of registered warning listeners.
void	removeImage(int imageIndex) Removes an image from the stream.
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	reset() Restores the ImageWriter to its initial state.
void	setLocale(java.util.Locale locale) Sets the current Locale of this ImageWriter to the given value.
void	setOutput(java.lang.Object output) Sets the destination to the given ImageOutputStream or other Object.
abstract void	write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) Appends a complete image stream containing a single image and associated stream to the output.
void	write(RenderedImage image) Appends a complete image stream consisting of a single image to the output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

output

protected java.lang.Object output

The ImageOutputStream or other Object set by setOutput and retrieved by getOutput. By default it is initialized to null.

availableLocales

protected java.util.Locale[] availableLocales

An array of Locales 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.

locale

protected java.util.Locale locale

The current Locale to be used for localization, or null if none has been set. By default it is initialized to null.

warningListeners

protected java.util.List warningListeners

A List of currently registered IIOWriteWarningListeners, initialized by default to null, which is synonymous with an empty List.

warningLocales

protected java.util.List warningLocales

A List of Locales, one for each element of warningListeners, initialized by default null, which is synonymous with an empty List.

progressListeners

protected java.util.List progressListeners

A List of currently registered IIOWriteProgressListeners, initialized by default null, which is synonymous with an empty List.

Method Detail

setOutput

public void setOutput(java.lang.Object output)

Sets the destination to the given ImageOutputStream or other Object. The destination is assumed to be ready to accept data, and will not be closed at the end of each write. This allows distributed imaging applications to transmit a series of images over a single network connection. If output is null, any currently set output will be removed.

If output is an ImageOutputStream, calls to the write, writeToSequence, and prepareWriteEmpty/endWriteEmpty methods will preserve the existing contents of the stream. Other write methods, such as writeInsert, 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. Most writers will return a single-element array containing only ImageOutputStream.class to indicate that they accept only an ImageOutputStream.

Parameters:

output - the ImageOutputStream or other Object to use for future writing.

See Also:

getOutput()

getOutput

public java.lang.Object getOutput()

Returns the ImageOutputStream or other Object set by the most recent call to the setOutput method. If no destination has been set, null is returned.

The default implementation returns the value of the output instance variable.

Returns:

the Object that was specified using setOutput, or null.

See Also:

setOutput(java.lang.Object)

getAvailableLocales

public java.util.Locale[] getAvailableLocales()

Returns an array of Locales that may be used to localize warning listeners and compression settings. A return value of null indicates that localization is not supported.

The default implementation returns a clone of the availableLocales instance variable if it is non-null, or else returns null.

Returns:

an array of Locales that may be used as arguments to setLocale, or null.

setLocale

public void setLocale(java.util.Locale locale)

Sets the current Locale of this ImageWriter to the given value. A value of null removes any previous setting, and indicates that the writer should localize as it sees fit.

The default implementation checks locale against the values returned by getAvailableLocales, and sets the locale instance variable if it is found. If locale is null, the instance variable is set to null without any checking.

Parameters:

locale - the desired Locale, or null.

Throws:

java.lang.IllegalArgumentException - if locale is non-null but is not one of the values returned by getAvailableLocales.

See Also:

getLocale()

getLocale

public java.util.Locale getLocale()

Returns the currently set Locale, or null if none has been set.

The default implementation returns the value of the locale instance variable.

Returns:

the current Locale, or null.

See Also:

setLocale(java.util.Locale)

getDefaultWriteParam

public ImageWriteParam getDefaultWriteParam()

Returns a new ImageWriteParam object of the appropriate type for this file format containing default values, that is, those values that would be used if no ImageWriteParam object were specified. This is useful as a starting point for tweaking just a few parameters and otherwise leaving the default settings alone.

The default implementation constructs and returns a new ImageWriteParam object that does not allow progressive encoding, or compression, and that will be localized for the current Locale (i.e., what you would get by calling new ImageWriteParam(getLocale()).

Returns:

a new ImageWriteParam object containing default values.

write

public abstract void write(IIOMetadata streamMetadata,
                           IIOImage image,
                           ImageWriteParam param)
                    throws java.io.IOException

Appends a complete image stream containing a single image and associated stream to the output. Any necessary header information is included. If the output is an ImageOutputStream, its existing contents prior to the current seek position are not affected, and need not be readable or writable.

The output must have been set beforehand using the setOutput method.

streamMetadata must be null, any value other than null, will throw an IllegalArgumentException.

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, they will be ignored.

Parameters:

streamMetadata - must be null. Any value other than null will throw an IllegalArgumentException.

image - an IIOImage object

param - an ImageWriteParam, or null to use a default ImageWriteParam.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IllegalArgumentException - if IIOmetadata is not null

java.io.IOException - if an error occurs during writing.

write

public void write(RenderedImage image)
           throws java.io.IOException

Appends a complete image stream consisting of a single image to the output. This method is a shorthand for write(null, new IIOImage(image, null, null), null).

Parameters:

image - a RenderedImage to be written.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IllegalArgumentException - if image is null or not a BufferedImage. See restriction on RenderedImage.

java.io.IOException - if an error occurs during writing.

canInsertImage

public boolean canInsertImage(int imageIndex)
                       throws java.io.IOException

Returns true if the writer supports the insertion of a new image at the given index. Existing images with indices greater than or equal to the insertion index will have their indices increased by 1. A value for imageIndex of -1 may be used to signify an index one larger than the current largest index.

A writer that does not support any image insertion may return false without performing bounds checking on the index.

The default implementation throws an IllegalStateException if the output is null, and otherwise returns false withour checking the value of imageIndex.

Parameters:

imageIndex - the index at which the image is to be inserted.

Returns:

true if an image may be inserted at the given index.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IndexOutOfBoundsException - if the writer supports image insertion in general, but imageIndex is less than -1 or greater than the largest available index.

java.io.IOException - if an I/O error occurs during the query.

canRemoveImage

public boolean canRemoveImage(int imageIndex)
                       throws java.io.IOException

Returns true if the writer supports the removal of an existing image at the given index. Existing images with indices greater than the insertion index will have their indices decreased by 1.

A writer that does not support any image removal may return false without performing bounds checking on the index.

The default implementation throws an IllegalStateException if the output is null, and otherwise returns false without checking the value of imageIndex.

Parameters:

imageIndex - the index of the image to be removed.

Returns:

true if it is possible to remove the given image.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IndexOutOfBoundsException - if the writer supports image removal in general, but imageIndex is less than 0 or greater than the largest available index.

java.io.IOException - if an I/O error occurs during the query.

removeImage

public void removeImage(int imageIndex)
                 throws java.io.IOException

Removes an image from the stream.

If canRemoveImage(imageIndex) returns false, an UnsupportedOperationExceptionwill be thrown.

The removal may or may not cause a reduction in the actual file size.

The default implementation throws an IllegalStateException if the output is null, and otherwise throws an UnsupportedOperationException.

Parameters:

imageIndex - the index of the image to be removed.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.UnsupportedOperationException - if canRemoveImage(imageIndex) returns false.

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the largest available index.

java.io.IOException - if an I/O error occurs during the removal.

canInsertEmpty

public boolean canInsertEmpty(int imageIndex)
                       throws java.io.IOException

Returns true if the writer supports the insertion of a new, empty image at the given index. The pixel values of the image are undefined, and may be specified in pieces using the replacePixels methods. Existing images with indices greater than or equal to the insertion index will have their indices increased by 1. A value for imageIndex of -1 may be used to signify an index one larger than the current largest index.

A writer that does not support insertion of empty images may return false without performing bounds checking on the index.

The default implementation throws an IllegalStateException if the output is null, and otherwise returns false without checking the value of imageIndex.

Parameters:

imageIndex - the index at which the image is to be inserted.

Returns:

true if an empty image may be inserted at the given index.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IndexOutOfBoundsException - if the writer supports empty image insertion in general, but imageIndex is less than -1 or greater than the largest available index.

java.io.IOException - if an I/O error occurs during the query.

canReplacePixels

public boolean canReplacePixels(int imageIndex)
                         throws java.io.IOException

Returns true if the writer allows pixels of the given image to be replaced using the replacePixels methods.

A writer that does not support any pixel replacement may return false without performing bounds checking on the index.

The default implementation throws an IllegalStateException if the output is null, and otherwise returns false without checking the value of imageIndex.

Parameters:

imageIndex - the index of the image whose pixels are to be replaced.

Returns:

true if the pixels of the given image can be replaced.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.IndexOutOfBoundsException - if the writer supports pixel replacement in general, but imageIndex is less than 0 or greater than the largest available index.

java.io.IOException - if an I/O error occurs during the query.

prepareReplacePixels

public void prepareReplacePixels(int imageIndex,
                                 Rectangle region)
                          throws java.io.IOException

Prepares the writer to handle a series of calls to the replacePixels methods. The affected pixel area will be clipped against the supplied

If canReplacePixels returns false, and UnsupportedOperationException will be thrown.

The default implementation throws an IllegalStateException if the output is null, and otherwise throws an UnsupportedOperationException.

Parameters:

imageIndex - the index of the image whose pixels are to be replaced.

region - a Rectangle that will be used to clip future pixel regions.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.UnsupportedOperationException - if canReplacePixels(imageIndex) returns false.

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the largest available index.

java.lang.IllegalStateException - if there is a previous call to prepareReplacePixels without a matching call to endReplacePixels (i.e., nesting is not allowed).

java.lang.IllegalArgumentException - if region is null or has a width or height less than 1.

java.io.IOException - if an I/O error occurs during the preparation.

replacePixels

public void replacePixels(RenderedImage image,
                          ImageWriteParam param)
                   throws java.io.IOException

Replaces a portion of an image already present in the output with a portion of the given image. The image data must match, or be convertible to, the image layout of the existing image.

The destination region is specified in the param argument, and will be clipped to the image boundaries and the region supplied to prepareReplacePixels. At least one pixel of the source must not be clipped, or an exception is thrown.

An ImageWriteParam may optionally be supplied to control the writing process. If param is null, a default write param will be used.

If the supplied ImageWriteParam contains optional setting values not supported by this writer, they will be ignored.

This method may only be called after a call to prepareReplacePixels, or else an IllegalStateException will be thrown.

The default implementation throws an IllegalStateException if the output is null, and otherwise throws an UnsupportedOperationException.

Parameters:

image - a RenderedImage containing source pixels.

param - an ImageWriteParam, or null to use a default ImageWriteParam.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.UnsupportedOperationException - if canReplacePixels(imageIndex) returns false.

java.lang.IllegalStateException - if there is no previous call to prepareReplacePixels without a matching call to endReplacePixels.

java.lang.IllegalArgumentException - if any of the following are true:

image is null or not a BufferedImage. See restriction on RenderedImage.

param is null.

the intersected region does not contain at least one pixel.

the layout of image does not match, or this writer cannot convert it to, the existing image layout.

java.io.IOException - if an I/O error occurs during writing.

endReplacePixels

public void endReplacePixels()
                      throws java.io.IOException

Terminates a sequence of calls to replacePixels.

If canReplacePixels returns false, and UnsupportedOperationException will be thrown.

The default implementation throws an IllegalStateException if the output is null, and otherwise throws an UnsupportedOperationException.

Throws:

java.lang.IllegalStateException - if the output has not been set.

java.lang.UnsupportedOperationException - if canReplacePixels(imageIndex) returns false.

java.lang.IllegalStateException - if there is no previous call to prepareReplacePixels without a matching call to endReplacePixels.

java.io.IOException - if an I/O error occurs during writing.

abort

public void abort()

Requests that any current write operation be aborted. The contents of the output following the abort will be undefined.

Writers should call clearAbortRequest at the beginning of each write operation, and poll the value of abortRequested regularly during the write.

abortRequested

protected boolean abortRequested()

Returns true if a request to abort the current write operation has been made since the writer was instantiated or clearAbortRequest was called.

Returns:

true if the current write operation should be aborted.

See Also:

abort(), clearAbortRequest()

clearAbortRequest

protected void clearAbortRequest()

Clears any previous abort request. After this method has been called, abortRequested will return false.

See Also:

abort(), abortRequested()

addIIOWriteWarningListener

public void addIIOWriteWarningListener(IIOWriteWarningListener listener)

Adds an IIOWriteWarningListener to the list of registered warning listeners. If listener is null, no exception will be thrown and no action will be taken. Messages sent to the given listener will be localized, if possible, to match the current Locale. If no Locale has been set, warning messages may be localized as the writer sees fit.

Parameters:

listener - an IIOWriteWarningListener to be registered.

See Also:

removeIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener)

removeIIOWriteWarningListener

public void removeIIOWriteWarningListener(IIOWriteWarningListener listener)

Removes an IIOWriteWarningListener from the list of registered warning listeners. If the listener was not previously registered, or if listener is null, no exception will be thrown and no action will be taken.

Parameters:

listener - an IIOWriteWarningListener to be deregistered.

See Also:

addIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener)

removeAllIIOWriteWarningListeners

public void removeAllIIOWriteWarningListeners()

Removes all currently registered IIOWriteWarningListener objects.

The default implementation sets the warningListeners and warningLocales instance variables to null.

addIIOWriteProgressListener

public void addIIOWriteProgressListener(IIOWriteProgressListener listener)

Adds an IIOWriteProgressListener to the list of registered progress listeners. If listener is null, no exception will be thrown and no action will be taken.

Parameters:

listener - an IIOWriteProgressListener to be registered.

See Also:

removeIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener)

removeIIOWriteProgressListener

public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)

Removes an IIOWriteProgressListener from the list of registered progress listeners. If the listener was not previously registered, or if listener is null, no exception will be thrown and no action will be taken.

Parameters:

listener - an IIOWriteProgressListener to be deregistered.

See Also:

addIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener)

removeAllIIOWriteProgressListeners

public void removeAllIIOWriteProgressListeners()

Removes all currently registered IIOWriteProgressListener objects.

The default implementation sets the progressListeners instance variable to null.

processImageStarted

protected void processImageStarted(int imageIndex)

Broadcasts the start of an image write to all registered IIOWriteProgressListeners by calling their imageStarted method. Subclasses may use this method as a convenience.

Parameters:

imageIndex - the index of the image about to be written.

processImageProgress

protected void processImageProgress(float percentageDone)

Broadcasts the current percentage of image completion to all registered IIOWriteProgressListeners by calling their imageProgress method. Subclasses may use this method as a convenience.

Parameters:

percentageDone - the current percentage of completion, as a float.

processImageComplete

protected void processImageComplete()

Broadcasts the completion of an image write to all registered IIOWriteProgressListeners by calling their imageComplete method. Subclasses may use this method as a convenience.

processWriteAborted

protected void processWriteAborted()

Broadcasts that the write has been aborted to all registered IIOWriteProgressListeners by calling their writeAborted method. Subclasses may use this method as a convenience.

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                                      java.lang.String warning)

Broadcasts a warning message to all registered IIOWriteWarningListeners by calling their warningOccurred method. Subclasses may use this method as a convenience.

Parameters:

imageIndex - the index of the image on which the warning occurred.

warning - the warning message.

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                                      java.lang.String baseName,
                                      java.lang.String keyword)

Broadcasts a localized warning message to all registered IIOWriteWarningListeners by calling their warningOccurred method with a string taken from a ResourceBundle. Subclasses may use this method as a convenience.

Parameters:

imageIndex - the index of the image on which the warning occurred.

baseName - the base name of a set of ResourceBundles containing localized warning messages.

keyword - the keyword used to index the warning message within the set of ResourceBundles.

reset

public void reset()

Restores the ImageWriter to its initial state.

The default implementation calls setOutput(null), setLocale(null), removeAllIIOWriteWarningListeners(), removeAllIIOWriteProgressListeners(), and clearAbortRequest.

dispose

public void dispose()

Allows any resources held by this object to be released. The result of calling any other method (other than finalize) subsequent to a call to this method is undefined.

It is important for applications to call this method when they know they will no longer be using this ImageWriter. Otherwise, the writer may continue to hold on to resources indefinitely.

The default implementation of this method in the superclass does nothing. Subclass implementations should ensure that all resources, especially native resources, are released.