APIdia Launch Partner
Top Description Fields Constructors Methods
javax.imageio

public abstract Class ImageReader

extends Object
Class Inheritance
Known Direct Subclasses
com.sun.imageio.plugins.bmp.BMPImageReader, com.sun.imageio.plugins.gif.GIFImageReader, com.sun.imageio.plugins.jpeg.JPEGImageReader, com.sun.imageio.plugins.png.PNGImageReader, com.sun.imageio.plugins.tiff.TIFFImageReader, com.sun.imageio.plugins.wbmp.WBMPImageReader
Imports
java.awt.Point, .Rectangle, java.awt.image.BufferedImage, .Raster, .RenderedImage, java.io.IOException, java.util.ArrayList, .Iterator, .List, .Locale, .MissingResourceException, .ResourceBundle, .Set, javax.imageio.spi.ImageReaderSpi, javax.imageio.event.IIOReadWarningListener, .IIOReadProgressListener, .IIOReadUpdateListener, javax.imageio.metadata.IIOMetadata, .IIOMetadataFormatImpl, javax.imageio.stream.ImageInputStream
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.

ImageReader objects are normally instantiated by the service provider interface (SPI) class for the specific format. Service provider classes (e.g., instances of ImageReaderSpi) are registered with the IIORegistry, which uses them for format recognition and presentation of available format readers and writers.

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, javax.imageio.spi.IIORegistry, javax.imageio.spi.ImageReaderSpi

Field Summary

Modifier and TypeField and Description
private boolean
abortFlag

If true, the current read operation should be aborted.

protected Locale[]
availableLocales

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

protected boolean
ignoreMetadata

true if the current input source has been marked as allowing metadata to be ignored by setInput.

protected Object
input

The ImageInputStream or other Object by setInput and retrieved by getInput.

protected 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 ImageReaderSpi
originatingProvider

The ImageReaderSpi that instantiated this object, or null if its identity is not known or none exists.

protected List<IIOReadProgressListener>
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 List<IIOReadUpdateListener>
updateListeners

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

protected List<IIOReadWarningListener>
warningListeners

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

protected List<Locale>
warningLocales

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

Constructor Summary

AccessConstructor and Description
protected
ImageReader(ImageReaderSpi
the ImageReaderSpi that is invoking this constructor, or null.
originatingProvider)

Constructs an ImageReader and sets its originatingProvider field to the supplied value.

Method Summary

Modifier and TypeMethod and Description
public synchronized void
abort()

Requests that any current read operation be aborted.

protected synchronized boolean

Returns:

true if the current read operation should be aborted.
abortRequested()

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

public void
addIIOReadProgressListener(IIOReadProgressListener
an IIOReadProgressListener to be registered.
listener)

Adds an IIOReadProgressListener to the list of registered progress listeners.

public void
addIIOReadUpdateListener(IIOReadUpdateListener
an IIOReadUpdateListener to be registered.
listener)

Adds an IIOReadUpdateListener to the list of registered update listeners.

public void
addIIOReadWarningListener(IIOReadWarningListener
an IIOReadWarningListener to be registered.
listener)

Adds an IIOReadWarningListener to the list of registered warning listeners.

pack-priv static <T> List<T>
addToList(List<T> l, T elt)

public boolean

Returns:

true if this plug-in supports reading raw Rasters.
canReadRaster()

Returns true if this plug-in supports reading just a Raster of pixel data.

protected static void
checkReadParamBandSettings(ImageReadParam
the ImageReadParam being used to read the image.
param, int
the number of bands of the image as it exists int the input source.
numSrcBands, int
the number of bands in the destination image being written.
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 synchronized void
clearAbortRequest()

Clears any previous abort request.

protected static void
computeRegions(ImageReadParam
an ImageReadParam, or null.
param, int
the width of the source image.
srcWidth, int
the height of the source image.
srcHeight, BufferedImage
a BufferedImage that will be the destination image, or null.
image, Rectangle
a Rectangle that will be filled with the source region of interest.
srcRegion, Rectangle
a Rectangle that will be filled with the destination region of interest.
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.

public void
dispose()

Allows any resources held by this object to be released.

public float

Returns:

a float indicating the aspect ratio of the given image.
getAspectRatio(int
the index of the image to be queried.
imageIndex)

Returns the aspect ratio of the given image (that is, its width divided by its height) as a float.

public Locale[]

Returns:

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

Returns an array of Locales that may be used to localize warning listeners and compression settings.

public ImageReadParam

Returns:

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

Returns a default ImageReadParam object appropriate for this format.

protected static BufferedImage

Returns:

the BufferedImage to which decoded pixel data should be written.
getDestination(ImageReadParam
an ImageReadParam to be used to get the destination image or image type, or null.
param, Iterator<ImageTypeSpecifier>
an Iterator of ImageTypeSpecifiers indicating the legal image types, with the default first.
imageTypes, int
the true width of the image or tile being decoded.
width, int
the true width of the image or tile being decoded.
height)

Returns the BufferedImage to which decoded pixel data should be written.

public String

Returns:

the format name, as a String.
getFormatName()

Returns a String identifying the format of the input source.

public abstract int

Returns:

the height of the image, as an int.
getHeight(int
the index of the image to be queried.
imageIndex)

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

public abstract IIOMetadata

Returns:

an IIOMetadata object, or null.
getImageMetadata(int
the index of the image whose metadata is to be retrieved.
imageIndex)

Returns an IIOMetadata object containing metadata associated with the given image, or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.

public IIOMetadata

Returns:

an IIOMetadata object, or null.
getImageMetadata(int
the index of the image whose metadata is to be retrieved.
imageIndex, String
a metadata format name that may be used to retrieve a document from the returned IIOMetadata object.
formatName, Set<String>
a Set containing the names of nodes that may be contained in a retrieved document.
nodeNames)

Returns an IIOMetadata object representing the metadata associated with the given image, or null if the reader does not support reading metadata or none is available.

public abstract Iterator<ImageTypeSpecifier>

Returns:

an Iterator containing at least one ImageTypeSpecifier representing suggested image types for decoding the current given image.
getImageTypes(int
the index of the image to be retrieved.
imageIndex)

Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss.

public Object

Returns:

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

Returns the ImageInputStream or other Object previously set as the input source.

public Locale

Returns:

the current Locale, or null.
getLocale()

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

private IIOMetadata
getMetadata(String formatName, Set<String> nodeNames, boolean wantStream, int imageIndex)

public int

Returns:

the minimum legal index for reading.
getMinIndex()

Returns the lowest valid index for reading an image, thumbnail, or image metadata.

public abstract int

Returns:

the number of images, as an int, or -1 if allowSearch is false and a search would be required.
getNumImages(boolean
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.
allowSearch)

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

public int

Returns:

the number of thumbnails associated with the given image.
getNumThumbnails(int
the index of the image being queried.
imageIndex)

Returns the number of thumbnail preview images associated with the given image.

public ImageReaderSpi

Returns:

an ImageReaderSpi, or null.
getOriginatingProvider()

Returns the ImageReaderSpi that was passed in on the constructor.

public ImageTypeSpecifier

Returns:

an ImageTypeSpecifier.
getRawImageType(int
the index of the image to be queried.
imageIndex)

Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image.

protected static Rectangle

Returns:

the source region as a Rectangle.
getSourceRegion(ImageReadParam
the ImageReadParam being used, or null.
param, int
the width of the source image.
srcWidth, int
the height of the source image.
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.

public abstract IIOMetadata

Returns:

an IIOMetadata object, or null.
getStreamMetadata()

Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image), or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.

public IIOMetadata

Returns:

an IIOMetadata object, or null.
getStreamMetadata(String
a metadata format name that may be used to retrieve a document from the returned IIOMetadata object.
formatName, Set<String>
a Set containing the names of nodes that may be contained in a retrieved document.
nodeNames)

Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image).

public int

Returns:

the height of the desired thumbnail as an int.
getThumbnailHeight(int
the index of the image to be retrieved.
imageIndex, int
the index of the thumbnail to be retrieved.
thumbnailIndex)

Returns the height of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex.

public int

Returns:

the width of the desired thumbnail as an int.
getThumbnailWidth(int
the index of the image to be retrieved.
imageIndex, int
the index of the thumbnail to be retrieved.
thumbnailIndex)

Returns the width of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex.

public int

Returns:

the X offset of the tile grid.
getTileGridXOffset(int
the index of the image to be queried.
imageIndex)

Returns the X coordinate of the upper-left corner of tile (0, 0) in the given image.

public int

Returns:

the Y offset of the tile grid.
getTileGridYOffset(int
the index of the image to be queried.
imageIndex)

Returns the Y coordinate of the upper-left corner of tile (0, 0) in the given image.

public int

Returns:

the height of a tile.
getTileHeight(int
the index of the image to be queried.
imageIndex)

Returns the height of a tile in the given image.

public int

Returns:

the width of a tile.
getTileWidth(int
the index of the image to be queried.
imageIndex)

Returns the width of a tile in the given image.

public abstract int

Returns:

the width of the image, as an int.
getWidth(int
the index of the image to be queried.
imageIndex)

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

public boolean

Returns:

true if the given image has thumbnails.
hasThumbnails(int
the index of the image being queried.
imageIndex)

Returns true if the given image has thumbnail preview images associated with it.

public boolean

Returns:

true if the metadata may be ignored.
isIgnoringMetadata()

Returns true if the current input source has been marked as allowing metadata to be ignored by passing true as the ignoreMetadata argument to the setInput method.

public boolean

Returns:

true if the image is tiled.
isImageTiled(int
the index of the image to be queried.
imageIndex)

Returns true if the image is organized into tiles, that is, equal-sized non-overlapping rectangles.

public boolean

Returns:

true if reading a region of interest of the given image is likely to be efficient.
isRandomAccessEasy(int
the index of the image to be queried.
imageIndex)

Returns true if the storage format of the given image places no inherent impediment on random access to pixels.

public boolean

Returns:

true if the input source is seek forward only.
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
the current percentage of completion, as a float.
percentageDone)

Broadcasts the current percentage of image completion to all registered IIOReadProgressListeners by calling their imageProgress method.

protected void
processImageStarted(int
the index of the image about to be read.
imageIndex)

Broadcasts the start of an image read to all registered IIOReadProgressListeners by calling their imageStarted method.

protected void
processImageUpdate(BufferedImage
the BufferedImage being updated.
theImage, int
the X coordinate of the upper-left pixel included in the pass.
minX, int
the X coordinate of the upper-left pixel included in the pass.
minY, int
the total width of the area being updated, including pixels being skipped if periodX > 1.
width, int
the total height of the area being updated, including pixels being skipped if periodY > 1.
height, int
the horizontal separation between pixels.
periodX, int
the vertical separation between pixels.
periodY, int[]
an array of ints indicating the set of affected bands of the destination.
bands)

Broadcasts the update of a set of samples to all registered IIOReadUpdateListeners by calling their imageUpdate method.

protected void
processPassComplete(BufferedImage
the BufferedImage being updated.
theImage)

Broadcasts the end of a progressive pass to all registered IIOReadUpdateListeners by calling their passComplete method.

protected void
processPassStarted(BufferedImage
the BufferedImage being updated.
theImage, int
the index of the current pass, starting with 0.
pass, int
the index of the first pass that will be decoded.
minPass, int
the index of the last pass that will be decoded.
maxPass, int
the X coordinate of the upper-left pixel included in the pass.
minX, int
the X coordinate of the upper-left pixel included in the pass.
minY, int
the horizontal separation between pixels.
periodX, int
the vertical separation between pixels.
periodY, int[]
an array of ints indicating the set of affected bands of the destination.
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
the lowest index being read.
minIndex)

Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceStarted method.

protected void
processThumbnailComplete()

Broadcasts the completion of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailComplete method.

protected void
processThumbnailPassComplete(BufferedImage
the BufferedImage thumbnail being updated.
theThumbnail)

Broadcasts the end of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassComplete method.

protected void
processThumbnailPassStarted(BufferedImage
the BufferedImage thumbnail being updated.
theThumbnail, int
the index of the current pass, starting with 0.
pass, int
the index of the first pass that will be decoded.
minPass, int
the index of the last pass that will be decoded.
maxPass, int
the X coordinate of the upper-left pixel included in the pass.
minX, int
the X coordinate of the upper-left pixel included in the pass.
minY, int
the horizontal separation between pixels.
periodX, int
the vertical separation between pixels.
periodY, int[]
an array of ints indicating the set of affected bands of the destination.
bands)

Broadcasts the beginning of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassStarted method.

protected void
processThumbnailProgress(float
the current percentage of completion, as a float.
percentageDone)

Broadcasts the current percentage of thumbnail completion to all registered IIOReadProgressListeners by calling their thumbnailProgress method.

protected void
processThumbnailStarted(int
the index of the image associated with the thumbnail.
imageIndex, int
the index of the thumbnail.
thumbnailIndex)

Broadcasts the start of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailStarted method.

protected void
processThumbnailUpdate(BufferedImage
the BufferedImage thumbnail being updated.
theThumbnail, int
the X coordinate of the upper-left pixel included in the pass.
minX, int
the X coordinate of the upper-left pixel included in the pass.
minY, int
the total width of the area being updated, including pixels being skipped if periodX > 1.
width, int
the total height of the area being updated, including pixels being skipped if periodY > 1.
height, int
the horizontal separation between pixels.
periodX, int
the vertical separation between pixels.
periodY, int[]
an array of ints indicating the set of affected bands of the destination.
bands)

Broadcasts the update of a set of samples in a thumbnail image to all registered IIOReadUpdateListeners by calling their thumbnailUpdate method.

protected void
processWarningOccurred(String
the warning message to send.
warning)

Broadcasts a warning message to all registered IIOReadWarningListeners by calling their warningOccurred method.

protected void
processWarningOccurred(String
the base name of a set of ResourceBundles containing localized warning messages.
baseName, String
the keyword used to index the warning message within the set of ResourceBundles.
keyword)

Broadcasts a localized warning message to all registered IIOReadWarningListeners by calling their warningOccurred method with a string taken from a ResourceBundle.

public BufferedImage

Returns:

the desired portion of the image as a BufferedImage.
read(int
the index of the image to be retrieved.
imageIndex)

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

public abstract BufferedImage

Returns:

the desired portion of the image as a BufferedImage.
read(int
the index of the image to be retrieved.
imageIndex, ImageReadParam
an ImageReadParam used to control the reading process, or null.
param)

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

public IIOImage

Returns:

an IIOImage containing the desired portion of the image, a set of thumbnails, and associated image metadata.
readAll(int
the index of the image to be retrieved.
imageIndex, ImageReadParam
an ImageReadParam used to control the reading process, or null.
param)

Reads the image indexed by imageIndex and returns an IIOImage containing the image, thumbnails, and associated image metadata, using a supplied ImageReadParam.

public Iterator<IIOImage>

Returns:

an Iterator representing the contents of the input source as IIOImages.
readAll(Iterator<? extends ImageReadParam>
an Iterator containing ImageReadParam objects.
params)

Returns an Iterator containing all the images, thumbnails, and metadata, starting at the index given by getMinIndex, from the input source in the form of IIOImage objects.

public RenderedImage

Returns:

a RenderedImage object providing a view of the image.
readAsRenderedImage(int
the index of the image to be retrieved.
imageIndex, ImageReadParam
an ImageReadParam used to control the reading process, or null.
param)

Returns a RenderedImage object that contains the contents of the image indexed by imageIndex.

public boolean

Returns:

true if thumbnails are supported.
readerSupportsThumbnails()

Returns true if the image format understood by this reader supports thumbnail preview images associated with it.

public Raster

Returns:

the desired portion of the image as a Raster.
readRaster(int
the index of the image to be read.
imageIndex, ImageReadParam
an ImageReadParam used to control the reading process, or null.
param)

Returns a new Raster object containing the raw pixel data from the image stream, without any color conversion applied.

public BufferedImage

Returns:

the desired thumbnail as a BufferedImage.
readThumbnail(int
the index of the image to be retrieved.
imageIndex, int
the index of the thumbnail to be retrieved.
thumbnailIndex)

Returns the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex as a BufferedImage.

public BufferedImage

Returns:

the tile as a BufferedImage.
readTile(int
the index of the image to be retrieved.
imageIndex, int
the column index (starting with 0) of the tile to be retrieved.
tileX, int
the row index (starting with 0) of the tile to be retrieved.
tileY)

Reads the tile indicated by the tileX and tileY arguments, returning it as a BufferedImage.

public Raster

Returns:

the tile as a Raster.
readTileRaster(int
the index of the image to be retrieved.
imageIndex, int
the column index (starting with 0) of the tile to be retrieved.
tileX, int
the row index (starting with 0) of the tile to be retrieved.
tileY)

Returns a new Raster object containing the raw pixel data from the tile, without any color conversion applied.

public void
removeAllIIOReadProgressListeners()

Removes all currently registered IIOReadProgressListener objects.

public void
removeAllIIOReadUpdateListeners()

Removes all currently registered IIOReadUpdateListener objects.

public void
removeAllIIOReadWarningListeners()

Removes all currently registered IIOReadWarningListener objects.

pack-priv static <T> List<T>
removeFromList(List<T> l, T elt)

public void
removeIIOReadProgressListener(IIOReadProgressListener
an IIOReadProgressListener to be unregistered.
listener)

Removes an IIOReadProgressListener from the list of registered progress listeners.

public void
removeIIOReadUpdateListener(IIOReadUpdateListener
an IIOReadUpdateListener to be unregistered.
listener)

Removes an IIOReadUpdateListener from the list of registered update listeners.

public void
removeIIOReadWarningListener(IIOReadWarningListener
an IIOReadWarningListener to be unregistered.
listener)

Removes an IIOReadWarningListener from the list of registered error listeners.

public void
reset()

Restores the ImageReader to its initial state.

public void
setInput(Object
the ImageInputStream or other Object to use for future decoding.
input, boolean
if true, images and metadata may only be read in ascending order from this input source.
seekForwardOnly, boolean
if true, metadata may be ignored during reads.
ignoreMetadata)

Sets the input source to use to the given ImageInputStream or other Object.

public void
setInput(Object
the ImageInputStream or other Object to use for future decoding.
input, boolean
if true, images and metadata may only be read in ascending order from this input source.
seekForwardOnly)

Sets the input source to use to the given ImageInputStream or other Object.

public void
setInput(Object
the ImageInputStream or other Object to use for future decoding.
input)

Sets the input source to use to the given ImageInputStream or other Object.

public void
setLocale(Locale
the desired Locale, or null.
locale)

Sets the current Locale of this ImageReader to the given value.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait