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 ImageReader

java.lang.Object
  javax.imageio.ImageReader

public abstract class ImageReader

extends java.lang.Object

An abstract superclass for parsing and decoding of images. This class must be subclassed by classes that read in images in the context of the Java Image I/O framework.

When an input source is set (using the setInput method), it may be marked as "seek forward only". This setting means that images contained within the input source will only be read in order, possibly allowing the reader to avoid caching portions of the input containing data associated with images that have been read previously.

See Also:

ImageWriter

Field Summary

protected java.util.Locale[]	availableLocales An array of Locales which may be used to localize warning messages, or null if localization is not supported.
protected java.lang.Object	input The ImageInputStream or other Object by setInput and retrieved by getInput.
protected java.util.Locale	locale The current Locale to be used for localization, or null if none has been set.
protected int	minIndex The smallest valid index for reading, initially 0.
protected java.util.List	progressListeners A List of currently registered IIOReadProgressListeners, initialized by default to null, which is synonymous with an empty List.
protected boolean	seekForwardOnly true if the current input source has been marked as allowing only forward seeking by setInput.
protected java.util.List	updateListeners A List of currently registered IIOReadUpdateListeners, initialized by default to null, which is synonymous with an empty List.
protected java.util.List	warningListeners A List of currently registered IIOReadWarningListeners, initialized by default to null, which is synonymous with an empty List.
protected java.util.List	warningLocales A List of the Locales associated with each currently registered IIOReadWarningListener, initialized by default to null, which is synonymous with an empty List.

Method Summary

void	abort() Requests that any current read operation be aborted.
protected boolean	abortRequested() Returns true if a request to abort the current read operation has been made since the reader was instantiated or clearAbortRequest was called.
void	addIIOReadProgressListener(IIOReadProgressListener listener) Adds an IIOReadProgressListener to the list of registered progress listeners.
void	addIIOReadUpdateListener(IIOReadUpdateListener listener) Adds an IIOReadUpdateListener to the list of registered update listeners.
void	addIIOReadWarningListener(IIOReadWarningListener listener) Adds an IIOReadWarningListener to the list of registered warning listeners.
protected static void	checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands) A utility method that may be used by readers to test the validity of the source and destination band settings of an ImageReadParam.
protected void	clearAbortRequest() Clears any previous abort request.
protected static void	computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion) Computes the source region of interest and the destination region of interest, taking the width and height of the source image, an optional destination image, and an optional ImageReadParam into account.
void	dispose() Allows any resources held by this object to be released.
float	getAspectRatio(int imageIndex) Returns the aspect ratio of the given image (that is, its width divided by its height) as a float.
java.util.Locale[]	getAvailableLocales() Returns an array of Locales that may be used to localize warning listeners and compression settings.
ImageReadParam	getDefaultReadParam() Returns a default ImageReadParam object appropriate for this format.
protected static BufferedImage	getDestination(ImageReadParam param, java.util.Iterator imageTypes, int width, int height) Returns the BufferedImage to which decoded pixel data should be written.
java.lang.String	getFormatName() Returns a String identifying the format of the input source.
abstract int	getHeight(int imageIndex) Returns the height in pixels of the given image within the input source.
abstract java.util.Iterator	getImageTypes(int imageIndex) Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss.
java.lang.Object	getInput() Returns the ImageInputStream or other Object previously set as the input source.
java.util.Locale	getLocale() Returns the currently set Locale, or null if none has been set.
int	getMinIndex() Returns the lowest valid index for reading an image.
abstract int	getNumImages(boolean allowSearch) Returns the number of images, available from the current input source.
ImageTypeSpecifier	getRawImageType(int imageIndex) Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image.
protected static Rectangle	getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight) A utility method that may be used by readers to compute the region of the source image that should be read, taking into account any source region and subsampling offset settings in the supplied ImageReadParam.
abstract int	getWidth(int imageIndex) Returns the width in pixels of the given image within the input source.
boolean	isRandomAccessEasy(int imageIndex) Returns true if the storage format of the given image places no inherent impediment on random access to pixels.
boolean	isSeekForwardOnly() Returns true if the current input source has been marked as seek forward only by passing true as the seekForwardOnly argument to the setInput method.
protected void	processImageComplete() Broadcasts the completion of an image read to all registered IIOReadProgressListeners by calling their imageComplete method.
protected void	processImageProgress(float percentageDone) Broadcasts the current percentage of image completion to all registered IIOReadProgressListeners by calling their imageProgress method.
protected void	processImageStarted(int imageIndex) Broadcasts the start of an image read to all registered IIOReadProgressListeners by calling their imageStarted method.
protected void	processImageUpdate(BufferedImage theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) Broadcasts the update of a set of samples to all registered IIOReadUpdateListeners by calling their imageUpdate method.
protected void	processPassComplete(BufferedImage theImage) Broadcasts the end of a progressive pass to all registered IIOReadUpdateListeners by calling their passComplete method.
protected void	processPassStarted(BufferedImage theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) Broadcasts the beginning of a progressive pass to all registered IIOReadUpdateListeners by calling their passStarted method.
protected void	processReadAborted() Broadcasts that the read has been aborted to all registered IIOReadProgressListeners by calling their readAborted method.
protected void	processSequenceComplete() Broadcasts the completion of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceComplete method.
protected void	processSequenceStarted(int minIndex) Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceStarted method.
protected void	processWarningOccurred(java.lang.String warning) Broadcasts a warning message to all registered IIOReadWarningListeners by calling their warningOccurred method.
protected void	processWarningOccurred(java.lang.String baseName, java.lang.String keyword) Broadcasts a localized warning message to all registered IIOReadWarningListeners by calling their warningOccurred method with a string taken from a ResourceBundle.
BufferedImage	read(int imageIndex) Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a default ImageReadParam.
abstract BufferedImage	read(int imageIndex, ImageReadParam param) Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a supplied ImageReadParam.
java.util.Iterator	readAll(java.util.Iterator params) Returns an Iterator containing all the images, starting at the index given by getMinIndex, from the input source in the form of IIOImage objects.
RenderedImage	readAsRenderedImage(int imageIndex, ImageReadParam param) Returns a RenderedImage object that contains the contents of the image indexed by imageIndex.
void	removeAllIIOReadProgressListeners() Removes all currently registered IIOReadProgressListener objects.
void	removeAllIIOReadUpdateListeners() Removes all currently registered IIOReadUpdateListener objects.
void	removeAllIIOReadWarningListeners() Removes all currently registered IIOReadWarningListener objects.
void	removeIIOReadProgressListener(IIOReadProgressListener listener) Removes an IIOReadProgressListener from the list of registered progress listeners.
void	removeIIOReadUpdateListener(IIOReadUpdateListener listener) Removes an IIOReadUpdateListener from the list of registered update listeners.
void	removeIIOReadWarningListener(IIOReadWarningListener listener) Removes an IIOReadWarningListener from the list of registered error listeners.
void	reset() Restores the ImageReader to its initial state.
void	setInput(java.lang.Object input) Sets the input source to use to the given ImageInputStream or other Object.
void	setInput(java.lang.Object input, boolean seekForwardOnly) Sets the input source to use to the given ImageInputStream or other Object.
void	setLocale(java.util.Locale locale) Sets the current Locale of this ImageReader to the given value.

Methods inherited from class java.lang.Object

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

Field Detail

input

protected java.lang.Object input

The ImageInputStream or other Object by setInput and retrieved by getInput. By default it is initialized to null.

seekForwardOnly

protected boolean seekForwardOnly

true if the current input source has been marked as allowing only forward seeking by setInput. By default, the value is false.

See Also:

minIndex, setInput(java.lang.Object, boolean)

minIndex

protected int minIndex

The smallest valid index for reading, initially 0. When seekForwardOnly is true, various methods may throw an IndexOutOfBoundsException on an attempt to access data associate with an image having a lower index.

See Also:

seekForwardOnly, setInput(java.lang.Object, boolean)

availableLocales

protected java.util.Locale[] availableLocales

An array of Locales which may be used to localize warning messages, or null if localization is not supported.

locale

protected java.util.Locale locale

The current Locale to be used for localization, or null if none has been set.

warningListeners

protected java.util.List warningListeners

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

warningLocales

protected java.util.List warningLocales

A List of the Locales associated with each currently registered IIOReadWarningListener, initialized by default to null, which is synonymous with an empty List.

progressListeners

protected java.util.List progressListeners

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

updateListeners

protected java.util.List updateListeners

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

Method Detail

getFormatName

public java.lang.String getFormatName()
                               throws java.io.IOException

Returns a String identifying the format of the input source.

Returns:

the format name, as a String.

Throws:

java.io.IOException - if an error occurs reading the information from the input source.

setInput

public void setInput(java.lang.Object input,
                     boolean seekForwardOnly)

Sets the input source to use to the given ImageInputStream or other Object. The input source must be set before any of the query or read methods are used. If input is null, any currently set input source will be removed. In any case, the value of minIndex will be initialized to 0.

The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image is read. If seekForwardOnly is true, then a call to read(index) will throw an IndexOutOfBoundsException if index < this.minIndex; otherwise, the value of minIndex will be set to index. If seekForwardOnly is false, the value of minIndex will remain 0 regardless of any read operations.

Parameters:

input - the ImageInputStream or other Object to use for future decoding.

seekForwardOnly - if true, images may only be read in ascending order from this input source.

Throws:

java.lang.IllegalArgumentException - if input is not an ImageInputStream.

See Also:

getInput()

setInput

public void setInput(java.lang.Object input)

Sets the input source to use to the given ImageInputStream or other Object. The input source must be set before any of the query or read methods are used. If input is null, any currently set input source will be removed. In any case, the value of minIndex will be initialized to 0.

Parameters:

input - the ImageInputStream or other Object to use for future decoding.

Throws:

java.lang.IllegalArgumentException - if input is not an ImageInputStream.

See Also:

getInput()

getInput

public java.lang.Object getInput()

Returns the ImageInputStream or other Object previously set as the input source. If the input source has not been set, null is returned.

Returns:

the Object that will be used for future decoding, or null.

See Also:

ImageInputStream, setInput(java.lang.Object, boolean)

isSeekForwardOnly

public boolean isSeekForwardOnly()

Returns true if the current input source has been marked as seek forward only by passing true as the seekForwardOnly argument to the setInput method.

Returns:

true if the input source is seek forward only.

See Also:

setInput(java.lang.Object, boolean)

getMinIndex

public int getMinIndex()

Returns the lowest valid index for reading an image. If seekForwardOnly() is false, this value will typically remain 0, indicating that random access is possible. Otherwise, it will contain the value of the most recently accessed index, and increase in a monotonic fashion.

Returns:

the minimum legal index for reading.

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 ImageReader to the given value. A value of null removes any previous setting, and indicates that the reader should localize as it sees fit.

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.

Returns:

the current Locale, or null.

See Also:

setLocale(java.util.Locale)

getNumImages

public abstract int getNumImages(boolean allowSearch)
                          throws java.io.IOException

Returns the number of images, available from the current input source.

Note that some image formats (such as animated GIF) do not specify how many images are present in the stream. Thus determining the number of images will require the entire stream to be scanned and may require memory for buffering. If images are to be processed in order, it may be more efficient to simply call read with increasing indices until an IndexOutOfBoundsException is thrown to indicate that no more images are available. The allowSearch parameter may be set to false to indicate that an exhaustive search is not desired; the return value will be -1 to indicate that a search is necessary. If the input has been specified with seekForwardOnly set to true, this method throws an IllegalStateException if allowSearch is set to true.

Parameters:

allowSearch - if true, the true number of images will be returned even if a search is required. If false, the reader may return -1 without performing the search.

Returns:

the number of images, as an int, or -1 if allowSearch is false and a search would be required.

Throws:

java.lang.IllegalStateException - if the input source has not been set, or if the input has been specified with seekForwardOnly set to true.

java.io.IOException - if an error occurs reading the information from the input source.

See Also:

setInput(java.lang.Object, boolean)

getWidth

public abstract int getWidth(int imageIndex)
                      throws java.io.IOException

Returns the width in pixels of the given image within the input source.

If the image can be rendered to a user-specified size, then this method returns the default width.

Parameters:

imageIndex - the index of the image to be queried.

Returns:

the width of the image, as an int.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.io.IOException - if an error occurs reading the width information from the input source.

getHeight

public abstract int getHeight(int imageIndex)
                       throws java.io.IOException

Returns the height in pixels of the given image within the input source.

If the image can be rendered to a user-specified size, then this method returns the default height.

Parameters:

imageIndex - the index of the image to be queried.

Returns:

the height of the image, as an int.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.io.IOException - if an error occurs reading the height information from the input source.

isRandomAccessEasy

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

Returns true if the storage format of the given image places no inherent impediment on random access to pixels. For most compressed formats, such as JPEG, this method should return false, as a large section of the image in addition to the region of interest may need to be decoded.

This is merely a hint for programs that wish to be efficient; all readers must be able to read arbitrary regions as specified in an ImageReadParam.

A reader for which all images are guaranteed to support easy random access, or are guaranteed not to support easy random access, may return true or false respectively without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.

The default implementation returns false.

Parameters:

imageIndex - the index of the image to be queried.

Returns:

true if reading a region of interest of the given image is likely to be efficient.

Throws:

java.lang.IllegalStateException - if an input source is required to determine the return value, but none has been set.

java.lang.IndexOutOfBoundsException - if an image must be accessed to determine the return value, but the supplied index is out of bounds.

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

getAspectRatio

public float getAspectRatio(int imageIndex)
                     throws java.io.IOException

Returns the aspect ratio of the given image (that is, its width divided by its height) as a float. For images that are inherently resizable, this method provides a way to determine the appropriate width given a deired height, or vice versa. For non-resizable images, the true width and height are used.

The default implementation simply returns (float)getWidth(imageIndex)/getHeight(imageIndex).

Parameters:

imageIndex - the index of the image to be queried.

Returns:

a float indicating the aspect ratio of the given image.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

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

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)
                                   throws java.io.IOException

Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image. For example, for a JPEG image the raw type might have a YCbCr color space even though the image would conventionally be transformed into an RGB color space prior to display. The returned value should also be included in the list of values returned by getImageTypes.

The default implementation simply returns the first entry from the list provided by getImageType.

Parameters:

imageIndex - the index of the image to be queried.

Returns:

an ImageTypeSpecifier.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.io.IOException - if an error occurs reading the format information from the input source.

getImageTypes

public abstract java.util.Iterator getImageTypes(int imageIndex)
                                          throws java.io.IOException

Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss. At least one legal image type will be returned.

The first element of the iterator should be the most "natural" type for decoding the image with as little loss as possible. For example, for a JPEG image the first entry should be an RGB image, even though the image data is stored internally in a YCbCr color space.

Parameters:

imageIndex - the index of the image to be retrieved.

Returns:

an Iterator containing at least one ImageTypeSpecifier representing suggested image types for decoding the current given image.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.io.IOException - if an error occurs reading the format information from the input source.

See Also:

ImageReadParam.setDestination(BufferedImage), ImageReadParam.setDestinationType(ImageTypeSpecifier)

getDefaultReadParam

public ImageReadParam getDefaultReadParam()

Returns a default ImageReadParam object appropriate for this format. All subclasses should define a set of default values for all parameters and return them with this call. This method may be called before the input source is set.

The default implementation constructs and returns a new ImageReadParam object that does not allow source scaling (i.e., it returns new ImageReadParam().

Returns:

an ImageReadParam object which may be used to control the decoding process using a set of default settings.

read

public BufferedImage read(int imageIndex)
                   throws java.io.IOException

Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a default ImageReadParam. This is a convenience method that calls read(imageIndex, null).

The image returned will be formatted according to the first ImageTypeSpecifier returned from getImageTypes.

Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.

Parameters:

imageIndex - the index of the image to be retrieved.

Returns:

the desired portion of the image as a BufferedImage.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

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

read

public abstract BufferedImage read(int imageIndex,
                                   ImageReadParam param)
                            throws java.io.IOException

Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a supplied ImageReadParam.

The actual BufferedImage returned will be chosen using the algorithm defined by the getDestination method.

Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.

The set of source bands to be read and destination bands to be written is determined by calling getSourceBands and getDestinationBands on the supplied ImageReadParam. If the lengths of the arrays returned by these methods differ, the set of source bands contains an index larger that the largest available source index, or the set of destination bands contains an index larger than the largest legal destination index, an IllegalArgumentException is thrown.

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

Parameters:

imageIndex - the index of the image to be retrieved.

param - an ImageReadParam used to control the reading process, or null.

Returns:

the desired portion of the image as a BufferedImage.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.lang.IllegalArgumentException - if the set of source and destination bands specified by param.getSourceBands and param.getDestinationBands differ in length or include indices that are out of bounds.

java.lang.IllegalArgumentException - if the resulting image would have a width or height less than 1.

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

readAll

public java.util.Iterator readAll(java.util.Iterator params)
                           throws java.io.IOException

Returns an Iterator containing all the images, starting at the index given by getMinIndex, from the input source in the form of IIOImage objects. An Iterator containing ImageReadParam objects is supplied; one element is consumed for each image read from the input source until no more images are available. If the read param Iterator runs out of elements, but there are still more images available from the input source, default read params are used for the remaining images.

If params is null, a default read param will be used for all images.

The actual BufferedImage referenced by the returned IIOImage will be chosen using the algorithm defined by the getDestination method.

Any registered IIOReadProgressListener objects will be notified by calling their sequenceStarted method once. Then, for each image decoded, there will be a call to imageStarted, followed by calls to imageProgress as the read progresses, and finally to imageComplete. The sequenceComplete method will be called after the last image has been decoded. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.

The set of source bands to be read and destination bands to be written is determined by calling getSourceBands and getDestinationBands on the supplied ImageReadParam. If the lengths of the arrays returned by these methods differ, the set of source bands contains an index larger that the largest available source index, or the set of destination bands contains an index larger than the largest legal destination index, an IllegalArgumentException is thrown.

If any of the supplied ImageReadParams contain optional setting values not supported by this reader, they will be ignored.

Parameters:

params - an Iterator containing ImageReadParam objects.

Returns:

an Iterator representing the contents of the input source as IIOImages.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IllegalArgumentException - if any non-null element of params is not an ImageReadParam.

java.lang.IllegalArgumentException - if the set of source and destination bands specified by param.getSourceBands and param.getDestinationBands differ in length or include indices that are out of bounds.

java.lang.IllegalArgumentException - if a resulting image would have a width or height less than 1.

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

See Also:

ImageReadParam, IIOImage

readAsRenderedImage

public RenderedImage readAsRenderedImage(int imageIndex,
                                         ImageReadParam param)
                                  throws java.io.IOException

Returns a RenderedImage object that contains the contents of the image indexed by imageIndex. By default, the returned image is simply the BufferedImage returned by read(imageIndex, param).

The semantics of this method may differ from those of the other read methods in several ways. First, any destination image and/or image type set in the ImageReadParam may be ignored. Second, the usual listener calls are not guaranteed to be made, or to be meaningful if they are. This is because the returned image may not be fully populated with pixel data at the time it is returned, or indeed at any time.

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

The default implementation just calls read(imageIndex, param).

Parameters:

imageIndex - the index of the image to be retrieved.

param - an ImageReadParam used to control the reading process, or null.

Returns:

a RenderedImage object providing a view of the image.

Throws:

java.lang.IllegalStateException - if the input source has not been set.

java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.

java.lang.IllegalArgumentException - if the set of source and destination bands specified by param.getSourceBands and param.getDestinationBands differ in length or include indices that are out of bounds.

java.lang.IllegalArgumentException - if the resulting image would have a width or height less than 1.

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

abort

public void abort()

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

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

abortRequested

protected boolean abortRequested()

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

Returns:

true if the current read 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()

addIIOReadWarningListener

public void addIIOReadWarningListener(IIOReadWarningListener listener)

Adds an IIOReadWarningListener 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 reader sees fit.

Parameters:

listener - an IIOReadWarningListener to be registered.

See Also:

removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)

removeIIOReadWarningListener

public void removeIIOReadWarningListener(IIOReadWarningListener listener)

Removes an IIOReadWarningListener from the list of registered error 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 IIOReadWarningListener to be unregistered.

See Also:

addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)

removeAllIIOReadWarningListeners

public void removeAllIIOReadWarningListeners()

Removes all currently registered IIOReadWarningListener objects.

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

addIIOReadProgressListener

public void addIIOReadProgressListener(IIOReadProgressListener listener)

Adds an IIOReadProgressListener 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 IIOReadProgressListener to be registered.

See Also:

removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)

removeIIOReadProgressListener

public void removeIIOReadProgressListener(IIOReadProgressListener listener)

Removes an IIOReadProgressListener 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 IIOReadProgressListener to be unregistered.

See Also:

addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)

removeAllIIOReadProgressListeners

public void removeAllIIOReadProgressListeners()

Removes all currently registered IIOReadProgressListener objects.

The default implementation sets the progressListeners instance variable to null.

addIIOReadUpdateListener

public void addIIOReadUpdateListener(IIOReadUpdateListener listener)

Adds an IIOReadUpdateListener to the list of registered update listeners. If listener is null, no exception will be thrown and no action will be taken. The listener will receive notification of pixel updates as images are decoded, including the starts and ends of progressive passes.

If no update listeners are present, the reader may choose to perform fewer updates to the pixels of the destination images, which may result in more efficient decoding.

For example, in progressive JPEG decoding each pass contains updates to a set of coefficients, which would have to be transformed into pixel values and converted to an RGB color space for each pass if listeners are present. If no listeners are present, the coefficients may simply be accumulated and the final results transformed and color converted one time only.

The final results of decoding will be the same whether or not intermediate updates are performed. Thus if only the final image is desired it may be perferable not to register any IIOReadUpdateListeners. In general, progressive updating is most effective when fetching images over a network connection that is very slow compared to local CPU processing; over a fast connection, progressive updates may actually slow down the presentation of the image.

Parameters:

listener - an IIOReadUpdateListener to be registered.

See Also:

removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)

removeIIOReadUpdateListener

public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)

Removes an IIOReadUpdateListener from the list of registered update 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 IIOReadUpdateListener to be unregistered.

See Also:

addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)

removeAllIIOReadUpdateListeners

public void removeAllIIOReadUpdateListeners()

Removes all currently registered IIOReadUpdateListener objects.

The default implementation sets the updateListeners instance variable to null.

processSequenceStarted

protected void processSequenceStarted(int minIndex)

Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceStarted method. Subclasses may use this method as a convenience.

Parameters:

minIndex - the lowest index being read.

processSequenceComplete

protected void processSequenceComplete()

Broadcasts the completion of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceComplete method. Subclasses may use this method as a convenience.

processImageStarted

protected void processImageStarted(int imageIndex)

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

Parameters:

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

processImageProgress

protected void processImageProgress(float percentageDone)

Broadcasts the current percentage of image completion to all registered IIOReadProgressListeners 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 read to all registered IIOReadProgressListeners by calling their imageComplete method. Subclasses may use this method as a convenience.

processReadAborted

protected void processReadAborted()

Broadcasts that the read has been aborted to all registered IIOReadProgressListeners by calling their readAborted method. Subclasses may use this method as a convenience.

processPassStarted

protected void processPassStarted(BufferedImage theImage,
                                  int pass,
                                  int minPass,
                                  int maxPass,
                                  int minX,
                                  int minY,
                                  int periodX,
                                  int periodY,
                                  int[] bands)

Broadcasts the beginning of a progressive pass to all registered IIOReadUpdateListeners by calling their passStarted method. Subclasses may use this method as a convenience.

Parameters:

theImage - the BufferedImage being updated.

pass - the index of the current pass, starting with 0.

minPass - the index of the first pass that will be decoded.

maxPass - the index of the last pass that will be decoded.

minX - the X coordinate of the upper-left pixel included in the pass.

minY - the X coordinate of the upper-left pixel included in the pass.

periodX - the horizontal separation between pixels.

periodY - the vertical separation between pixels.

bands - an array of ints indicating the set of affected bands of the destination.

processImageUpdate

protected void processImageUpdate(BufferedImage theImage,
                                  int minX,
                                  int minY,
                                  int width,
                                  int height,
                                  int periodX,
                                  int periodY,
                                  int[] bands)

Broadcasts the update of a set of samples to all registered IIOReadUpdateListeners by calling their imageUpdate method. Subclasses may use this method as a convenience.

Parameters:

theImage - the BufferedImage being updated.

minX - the X coordinate of the upper-left pixel included in the pass.

minY - the X coordinate of the upper-left pixel included in the pass.

width - the total width of the area being updated, including pixels being skipped if periodX > 1.

height - the total height of the area being updated, including pixels being skipped if periodY > 1.

periodX - the horizontal separation between pixels.

periodY - the vertical separation between pixels.

bands - an array of ints indicating the set of affected bands of the destination.

processPassComplete

protected void processPassComplete(BufferedImage theImage)

Broadcasts the end of a progressive pass to all registered IIOReadUpdateListeners by calling their passComplete method. Subclasses may use this method as a convenience.

Parameters:

theImage - the BufferedImage being updated.

processWarningOccurred

protected void processWarningOccurred(java.lang.String warning)

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

Parameters:

warning - the warning message to send.

Throws:

java.lang.IllegalArgumentException - if warning is null.

processWarningOccurred

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

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

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - if baseName is null.

java.lang.IllegalArgumentException - if keyword is null.

java.lang.IllegalArgumentException - if no appropriate ResourceBundle may be located.

java.lang.IllegalArgumentException - if the named resource is not found in the located ResourceBundle.

java.lang.IllegalArgumentException - if the object retrieved from the ResourceBundle is not a String.

reset

public void reset()

Restores the ImageReader to its initial state.

The default implementation calls setInput(null, false), setLocale(null), removeAllIIOReadUpdateListeners(), removeAllIIOReadWarningListeners(), removeAllIIOReadProgressListeners(), 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 ImageReader. Otherwise, the reader 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.

getSourceRegion

protected static Rectangle getSourceRegion(ImageReadParam param,
                                           int srcWidth,
                                           int srcHeight)

A utility method that may be used by readers to compute the region of the source image that should be read, taking into account any source region and subsampling offset settings in the supplied ImageReadParam. The actual subsampling factors, destination size, and destination offset are not taken into consideration, thus further clipping must take place. The computeRegions method performs all necessary clipping.

Parameters:

param - the ImageReadParam being used, or null.

srcWidth - the width of the source image.

srcHeight - the height of the source image.

Returns:

the source region as a Rectangle.

computeRegions

protected static void computeRegions(ImageReadParam param,
                                     int srcWidth,
                                     int srcHeight,
                                     BufferedImage image,
                                     Rectangle srcRegion,
                                     Rectangle destRegion)

Computes the source region of interest and the destination region of interest, taking the width and height of the source image, an optional destination image, and an optional ImageReadParam into account. The source region begins with the entire source image. Then that is clipped to the source region specified in the ImageReadParam, if one is specified.

If either of the destination offsets are negative, the source region is clipped so that its top left will coincide with the top left of the destination image, taking subsampling into account. Then the result is clipped to the destination image on the right and bottom, if one is specified, taking subsampling and destination offsets into account.

Similarly, the destination region begins with the source image, is translated to the destination offset given in the ImageReadParam if there is one, and finally is clipped to the destination image, if there is one.

If either the source or destination regions end up having a width or height of 0, an IllegalArgumentException is thrown.

The getSourceRegion method may be used if only source clipping is desired.

Parameters:

param - an ImageReadParam, or null.

srcWidth - the width of the source image.

srcHeight - the height of the source image.

image - a BufferedImage that will be the destination image, or null.

srcRegion - a Rectangle that will be filled with the source region of interest.

destRegion - a Rectangle that will be filled with the destination region of interest.

Throws:

java.lang.IllegalArgumentException - if srcRegion is null.

java.lang.IllegalArgumentException - if dstRegion is null.

java.lang.IllegalArgumentException - if the resulting source or destination region is empty.

checkReadParamBandSettings

protected static void checkReadParamBandSettings(ImageReadParam param,
                                                 int numSrcBands,
                                                 int numDstBands)

A utility method that may be used by readers to test the validity of the source and destination band settings of an ImageReadParam. This method may be called as soon as the reader knows both the number of bands of the source image as it exists in the input stream, and the number of bands of the destination image that being written.

The method retrieves the source and destination band setting arrays from param using the getSourceBands and getDestinationBandsmethods (or considers them to be null if param is null). If the source band setting array is null, it is considered to be equal to the array { 0, 1, ..., numSrcBands - 1 }, and similarly for the destination band setting array.

The method then tests that both arrays are equal in length, and that neither array contains a value larger than the largest available band index.

Any failure results in an IllegalArgumentException being thrown; success results in the method returning silently.

Parameters:

param - the ImageReadParam being used to read the image.

numSrcBands - the number of bands of the image as it exists int the input source.

numDstBands - the number of bands in the destination image being written.

Throws:

java.lang.IllegalArgumentException - if param contains an invalid specification of a source and/or destination band subset.

getDestination

protected static BufferedImage getDestination(ImageReadParam param,
                                              java.util.Iterator imageTypes,
                                              int width,
                                              int height)
                                       throws IIOException

Returns the BufferedImage to which decoded pixel data should be written. The image is determined by inspecting the supplied ImageReadParam if it is non-null; if its getDestination method returns a non-null value, that image is simply returned. Otherwise, param.getDestinationType method is called to determine if a particular image type has been specified. If so, the returned ImageTypeSpecifier is used after checking that it is equal to one of those included in imageTypes.

If param is null or the above steps have not yielded an image or an ImageTypeSpecifier, the first value obtained from the imageTypes parameter is used. Typically, the caller will set imageTypes to the value of getImageTypes(imageIndex).

Next, the dimensions of the image are determined by a call to computeRegions. The actual width and height of the image being decoded are passed in as the width and height parameters.

Parameters:

param - an ImageReadParam to be used to get the destination image or image type, or null.

imageTypes - an Iterator of ImageTypeSpecifiers indicating the legal image types, with the default first.

width - the true width of the image being decoded.

height - the true width of the image being decoded.

Returns:

the BufferedImage to which decoded pixel data should be written.

Throws:

IIOException - if the ImageTypeSpecifier specified by param does not match any of the legal ones from imageTypes.

java.lang.IllegalArgumentException - if imageTypes is null or empty, or if an object not of type ImageTypeSpecifier is retrieved from it.

java.lang.IllegalArgumentException - if the resulting image would have a width or height less than 1.

java.lang.IllegalArgumentException - if the product of width and height is greater than Integer.MAX_VALUE.