org.geotoolkit.image.io.stream
Class ChannelImageInputStream

Object
  InputStream
      ChannelImageInputStream

All Implemented Interfaces:

Closeable, DataInput, ImageInputStream

public class ChannelImageInputStream
extends InputStream
implements ImageInputStream

An Image Input Stream using a Readable Byte Channel as the data source. Using this class is similar to using the code below:

import javax.imageio.ImageIO;
import java.nio.channels.Channels;

// Omitting class and method declaration...

ReadableByteChannel channel = ...;
ImageInputStream stream = ImageIO.createImageInputStream(Channels.newInputStream(channel));

except that:

• This class is both an InputStream and an ImageInputStream.
• It delegates most of the work to the underlying ByteBuffer (by contrast, the standard ImageInputStreamImpl performs many work itself, including the byte order handling).
• This class can uses an existing ByteBuffer supplied by the caller.

Since:

3.07

Version:

3.07

Author:

Martin Desruisseaux (Geomatys)

See Also:

FileImageInputStream, ImageInputStreamImpl, ImageIO.createImageInputStream(Object), Channels.newInputStream(ReadableByteChannel)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

protected ByteBuffer	buffer The byte buffer to use for reading bytes from the channel.
protected ReadableByteChannel	channel The channel from which to read bytes.

Constructor Summary

ChannelImageInputStream(ReadableByteChannel channel, ByteBuffer buffer)
Creates a new image input stream using the given channel and buffer.

ChannelImageInputStream(ReadableByteChannel channel, int size)
Creates a new image input stream using the given channel.

Method Summary

void	close() Closes the channel.
void	flush() Discards the initial position of the stream prior to the current stream position.
void	flushBefore(long pos) Discards the initial portion of the stream prior to the indicated postion.
int	getBitOffset() Returns the current bit offset, as an integer between 0 and 7 inclusive.
ByteOrder	getByteOrder() Returns the byte order with which data values will be read from this stream.
long	getFlushedPosition() Returns the earliest position in the stream to which seeking may be performed.
long	getStreamPosition() Returns the current byte position of the stream.
boolean	isCached() Returns true if this ImageInputStream caches data itself in order to allow seeking backwards.
boolean	isCachedFile() Returns true if this ImageInputStream caches data itself in order to allow seeking backwards, and the cache is kept in a temporary file.
boolean	isCachedMemory() Returns true if this ImageInputStream caches data itself in order to allow seeking backwards, and the cache is kept in main memory.
long	length() Returns the length of the stream (in bytes), or -1 if unknown.
void	mark() Pushes the current stream position onto a stack of marked positions.
int	read() Reads a single byte from the stream and returns it as an int between 0 and 255.
int	read(byte[] dest) Reads up to dest.length bytes from the stream, and stores them into dest starting at index 0.
int	read(byte[] dest, int offset, int length) Reads up to length bytes from the stream, and stores them into dest starting at index offset.
int	readBit() Reads a single bit from the stream.
long	readBits(int numBits) Reads many bits from the stream.
boolean	readBoolean() Reads a byte from the stream and returns a true if it is nonzero, false otherwise.
byte	readByte() Reads a byte from the stream.
void	readBytes(IIOByteBuffer dest, int length) Reads up to length bytes from the stream, and modifies the supplied IIOByteBuffer to indicate the byte array, offset, and length where the data may be found.
char	readChar() Reads a character from the stream.
double	readDouble() Reads a double from the stream.
float	readFloat() Reads a float from the stream.
void	readFully(byte[] dest) Reads dest.length bytes from the stream, and stores them into dest starting at index 0.
void	readFully(byte[] dest, int offset, int length) Reads length bytes from the stream, and stores them into dest starting at index offset.
void	readFully(char[] dest, int offset, int length) Reads length characters from the stream, and stores them into dest starting at index offset.
void	readFully(double[] dest, int offset, int length) Reads length doubles from the stream, and stores them into dest starting at index offset.
void	readFully(float[] dest, int offset, int length) Reads length floats from the stream, and stores them into dest starting at index offset.
void	readFully(int[] dest, int offset, int length) Reads length ints from the stream, and stores them into dest starting at index offset.
void	readFully(long[] dest, int offset, int length) Reads length longs from the stream, and stores them into dest starting at index offset.
void	readFully(short[] dest, int offset, int length) Reads length shorts from the stream, and stores them into dest starting at index offset.
int	readInt() Reads an integer from the stream.
String	readLine() Reads the new bytes until the next EOL.
long	readLong() Reads a long from the stream.
short	readShort() Reads a short from the stream.
int	readUnsignedByte() Reads a unsigned byte from the stream.
long	readUnsignedInt() Reads a unsigned integer from the stream.
int	readUnsignedShort() Reads a unsigned short from the stream.
String	readUTF() Reads in a string that has been encoded using a UTF-8 string.
void	reset() Resets the current stream byte and bit positions from the stack of marked positions.
void	seek(long pos) Sets the current stream position to the desired location.
void	setBitOffset(int bitOffset) Sets the bit offset to the given value.
void	setByteOrder(ByteOrder byteOrder) Sets the desired byte order for future reads of data values from this stream.
int	skipBytes(int n) Advances the current stream position by the given amount of bytes.
long	skipBytes(long n) Advances the current stream position by the given amount of bytes.

Methods inherited from class InputStream

available, mark, markSupported, skip

Methods inherited from class Object

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

Field Detail

channel

protected final ReadableByteChannel channel

The channel from which to read bytes. This is the channel given at construction time.

buffer

protected final ByteBuffer buffer

The byte buffer to use for reading bytes from the channel. This is the buffer given at construction time.

Constructor Detail

ChannelImageInputStream

public ChannelImageInputStream(ReadableByteChannel channel,
                               int size)

Creates a new image input stream using the given channel. A default buffer of the given size is created.

Parameters:

channel - The channel to use.

size - The buffer size.

ChannelImageInputStream

public ChannelImageInputStream(ReadableByteChannel channel,
                               ByteBuffer buffer)

Creates a new image input stream using the given channel and buffer. The buffer is assumed to have valid initial content. If not, then the following should be invoked before to give the buffer to this constructor:

buffer.clear().limit(0);

Parameters:

channel - The channel to use.

buffer - The buffer to use.

Method Detail

setByteOrder

public void setByteOrder(ByteOrder byteOrder)

Sets the desired byte order for future reads of data values from this stream. The default value is BIG_ENDIAN.

Specified by:

setByteOrder in interface ImageInputStream

getByteOrder

public ByteOrder getByteOrder()

Returns the byte order with which data values will be read from this stream.

Specified by:

getByteOrder in interface ImageInputStream

length

public long length()
            throws IOException

Returns the length of the stream (in bytes), or -1 if unknown.

Specified by:

length in interface ImageInputStream

Throws:

IOException - If an error occurred while fetching the stream length.

getFlushedPosition

public long getFlushedPosition()

Returns the earliest position in the stream to which seeking may be performed.

Specified by:

getFlushedPosition in interface ImageInputStream

Returns:

the earliest legal position for seeking.

getStreamPosition

public long getStreamPosition()
                       throws IOException

Returns the current byte position of the stream.

Specified by:

getStreamPosition in interface ImageInputStream

Returns:

The position of the stream.

Throws:

IOException - if an I/O error occurs.

getBitOffset

public int getBitOffset()
                 throws IOException

Returns the current bit offset, as an integer between 0 and 7 inclusive. Note that the bit offset is reset to 0 by every call to a read methods except readBit() and readBits(int).

Specified by:

getBitOffset in interface ImageInputStream

Returns:

The bit offset of the stream.

Throws:

IOException - if an I/O error occurs.

setBitOffset

public void setBitOffset(int bitOffset)
                  throws IOException

Sets the bit offset to the given value. Note that the bit offset is implicitly reset to 0 by every call to a read methods except readBit() and readBits(int).

Specified by:

setBitOffset in interface ImageInputStream

Parameters:

bitOffset - The new bit offset of the stream.

Throws:

IOException - if an I/O error occurs.

read

public int read()
         throws IOException

Reads a single byte from the stream and returns it as an int between 0 and 255. If EOF is reached, -1 is returned.

Specified by:

read in interface ImageInputStream

Specified by:

read in class InputStream

Returns:

The value of the next byte in the stream, or -1 on EOF.

Throws:

IOException - If an error occurred while reading.

readBit

public int readBit()
            throws IOException

Reads a single bit from the stream. The bit to be read depends on the current bit offset. Note that the bit offset is reset to 0 by every read methods except readBit() and readBits(int).

Specified by:

readBit in interface ImageInputStream

Returns:

The value of the next bit from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readBits

public long readBits(int numBits)
              throws IOException

Reads many bits from the stream. The first bit to be read depends on the current bit offset. Note that the bit offset is reset to 0 by every read methods except readBit() and readBits(int).

Specified by:

readBits in interface ImageInputStream

Parameters:

numBits - The number of bits to read.

Returns:

The value of the next bits from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readBoolean

public boolean readBoolean()
                    throws IOException

Reads a byte from the stream and returns a true if it is nonzero, false otherwise. The default implementation is as below:

return readByte() != 0;

Specified by:

readBoolean in interface DataInput

Specified by:

readBoolean in interface ImageInputStream

Returns:

The value of the next boolean from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readByte

public byte readByte()
              throws IOException

Reads a byte from the stream. The default implementation ensures that there is at least 1 byte remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.get().

Specified by:

readByte in interface DataInput

Specified by:

readByte in interface ImageInputStream

Returns:

The value of the next byte from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readUnsignedByte

public int readUnsignedByte()
                     throws IOException

Reads a unsigned byte from the stream. The default implementation is as below:

return readByte() & 0xFF;

Specified by:

readUnsignedByte in interface DataInput

Specified by:

readUnsignedByte in interface ImageInputStream

Returns:

The value of the next byte from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readShort

public short readShort()
                throws IOException

Reads a short from the stream. The default implementation ensures that there is at least 2 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getShort().

Specified by:

readShort in interface DataInput

Specified by:

readShort in interface ImageInputStream

Returns:

The value of the next short from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readUnsignedShort

public int readUnsignedShort()
                      throws IOException

Reads a unsigned short from the stream. The default implementation is as below:

return readShort() & 0xFFFF;

Specified by:

readUnsignedShort in interface DataInput

Specified by:

readUnsignedShort in interface ImageInputStream

Returns:

The value of the next short from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readChar

public char readChar()
              throws IOException

Reads a character from the stream. The default implementation ensures that there is at least 2 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getChar().

Specified by:

readChar in interface DataInput

Specified by:

readChar in interface ImageInputStream

Returns:

The value of the next character from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readInt

public int readInt()
            throws IOException

Reads an integer from the stream. The default implementation ensures that there is at least 4 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getInt().

Specified by:

readInt in interface DataInput

Specified by:

readInt in interface ImageInputStream

Returns:

The value of the next integer from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readUnsignedInt

public long readUnsignedInt()
                     throws IOException

Reads a unsigned integer from the stream. The default implementation is as below:

return readInt() & 0xFFFFFFFFL;

Specified by:

readUnsignedInt in interface ImageInputStream

Returns:

The value of the next integer from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readLong

public long readLong()
              throws IOException

Reads a long from the stream. The default implementation ensures that there is at least 8 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getLong().

Specified by:

readLong in interface DataInput

Specified by:

readLong in interface ImageInputStream

Returns:

The value of the next long from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readFloat

public float readFloat()
                throws IOException

Reads a float from the stream. The default implementation ensures that there is at least 4 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getFloat().

Specified by:

readFloat in interface DataInput

Specified by:

readFloat in interface ImageInputStream

Returns:

The value of the next float from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readDouble

public double readDouble()
                  throws IOException

Reads a double from the stream. The default implementation ensures that there is at least 8 bytes remaining in the buffer (reading new bytes from the channel if necessary), then delegates to ByteBuffer.getDouble().

Specified by:

readDouble in interface DataInput

Specified by:

readDouble in interface ImageInputStream

Returns:

The value of the next double from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readLine

public String readLine()
                throws IOException

Reads the new bytes until the next EOL.

Specified by:

readLine in interface DataInput

Specified by:

readLine in interface ImageInputStream

Returns:

The next line, or null if the EOF has been reached.

Throws:

IOException - If an error occurred while reading.

readUTF

public String readUTF()
               throws IOException

Reads in a string that has been encoded using a UTF-8 string.

Specified by:

readUTF in interface DataInput

Specified by:

readUTF in interface ImageInputStream

Returns:

The string reads from the stream.

Throws:

IOException - If an error occurred while reading (including EOF).

readBytes

public void readBytes(IIOByteBuffer dest,
                      int length)
               throws IOException

Reads up to length bytes from the stream, and modifies the supplied IIOByteBuffer to indicate the byte array, offset, and length where the data may be found.

Specified by:

readBytes in interface ImageInputStream

Parameters:

dest - The buffer to be written to.

length - The maximum number of bytes to read.

Throws:

IOException - If an error occurred while reading.

read

public int read(byte[] dest)
         throws IOException

Reads up to dest.length bytes from the stream, and stores them into dest starting at index 0. The default implementation is as below:

return read(dest, 0, dest.length);

Specified by:

read in interface ImageInputStream

Overrides:

read in class InputStream

Parameters:

dest - An array of bytes to be written to.

Returns:

The number of bytes actually read, or -1 on EOF.

Throws:

IOException - If an error occurred while reading.

read

public int read(byte[] dest,
                int offset,
                int length)
         throws IOException

Reads up to length bytes from the stream, and stores them into dest starting at index offset. If no bytes can be read because the end of the stream has been reached, -1 is returned.

Specified by:

read in interface ImageInputStream

Overrides:

read in class InputStream

Parameters:

dest - An array of bytes to be written to.

offset - The starting position withing dest to write.

length - The maximum number of bytes to read.

Returns:

The number of bytes actually read, or -1 on EOF.

Throws:

IOException - If an error occurred while reading.

readFully

public void readFully(byte[] dest)
               throws IOException

Reads dest.length bytes from the stream, and stores them into dest starting at index 0. The default implementation is as below:

return readFully(dest, 0, dest.length);

Specified by:

readFully in interface DataInput

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of bytes to be written to.

Throws:

IOException - If an error occurred while reading.

readFully

public void readFully(byte[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length bytes from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface DataInput

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of bytes to be written to.

offset - The starting position withing dest to write.

length - The number of bytes to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(char[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length characters from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of characters to be written to.

offset - The starting position withing dest to write.

length - The number of characters to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(short[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length shorts from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of shorts to be written to.

offset - The starting position withing dest to write.

length - The number of shorts to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(int[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length ints from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of ints to be written to.

offset - The starting position withing dest to write.

length - The number of ints to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(long[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length longs from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of longs to be written to.

offset - The starting position withing dest to write.

length - The number of longs to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(float[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length floats from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of floats to be written to.

offset - The starting position withing dest to write.

length - The number of floats to read.

Throws:

IOException - If an error occurred while reading (including EOF).

readFully

public void readFully(double[] dest,
                      int offset,
                      int length)
               throws IOException

Reads length doubles from the stream, and stores them into dest starting at index offset.

Specified by:

readFully in interface ImageInputStream

Parameters:

dest - An array of doubles to be written to.

offset - The starting position withing dest to write.

length - The number of shorts to read.

Throws:

IOException - If an error occurred while reading (including EOF).

skipBytes

public int skipBytes(int n)
              throws IOException

Advances the current stream position by the given amount of bytes. The default implementation delegates to:

return (int) skipBytes((long) n);

Specified by:

skipBytes in interface DataInput

Specified by:

skipBytes in interface ImageInputStream

Parameters:

n - The number of bytes to seek forward.

Returns:

The number of bytes skipped.

Throws:

IOException - If an error occurred while skiping.

skipBytes

public long skipBytes(long n)
               throws IOException

Advances the current stream position by the given amount of bytes. The bit offset is reset to 0 by this method.

Specified by:

skipBytes in interface ImageInputStream

Parameters:

n - The number of bytes to seek forward.

Returns:

The number of bytes skipped.

Throws:

IOException - If an error occurred while skiping.

seek

public void seek(long pos)
          throws IOException,
                 IllegalArgumentException

Sets the current stream position to the desired location. The next read will occur at this location. The bit offset is set to 0.

Specified by:

seek in interface ImageInputStream

Parameters:

pos - The new stream position.

Throws:

IOException - If an I/O error occurred.

IllegalArgumentException - If the given position is before the flushed position.

mark

public void mark()

Pushes the current stream position onto a stack of marked positions.

Specified by:

mark in interface ImageInputStream

reset

public void reset()
           throws IOException

Resets the current stream byte and bit positions from the stack of marked positions. An IOException will be thrown if the previous marked position lies in the discarded portion of the stream.

Specified by:

reset in interface ImageInputStream

Overrides:

reset in class InputStream

Throws:

IOException - If an I/O error occurs.

flush

public void flush()
           throws IOException

Discards the initial position of the stream prior to the current stream position. The default implementation is as below:

flushBefore(getStreamPosition());

Specified by:

flush in interface ImageInputStream

Throws:

IOException - If an I/O error occurred.

flushBefore

public void flushBefore(long pos)
                 throws IOException

Discards the initial portion of the stream prior to the indicated postion. Attempting to seek to an offset within the flushed portion of the stream will result in an IndexOutOfBoundsException.

Specified by:

flushBefore in interface ImageInputStream

Parameters:

pos - The length of the stream prefix that may be flushed.

Throws:

IOException - If an I/O error occurred.

isCached

public boolean isCached()

Returns true if this ImageInputStream caches data itself in order to allow seeking backwards. The default implementation returns false.

Specified by:

isCached in interface ImageInputStream

Returns:

true If this ImageInputStream caches data.

See Also:

isCachedMemory(), isCachedFile()

isCachedMemory

public boolean isCachedMemory()

Returns true if this ImageInputStream caches data itself in order to allow seeking backwards, and the cache is kept in main memory. The default implementation returns false.

Specified by:

isCachedMemory in interface ImageInputStream

Returns:

true if this ImageInputStream caches data in main memory.

isCachedFile

public boolean isCachedFile()

Returns true if this ImageInputStream caches data itself in order to allow seeking backwards, and the cache is kept in a temporary file. The default implementation returns false.

Specified by:

isCachedFile in interface ImageInputStream

Returns:

true if this ImageInputStream caches data in a temporary file.

close

public void close()
           throws IOException

Closes the channel.

Specified by:

close in interface Closeable

Specified by:

close in interface ImageInputStream

Overrides:

close in class InputStream

Throws:

IOException - If an error occurred while closing the channel.