Class ChannelImageInputStream
java.lang.Object
org.apache.sis.internal.storage.io.ChannelData
org.apache.sis.internal.storage.io.ChannelDataInput
org.apache.sis.internal.storage.io.ChannelImageInputStream
- All Implemented Interfaces:
Closeable
,DataInput
,AutoCloseable
,ImageInputStream
,Markable
Adds the missing methods in
ChannelDataInput
for implementing the ImageInputStream
interface.
The JDK approach for creating an image input stream from a channel would be as below:
However, the standard ImageInputStreamImpl
implementation performs many work by itself,
including supporting various byte order, which could be more efficiently done by NIO.
Furthermore, this class allows us to reuse an existing buffer (especially direct buffer, which are costly to create)
and allow subclasses to store additional information, for example the file path.
This class is used when compatibility with ImageReader
is needed.
- Since:
- 0.3
- Version:
- 1.3
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.internal.storage.io.ChannelDataInput
ChannelDataInput.ArrayReader, ChannelDataInput.BytesReader, ChannelDataInput.CharsReader, ChannelDataInput.DoublesReader, ChannelDataInput.FloatsReader, ChannelDataInput.IntsReader, ChannelDataInput.LongsReader, ChannelDataInput.ShortsReader
-
Field Summary
Fields inherited from class org.apache.sis.internal.storage.io.ChannelDataInput
channel
Fields inherited from class org.apache.sis.internal.storage.io.ChannelData
buffer, bufferOffset, channelOffset, filename
-
Constructor Summary
ConstructorsConstructorDescriptionChannelImageInputStream
(String filename, ByteBuffer data) Creates a new instance for a buffer filled with the bytes to use.ChannelImageInputStream
(String filename, ReadableByteChannel channel, ByteBuffer buffer, boolean filled) Creates a new input stream for the given channel and using the given buffer.Creates a new input stream from the givenChannelDataInput
. -
Method Summary
Modifier and TypeMethodDescriptionfinal void
close()
Closes the ChannelDataInput.channel.final void
flush()
Discards the initial position of the stream prior to the current stream position.final ByteOrder
Returns the byte order with which data values will be read from this stream.final boolean
isCached()
Synonymous ofisCachedMemory()
since the caching behavior of this class is uniquely determined by the policy that we choose forisCachedMemory()
.final boolean
Returnsfalse
since thisImageInputStream
does not cache data in a temporary file.final boolean
Returnsfalse
since thisImageInputStream
does not cache data itself in order to allow seeking backwards.final int
read()
Returns the next byte from the stream as an unsigned integer between 0 and 255, or -1 if we reached the end of stream.final int
read
(byte[] dest) Reads up todest.length
bytes from the stream, and stores them intodest
starting at index 0.final int
read
(byte[] dest, int offset, int length) Reads up tolength
bytes from the stream, and stores them intodest
starting at indexoffset
.final boolean
Reads a byte from the stream and returns atrue
if it is nonzero,false
otherwise.final void
readBytes
(IIOByteBuffer dest, int length) Reads up tolength
bytes from the stream, and modifies the suppliedIIOByteBuffer
to indicate the byte array, offset, and length where the data may be found.final String
readLine()
Reads the new bytes until the next EOL.final String
readUTF()
Reads in a string that has been encoded using a UTF-8 string.final void
setByteOrder
(ByteOrder byteOrder) Sets the desired byte order for future reads of data values from this stream.final int
skipBytes
(int n) Skips over n bytes of data from the input stream.final long
skipBytes
(long n) Advances the current stream position by the given amount of bytes.Methods inherited from class org.apache.sis.internal.storage.io.ChannelDataInput
ensureBufferContains, hasRemaining, length, prefetch, pushBack, readBit, readBits, readByte, readBytes, readChar, readChars, readDouble, readDoubles, readFloat, readFloats, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readInts, readLong, readLongs, readShort, readShorts, readString, readUnsignedByte, readUnsignedInt, readUnsignedShort, rewind, seek
Methods inherited from class org.apache.sis.internal.storage.io.ChannelData
clearBitOffset, flushAndSetPosition, flushBefore, getBitOffset, getFlushedPosition, getStreamPosition, mark, onEmptyTransfer, readBitFromBuffer, reset, reset, setBitOffset, setStreamPosition, skipRemainingBits, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.imageio.stream.ImageInputStream
flushBefore, getBitOffset, getFlushedPosition, getStreamPosition, length, mark, readBit, readBits, readByte, readChar, readDouble, readFloat, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedShort, reset, seek, setBitOffset
-
Constructor Details
-
ChannelImageInputStream
public ChannelImageInputStream(String filename, ReadableByteChannel channel, ByteBuffer buffer, boolean filled) throws IOException Creates a new input stream for the given channel and using the given buffer.- Parameters:
filename
- a file identifier used only for formatting error message.channel
- the channel from where data are read.buffer
- the buffer where to copy the data.filled
-true
if the buffer already contains data, orfalse
if it needs to be initially filled with some content read from the channel.- Throws:
IOException
- if an error occurred while reading the channel.
-
ChannelImageInputStream
Creates a new instance for a buffer filled with the bytes to use. This constructor uses an independent, read-only view of the given buffer. No reference to the given buffer will be retained.- Parameters:
filename
- a short identifier (typically a filename without path) used for formatting error message.data
- the buffer filled with all bytes to read.
-
ChannelImageInputStream
Creates a new input stream from the givenChannelDataInput
. This constructor is invoked when we need to change the implementation class fromChannelDataInput
toChannelImageInputStream
. The old input should not be used anymore after this constructor has been invoked.- Parameters:
input
- the existing instance from which to takes the channel and buffer.
-
-
Method Details
-
setByteOrder
Sets the desired byte order for future reads of data values from this stream. The default value isByteOrder.BIG_ENDIAN
.- Specified by:
setByteOrder
in interfaceImageInputStream
- Parameters:
byteOrder
- the new buffer byte order.
-
getByteOrder
Returns the byte order with which data values will be read from this stream. This is the buffer byte order.- Specified by:
getByteOrder
in interfaceImageInputStream
- Returns:
- the buffer byte order.
-
readBoolean
Reads a byte from the stream and returns atrue
if it is nonzero,false
otherwise. The implementation is as below:- Specified by:
readBoolean
in interfaceDataInput
- Specified by:
readBoolean
in interfaceImageInputStream
- Returns:
- the value of the next boolean from the stream.
- Throws:
IOException
- if an error (including EOF) occurred while reading the stream.
-
readUTF
Reads in a string that has been encoded using a UTF-8 string.- Specified by:
readUTF
in interfaceDataInput
- Specified by:
readUTF
in interfaceImageInputStream
- Returns:
- the string reads from the stream.
- Throws:
IOException
- if an error (including EOF) occurred while reading the stream.
-
readLine
Reads the new bytes until the next EOL. This method can read only US-ASCII strings. This method is provided for compliance with theDataInput
interface, but is generally not recommended.- Specified by:
readLine
in interfaceDataInput
- Specified by:
readLine
in interfaceImageInputStream
- Returns:
- the next line, or
null
if the EOF has been reached. - Throws:
IOException
- if an error occurred while reading.
-
read
Returns the next byte from the stream as an unsigned integer between 0 and 255, or -1 if we reached the end of stream.- Specified by:
read
in interfaceImageInputStream
- Returns:
- the next byte as an unsigned integer, or -1 on end of stream.
- Throws:
IOException
- if an error occurred while reading the stream.
-
read
Reads up todest.length
bytes from the stream, and stores them intodest
starting at index 0. The default implementation is as below:- Specified by:
read
in interfaceImageInputStream
- 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
Reads up tolength
bytes from the stream, and stores them intodest
starting at indexoffset
. If no bytes can be read because the end of the stream has been reached, -1 is returned.- Specified by:
read
in interfaceImageInputStream
- Parameters:
dest
- an array of bytes to be written to.offset
- the starting position withindest
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.
-
readBytes
Reads up tolength
bytes from the stream, and modifies the suppliedIIOByteBuffer
to indicate the byte array, offset, and length where the data may be found.- Specified by:
readBytes
in interfaceImageInputStream
- Parameters:
dest
- the buffer to be written to.length
- the maximum number of bytes to read.- Throws:
IOException
- if an error occurred while reading.
-
skipBytes
Skips over n bytes of data from the input stream. A negative value move backward in the input stream.Design note
A previous version was skipping no more bytes than the buffer capacity. But experience shows that variousImageReader
implementations outside Apache SIS expect that we skip exactly the specified amount of bytes and ignore the returned value.- Specified by:
skipBytes
in interfaceDataInput
- Specified by:
skipBytes
in interfaceImageInputStream
- Parameters:
n
- maximal number of bytes to skip. Can be negative.- Returns:
- number of bytes actually skipped.
- Throws:
IOException
- if an error occurred while reading.
-
skipBytes
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 interfaceImageInputStream
- Parameters:
n
- the number of bytes to seek forward.- Returns:
- the number of bytes skipped.
- Throws:
IOException
- if an error occurred while skipping.
-
flush
Discards the initial position of the stream prior to the current stream position. The implementation is as below:- Specified by:
flush
in interfaceImageInputStream
- Throws:
IOException
- if an I/O error occurred.
-
isCached
public final boolean isCached()Synonymous ofisCachedMemory()
since the caching behavior of this class is uniquely determined by the policy that we choose forisCachedMemory()
. This class never creates temporary files.- Specified by:
isCached
in interfaceImageInputStream
- See Also:
-
isCachedMemory
public final boolean isCachedMemory()Returnsfalse
since thisImageInputStream
does not cache data itself in order to allow seeking backwards. Actually, we could consider theChannelData.buffer
as a cache in main memory. But this buffer has a maximal capacity, which would be a violation ofImageInputStream
contract.- Specified by:
isCachedMemory
in interfaceImageInputStream
- Returns:
false
since thisImageInputStream
does not caches data in main memory (ignoring theChannelData.buffer
).
-
isCachedFile
public final boolean isCachedFile()Returnsfalse
since thisImageInputStream
does not cache data in a temporary file.- Specified by:
isCachedFile
in interfaceImageInputStream
- Returns:
false
since thisImageInputStream
does not cache data in a temporary file.
-
close
Closes the ChannelDataInput.channel. If the channel is backed by anInputStream
, that stream will be closed too.Departure from Image I/O standard implementation
Java Image I/O wrappers around input/output streams do not close the underlying stream (see for exampleFileCacheImageInputStream.close()
specification). But Apache SIS needs the underlying stream to be closed because we do not keep reference to the original input stream. Note that channels created byChannels.newChannel(java.io.InputStream)
close the stream, which is the desired behavior for this method.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceImageInputStream
- Throws:
IOException
- if an error occurred while closing the channel.
-