org.geotoolkit.image.io
Class StreamImageReader

Object
  ImageReader
      SpatialImageReader
          StreamImageReader

All Implemented Interfaces:

WarningProducer, Disposable, Localized

Direct Known Subclasses:

FileImageReader, TextImageReader

public abstract class StreamImageReader
extends SpatialImageReader

Base class for image readers that expect an InputStream or channel input source. This class provides a getInputStream() method, which return the input as an InputStream for convenience.

Different kinds of outputs are automatically handled. The default implementation handles all the following types:

String, File, URI, URL, URLConnection, InputStream, ImageInputStream, ReadableByteChannel.

Note the TextImageReader subclass can go one step further by wrapping the InputStream into a BufferedReader using some character encoding.

Since:

2.4

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

StreamImageWriter

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

protected static class

StreamImageReader.Spi Service provider interface (SPI) for StreamImageReaders.

Field Summary

protected Closeable

closeOnReset The stream to close on setInput(...), ImageReader.reset() or SpatialImageReader.dispose() method invocation.

Fields inherited from class ImageReader

availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

protected

StreamImageReader(StreamImageReader.Spi provider) Constructs a new image reader.

Method Summary

protected void	close() Closes the input stream created by getInputStream().
protected void	finalize() Invokes the close() method when this reader is garbage-collected.
protected ReadableByteChannel	getChannel() Returns the input as an readable byte channel.
protected InputStream	getInputStream() Returns the input as an input stream object.
protected long	getStreamLength() Returns the stream length in bytes, or -1 if unknown.
void	setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata) Sets the input source to use.

Methods inherited from class SpatialImageReader

checkBandIndex, checkImageIndex, collapseNoDataValues, createMetadata, dispose, flipVertically, getDefaultReadParam, getDestination, getDimension, getGridEnvelope, getImageMetadata, getImageType, getImageTypes, getNumBands, getNumImages, getRawDataType, getRawImageType, getStreamMetadata, hasColors, warningOccurred

Methods inherited from class ImageReader

abort, abortRequested, addIIOReadProgressListener, addIIOReadUpdateListener, addIIOReadWarningListener, canReadRaster, checkReadParamBandSettings, clearAbortRequest, computeRegions, getAspectRatio, getAvailableLocales, getDestination, getFormatName, getHeight, getImageMetadata, getInput, getLocale, getMinIndex, getNumThumbnails, getOriginatingProvider, getSourceRegion, getStreamMetadata, getThumbnailHeight, getThumbnailWidth, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getWidth, hasThumbnails, isIgnoringMetadata, isImageTiled, isRandomAccessEasy, isSeekForwardOnly, processImageComplete, processImageProgress, processImageStarted, processImageUpdate, processPassComplete, processPassStarted, processReadAborted, processSequenceComplete, processSequenceStarted, processThumbnailComplete, processThumbnailPassComplete, processThumbnailPassStarted, processThumbnailProgress, processThumbnailStarted, processThumbnailUpdate, processWarningOccurred, processWarningOccurred, read, read, readAll, readAll, readAsRenderedImage, readerSupportsThumbnails, readRaster, readThumbnail, readTile, readTileRaster, removeAllIIOReadProgressListeners, removeAllIIOReadUpdateListeners, removeAllIIOReadWarningListeners, removeIIOReadProgressListener, removeIIOReadUpdateListener, removeIIOReadWarningListener, reset, setInput, setInput, setLocale

Methods inherited from class Object

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

Methods inherited from interface Localized

getLocale

Field Detail

closeOnReset

protected Closeable closeOnReset

The stream to close on setInput(...), ImageReader.reset() or SpatialImageReader.dispose() method invocation. This stream is typically an input stream or a reader created by getInputStream() or similar methods in subclasses.

This field is never equal to the user-specified input, since the usual ImageReader contract is to not close the user-provided stream. It is set to a non-null value only if a stream has been created from an other user object like File or URL.

See Also:

getInputStream(), TextImageReader.getReader(), close()

Constructor Detail

StreamImageReader

protected StreamImageReader(StreamImageReader.Spi provider)

Constructs a new image reader.

Parameters:

provider - The ImageReaderSpi that is invoking this constructor, or null if none.

Method Detail

setInput

public void setInput(Object input,
                     boolean seekForwardOnly,
                     boolean ignoreMetadata)

Sets the input source to use. Input may be one of the object documented in the class javadoc, namely String, File, URI, URL, URLConnection, InputStream, ImageInputStream or ReadableByteChannel.

If the given input is null, then any currently set input source will be removed.

Overrides:

setInput in class SpatialImageReader

Parameters:

input - The input object to use for future decoding.

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

ignoreMetadata - If true, metadata may be ignored during reads.

See Also:

ImageReader.getInput(), getInputStream()

getStreamLength

protected long getStreamLength()
                        throws IOException

Returns the stream length in bytes, or -1 if unknown. This method checks the input type and invokes one of File.length(), ImageInputStream.length() or URLConnection.getContentLength() method accordingly.

Returns:

The stream length, or -1 is unknown.

Throws:

IOException - if an I/O error occurred.

getInputStream

protected InputStream getInputStream()
                              throws IllegalStateException,
                                     IOException

Returns the input as an input stream object. If the input is already an input stream, it is returned unchanged. Otherwise this method creates a new input stream (usually not buffered) from File, URI, URL, URLConnection, ImageInputStream or ReadableByteChannel inputs.

This method creates a new input stream only when first invoked. All subsequent calls will return the same instance. Consequently, the returned stream should never be closed by the caller. It will be closed automatically (if the stream was not given directly by the user) when setInput(...), reset() or dispose() methods are invoked.

Returns:

ImageReader.getInput() as an InputStream. This input stream is usually not buffered.

Throws:

IllegalStateException - if the input is not set.

IOException - If the input stream can't be created for an other reason.

See Also:

ImageReader.getInput(), getChannel(), TextImageReader.getReader()

getChannel

protected ReadableByteChannel getChannel()
                                  throws IllegalStateException,
                                         IOException

Returns the input as an readable byte channel. If the input is already such channel, it is returned unchanged. Otherwise this method creates a new channel from the value returned by getInputStream().

This method creates a new channel only when first invoked. All subsequent calls will return the same instance. Consequently, the returned channel should never be closed by the caller. It will be closed automatically (if the channel was not given directly by the user) when setInput(...), reset() or dispose() methods are invoked.

Returns:

ImageReader.getInput() as a ReadableByteChannel.

Throws:

IllegalStateException - if the input is not set.

IOException - If the input stream can't be created for an other reason.

Since:

3.07

See Also:

ImageReader.getInput(), getInputStream()

close

protected void close()
              throws IOException

Closes the input stream created by getInputStream(). This method does nothing if the input stream is the input instance given by the user rather than a stream created by this class from a File or URL input.

This method is invoked automatically by setInput(...), reset(), dispose() or finalize() methods and doesn't need to be invoked explicitly. It has protected access only in order to allow overriding by subclasses. Overriding methods shall make sure that super.close() is invoked even if their own code fail.

Overrides:

close in class SpatialImageReader

Throws:

IOException - if an error occurred while closing the stream.

See Also:

closeOnReset

finalize

protected void finalize()
                 throws Throwable

Invokes the close() method when this reader is garbage-collected. Note that this will actually close the stream only if it has been created by this reader, rather than supplied by the user.

Overrides:

finalize in class Object

Throws:

Throwable