Java Doc for ImageReader.java in  » 6.0-JDK-Core » image » javax » imageio » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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
See Also:   javax.imageio.spi.IIORegistry
See Also:   javax.imageio.spi.ImageReaderSpi
version:
   0.5

Subclasses that make use of extensions should provide a constructor with signature (ImageReaderSpi, Object) in order to retrieve the extension object.

The default implementation returns originatingProvider.getFormatNames()[0]. Implementations that may not have an originating service provider, or which desire a different naming policy should override this method.
exception:
  IOException - if an error occurs reading theinformation from 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.

The resuting metadata object is only responsible for returning documents in the format named by formatName.

Note that some image formats (such as animated GIF) do not specify how many images are present in the stream.

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.

The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getHeight().

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.

The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getWidth().

A reader for which the tile grid X offset always has the same value (usually 0), may return the value without accessing any image data.

A reader for which the tile grid Y offset always has the same value (usually 0), may return the value without accessing any image data.

The default implementation simply returns getHeight(imageIndex), which is correct for non-tiled images.

The default implementation simply returns getWidth(imageIndex), which is correct for non-tiled images.

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.

A reader plug-in may choose whether or not to expose tiling that is present in the image as it is stored.

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.

Note that formats that return false from this method may nonetheless allow tiling (e.g. Restart Markers in JPEG), and random access will likely be reasonably efficient on tiles.

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.

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 imageStarted method, followed by calls to their imageProgress method as the read progresses.

Any registered IIOReadProgressListener objects will be notified by calling their thumbnailStarted, thumbnailProgress, and thumbnailComplete methods.

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown regardless of whether an input source has been set or whether the indices are in bounds.

The default implementation throws an UnsupportedOperationException.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  thumbnailIndex - the index of the thumbnail to be retrieved.

Subclasses that make use of extensions should provide a constructor with signature (ImageReaderSpi, Object) in order to retrieve the extension object. If the extension object is unsuitable, an IllegalArgumentException should be thrown.
Parameters:
  originatingProvider - the ImageReaderSpi that isinvoking this constructor, or null.

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

If no update listeners are present, the reader may choose to perform fewer updates to the pixels of the destination images and/or thumbnails, 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:   ImageReader.removeIIOReadUpdateListener

The default implementation returns false. true if this plug-in supports reading rawRasters.
See Also:   ImageReader.readRaster
See Also:   ImageReader.readTileRaster

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 readthe image.
Parameters:
  numSrcBands - the number of bands of the image as it existsint the input source.
Parameters:
  numDstBands - the number of bands in the destination imagebeing written.
exception:
  IllegalArgumentException - if paramcontains an invalid specification of a source and/ordestination band subset.

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 ImageReader.getSourceRegion getSourceRegion method may be used if only source clipping is desired.
Parameters:
  param - an ImageReadParam, or null.
Parameters:
  srcWidth - the width of the source image.
Parameters:
  srcHeight - the height of the source image.
Parameters:
  image - a BufferedImage that will be the destination image, or null.
Parameters:
  srcRegion - a Rectangle that will be filled withthe source region of interest.
Parameters:
  destRegion - a Rectangle that will be filled withthe destination region of interest.
exception:
  IllegalArgumentException - if srcRegionis null.
exception:
  IllegalArgumentException - if dstRegionis null.
exception:
  IllegalArgumentException - if the resulting source ordestination region is empty.

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.

The default implementation simply returns (float)getWidth(imageIndex)/getHeight(imageIndex).
Parameters:
  imageIndex - the index of the image to be queried. a float indicating the aspect ratio of thegiven image.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs during reading.

The default implementation returns a clone of the availableLocales instance variable if it is non-null, or else returns null. an array of Locales that may be used asarguments to setLocale, or null.

The default implementation constructs and returns a new ImageReadParam object that does not allow source scaling (i.e., it returns new ImageReadParam(). an ImageReadParam object which may be usedto control the decoding process using a set of default settings.

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 getthe destination image or image type, or null.
Parameters:
  imageTypes - an Iterator ofImageTypeSpecifiers indicating the legal imagetypes, with the default first.
Parameters:
  width - the true width of the image or tile begin decoded.
Parameters:
  height - the true width of the image or tile being decoded. the BufferedImage to which decoded pixeldata should be written.
exception:
  IIOException - if the ImageTypeSpecifierspecified by param does not match any of the legalones from imageTypes.
exception:
  IllegalArgumentException - if imageTypesis null or empty, or if an object not of typeImageTypeSpecifier is retrieved from it.
exception:
  IllegalArgumentException - if the resulting image wouldhave a width or height less than 1.
exception:
  IllegalArgumentException - if the product ofwidth and height is greater thanInteger.MAX_VALUE.

The default implementation returns originatingProvider.getFormatNames()[0]. Implementations that may not have an originating service provider, or which desire a different naming policy should override this method.
exception:
  IOException - if an error occurs reading theinformation from the input source. the format name, as a String.

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. the height of the image, as an int.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs reading the heightinformation from the input source.

The resuting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.

If formatName is not the name of a supported metadata format, null may be returned.

In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.

The default implementation simply returns the result of calling getImageMetadata(imageIndex), after checking that the format name is supported. If it is not, null is returned.
Parameters:
  imageIndex - the index of the image whose metadata is tobe retrieved.
Parameters:
  formatName - a metadata format name that may be used to retrievea document from the returned IIOMetadata object.
Parameters:
  nodeNames - a Set containing the names of nodes that may be contained in a retrieved document. an IIOMetadata object, or null.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IllegalArgumentException - if formatNameis null.
exception:
  IllegalArgumentException - if nodeNamesis null.
exception:
  IOException - if an error occurs during reading.

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 beretrieved. an Iterator containing at least oneImageTypeSpecifier representing suggested imagetypes for decoding the current given image.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs reading the formatinformation from the input source.
See Also:   ImageReadParam.setDestination(BufferedImage)
See Also:   ImageReadParam.setDestinationType(ImageTypeSpecifier)

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 ofimages will be returned even if a search is required. Iffalse, the reader may return -1without performing the search. the number of images, as an int, or-1 if allowSearch isfalse and a search would be required.
exception:
  IllegalStateException - if the input source has not been set,or if the input has been specified with seekForwardOnlyset to true.
exception:
  IOException - if an error occurs reading theinformation from the input source.
See Also:   ImageReader.setInput

The default implementation returns 0 without checking its argument.
Parameters:
  imageIndex - the index of the image being queried. the number of thumbnails associated with the givenimage.
exception:
  IllegalStateException - if the reader supportsthumbnails but the input source has not been set.
exception:
  IndexOutOfBoundsException - if the reader supportsthumbnails but imageIndex is out of bounds.
exception:
  IOException - if an error occurs during reading.

The default implementation simply returns the first entry from the list provided by getImageType.
Parameters:
  imageIndex - the index of the image to be queried. an ImageTypeSpecifier.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs reading the formatinformation from the input source.

The resuting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.

If formatName is not the name of a supported metadata format, null is returned.

In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.

The default implementation simply returns the result of calling getStreamMetadata(), after checking that the format name is supported. If it is not, null is returned.
Parameters:
  formatName - a metadata format name that may be used to retrievea document from the returned IIOMetadata object.
Parameters:
  nodeNames - a Set containing the names of nodes that may be contained in a retrieved document. an IIOMetadata object, or null.
exception:
  IllegalArgumentException - if formatNameis null.
exception:
  IllegalArgumentException - if nodeNamesis null.
exception:
  IOException - if an error occurs during reading.

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.

The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getHeight(). Subclasses should therefore override this method if possible in order to avoid forcing the thumbnail to be read.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  thumbnailIndex - the index of the thumbnail to be retrieved. the height of the desired thumbnail as an int.
exception:
  UnsupportedOperationException - if thumbnails are notsupported.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if either of the suppliedindices are out of bounds.
exception:
  IOException - if an error occurs during reading.

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown.

The default implementation simply returns readThumbnail(imageindex, thumbnailIndex).getWidth(). Subclasses should therefore override this method if possible in order to avoid forcing the thumbnail to be read.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  thumbnailIndex - the index of the thumbnail to be retrieved. the width of the desired thumbnail as an int.
exception:
  UnsupportedOperationException - if thumbnails are notsupported.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if either of the suppliedindices are out of bounds.
exception:
  IOException - if an error occurs during reading.

A reader for which the tile grid X offset always has the same value (usually 0), may return the value 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 simply returns 0, which is correct for non-tiled images and tiled images in most formats. Readers that support tiling with non-(0, 0) offsets should override this method. the X offset of the tile grid.
Parameters:
  imageIndex - the index of the image to be queried.
exception:
  IllegalStateException - if an input source is requiredto determine the return value, but none has been set.
exception:
  IndexOutOfBoundsException - if an image must beaccessed to determine the return value, but the supplied indexis out of bounds.
exception:
  IOException - if an error occurs during reading.

A reader for which the tile grid Y offset always has the same value (usually 0), may return the value 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 simply returns 0, which is correct for non-tiled images and tiled images in most formats. Readers that support tiling with non-(0, 0) offsets should override this method. the Y offset of the tile grid.
Parameters:
  imageIndex - the index of the image to be queried.
exception:
  IllegalStateException - if an input source is requiredto determine the return value, but none has been set.
exception:
  IndexOutOfBoundsException - if an image must beaccessed to determine the return value, but the supplied indexis out of bounds.
exception:
  IOException - if an error occurs during reading.

The default implementation simply returns getHeight(imageIndex), which is correct for non-tiled images. Readers that support tiling should override this method. the height of a tile.
Parameters:
  imageIndex - the index of the image to be queried.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs during reading.

The default implementation simply returns getWidth(imageIndex), which is correct for non-tiled images. Readers that support tiling should override this method. the width of a tile.
Parameters:
  imageIndex - the index of the image to be queried.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs during reading.

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. the width of the image, as an int.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs reading the widthinformation from the input source.

The default implementation returns true if getNumThumbnails returns a value greater than 0.
Parameters:
  imageIndex - the index of the image being queried. true if the given image has thumbnails.
exception:
  IllegalStateException - if the reader supportsthumbnails but the input source has not been set.
exception:
  IndexOutOfBoundsException - if the reader supportsthumbnails but imageIndex is out of bounds.
exception:
  IOException - if an error occurs during reading.

A reader plug-in may choose whether or not to expose tiling that is present in the image as it is stored. It may even choose to advertise tiling when none is explicitly present. In general, tiling should only be advertised if there is some advantage (in speed or space) to accessing individual tiles. Regardless of whether the reader advertises tiling, it must be capable of reading an arbitrary rectangular region specified in an ImageReadParam.

A reader for which all images are guaranteed to be tiled, or are guaranteed not to be tiled, 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 just returns false.
Parameters:
  imageIndex - the index of the image to be queried. true if the image is tiled.
exception:
  IllegalStateException - if an input source is requiredto determine the return value, but none has been set.
exception:
  IndexOutOfBoundsException - if an image must beaccessed to determine the return value, but the supplied indexis out of bounds.
exception:
  IOException - if an error occurs during reading.

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.

Note that formats that return false from this method may nonetheless allow tiling (e.g. Restart Markers in JPEG), and random access will likely be reasonably efficient on tiles. See ImageReader.isImageTiled isImageTiled .

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. true if reading a region of interest ofthe given image is likely to be efficient.
exception:
  IllegalStateException - if an input source is requiredto determine the return value, but none has been set.
exception:
  IndexOutOfBoundsException - if an image must beaccessed to determine the return value, but the supplied indexis out of bounds.
exception:
  IOException - if an error occurs during reading.

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. the desired portion of the image as aBufferedImage.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs during reading.

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 (e.g. source render size or any format-specific settings), they will be ignored.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  param - an ImageReadParam used to controlthe reading process, or null. the desired portion of the image as aBufferedImage.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IllegalArgumentException - if the set of source anddestination bands specified byparam.getSourceBands andparam.getDestinationBands differ in length orinclude indices that are out of bounds.
exception:
  IllegalArgumentException - if the resulting image wouldhave a width or height less than 1.
exception:
  IOException - if an error occurs during reading.

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 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.

Thumbnails will be returned in their entirety regardless of the region settings.

If the supplied ImageReadParam contains optional setting values not supported by this reader (e.g. source render size or any format-specific settings), those values will be ignored.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  param - an ImageReadParam used to controlthe reading process, or null. an IIOImage containing the desired portionof the image, a set of thumbnails, and associated imagemetadata.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IllegalArgumentException - if the set of source anddestination bands specified byparam.getSourceBands andparam.getDestinationBands differ in length orinclude indices that are out of bounds.
exception:
  IllegalArgumentException - if the resulting imagewould have a width or height less than 1.
exception:
  IOException - if an error occurs during reading.

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.

Thumbnails will be returned in their entirety regardless of the region settings.

If any of the supplied ImageReadParams contain optional setting values not supported by this reader (e.g. source render size or any format-specific settings), they will be ignored.
Parameters:
  params - an Iterator containingImageReadParam objects. an Iterator representing thecontents of the input source as IIOImages.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IllegalArgumentException - if anynon-null element of params is not anImageReadParam.
exception:
  IllegalArgumentException - if the set of source anddestination bands specified byparam.getSourceBands andparam.getDestinationBands differ in length orinclude indices that are out of bounds.
exception:
  IllegalArgumentException - if a resulting image wouldhave a width or height less than 1.
exception:
  IOException - if an error occurs during reading.
See Also:   ImageReadParam
See Also:   IIOImage

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 (e.g. source render size or any format-specific settings), they will be ignored.

The default implementation just calls ImageReader.readread(imageIndex, param) .
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  param - an ImageReadParam used to controlthe reading process, or null. a RenderedImage object providing a view ofthe image.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IllegalArgumentException - if the set of source anddestination bands specified byparam.getSourceBands andparam.getDestinationBands differ in length orinclude indices that are out of bounds.
exception:
  IllegalArgumentException - if the resulting imagewould have a width or height less than 1.
exception:
  IOException - if an error occurs during reading.

This method allows formats that normally apply a color conversion, such as JPEG, and formats that do not normally have an associated colorspace, such as remote sensing or medical imaging data, to provide access to raw pixel data.

Any registered readUpdateListeners are ignored, as there is no BufferedImage, but all other listeners are called exactly as they are for the ImageReader.read read method.

If ImageReader.canReadRaster canReadRaster() returns false, this method throws an UnsupportedOperationException.

If the supplied ImageReadParam contains optional setting values not supported by this reader (e.g. source render size or any format-specific settings), they will be ignored.

The default implementation throws an UnsupportedOperationException.
Parameters:
  imageIndex - the index of the image to be read.
Parameters:
  param - an ImageReadParam used to controlthe reading process, or null. the desired portion of the image as aRaster.
exception:
  UnsupportedOperationException - if this plug-in does notsupport reading raw Rasters.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if the supplied index isout of bounds.
exception:
  IOException - if an error occurs during reading.
See Also:   ImageReader.canReadRaster
See Also:   ImageReader.read
See Also:   java.awt.image.Raster

Any registered IIOReadProgressListener objects will be notified by calling their thumbnailStarted, thumbnailProgress, and thumbnailComplete methods.

If the reader does not support thumbnails, (readerSupportsThumbnails returns false), an UnsupportedOperationException will be thrown regardless of whether an input source has been set or whether the indices are in bounds.

The default implementation throws an UnsupportedOperationException.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  thumbnailIndex - the index of the thumbnail to be retrieved. the desired thumbnail as a BufferedImage.
exception:
  UnsupportedOperationException - if thumbnails are notsupported.
exception:
  IllegalStateException - if the input source has not been set.
exception:
  IndexOutOfBoundsException - if either of the suppliedindices are out of bounds.
exception:
  IOException - if an error occurs during reading.

This method is merely a convenience equivalent to calling read(int, ImageReadParam) with a read param specifiying a source region having offsets of tileX*getTileWidth(imageIndex), tileY*getTileHeight(imageIndex) and width and height of getTileWidth(imageIndex), getTileHeight(imageIndex); and subsampling factors of 1 and offsets of 0. To subsample a tile, call read with a read param specifying this region and different subsampling parameters.

The default implementation returns the entire image if tileX and tileY are 0, or throws an IllegalArgumentException otherwise.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  tileX - the column index (starting with 0) of the tileto be retrieved.
Parameters:
  tileY - the row index (starting with 0) of the tileto be retrieved. the tile as a BufferedImage.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if imageIndexis out of bounds.
exception:
  IllegalArgumentException - if the tile indices areout of bounds.
exception:
  IOException - if an error occurs during reading.

If ImageReader.canReadRaster canReadRaster() returns false, this method throws an UnsupportedOperationException.

The default implementation checks if reading Rasters is supported, and if so calls ImageReader.readRaster readRaster(imageIndex, null) if tileX and tileY are 0, or throws an IllegalArgumentException otherwise.
Parameters:
  imageIndex - the index of the image to be retrieved.
Parameters:
  tileX - the column index (starting with 0) of the tileto be retrieved.
Parameters:
  tileY - the row index (starting with 0) of the tileto be retrieved. the tile as a Raster.
exception:
  UnsupportedOperationException - if this plug-in does notsupport reading raw Rasters.
exception:
  IllegalArgumentException - if the tile indices areout of bounds.
exception:
  IllegalStateException - if the input source has not beenset.
exception:
  IndexOutOfBoundsException - if imageIndexis out of bounds.
exception:
  IOException - if an error occurs during reading.
See Also:   ImageReader.readTile
See Also:   ImageReader.readRaster
See Also:   java.awt.image.Raster

If this method returns false, hasThumbnails and getNumThumbnails will return false and 0, respectively, and readThumbnail will throw an UnsupportedOperationException, regardless of their arguments.

A reader that does not support thumbnails need not implement any of the thumbnail-related methods. true if thumbnails are supported.

The default implementation sets the progressListeners instance variable to null.

The default implementation sets the updateListeners instance variable to null.

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

The default implementation calls setInput(null, false), setLocale(null), removeAllIIOReadUpdateListeners(), removeAllIIOReadWarningListeners(), removeAllIIOReadProgressListeners(), and clearAbortRequest.

The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) 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.

The ignoreMetadata parameter, if set to true, allows the reader to disregard any metadata encountered during the read. Subsequent calls to the getStreamMetadata and getImageMetadata methods may return null, and an IIOImage returned from readAll may return null from their getMetadata method. Setting this parameter may allow the reader to work more efficiently. The reader may choose to disregard this setting and return metadata normally.

Subclasses should take care to remove any cached information based on the previous stream, such as header information or partially decoded image data.

Use of a general Object other than an ImageInputStream is intended for readers that interact directly with a capture device or imaging protocol. The set of legal classes is advertised by the reader's service provider's getInputTypes method; most readers will return a single-element array containing only ImageInputStream.class to indicate that they accept only an ImageInputStream.

The default implementation checks the input argument against the list returned by originatingProvider.getInputTypes() and fails if the argument is not an instance of one of the classes in the list. If the originating provider is set to null, the input is accepted only if it is an ImageInputStream.
Parameters:
  input - the ImageInputStream or otherObject to use for future decoding.
Parameters:
  seekForwardOnly - if true, images and metadatamay only be read in ascending order from this input source.
Parameters:
  ignoreMetadata - if true, metadatamay be ignored during reads.
exception:
  IllegalArgumentException - if input isnot an instance of one of the classes returned by theoriginating service provider's getInputTypesmethod, or is not an ImageInputStream.
See Also:   ImageInputStream
See Also:   ImageReader.getInput
See Also:   javax.imageio.spi.ImageReaderSpi.getInputTypes

The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) 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.

This method is equivalent to setInput(input, seekForwardOnly, false).
Parameters:
  input - the ImageInputStream or otherObject to use for future decoding.
Parameters:
  seekForwardOnly - if true, images and metadatamay only be read in ascending order from this input source.
exception:
  IllegalArgumentException - if input isnot an instance of one of the classes returned by theoriginating service provider's getInputTypesmethod, or is not an ImageInputStream.
See Also:   ImageReader.getInput

This method is equivalent to setInput(input, false, false).
Parameters:
  input - the ImageInputStream or otherObject to use for future decoding.
exception:
  IllegalArgumentException - if input isnot an instance of one of the classes returned by theoriginating service provider's getInputTypesmethod, or is not an ImageInputStream.
See Also:   ImageReader.getInput