Class ChannelData
- All Implemented Interfaces:
Markable
- Direct Known Subclasses:
ChannelDataInput
,ChannelDataOutput
ChannelDataInput
and ChannelDataOutput
.
Common properties include a reference to a ByteBuffer
supplied by the user and methods for
querying or modifying the stream position. This class does not define any read or write operations.- Since:
- 0.3
- Version:
- 1.3
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Number of bits needed for storing the bit offset inbitPosition
.private long
The current bit position within the stream.final ByteBuffer
The buffer to use for transferring data between the channel to memory.(package private) long
The channel position where is located thebuffer
value at index 0.final long
The position of the channel when thisChannelData
has been created.final String
A short identifier (typically a filename without path) used for formatting error message.private ChannelData.Mark
The most recent mark, ornull
if none. -
Constructor Summary
ConstructorsConstructorDescriptionChannelData
(String filename, ByteBuffer data) Creates a new instance for a buffer filled with the bytes to use.ChannelData
(String filename, Channel channel, ByteBuffer buffer) Creates a new instance for the given channel and using the given buffer.ChannelData
(ChannelData old) Creates a new instance from the givenChannelData
. -
Method Summary
Modifier and TypeMethodDescription(package private) final void
Sets the bit offset to zero.(package private) void
flushAndSetPosition
(int position) Writes (if applicable) the buffer content up to the given position, then sets the buffer position to the given value.final void
flushBefore
(long position) Discards the initial portion of the stream prior to the indicated position.final int
Returns the current bit offset, as an integer between 0 and 7 inclusive.final long
Returns the earliest position in the stream to which seeking may be performed.long
Returns the current byte position of the stream.final void
mark()
Pushes the current stream position onto a stack of marked positions.protected void
Invoked when an operation between the channel and the buffer transferred no byte.private long
position()
Returns the current byte position of the stream, ignoring overriding by subclasses.(package private) final int
Implementation ofChannelDataInput.readBit()
provided here for performance reasons.final void
reset()
Resets the current stream byte and bit positions from the stack of marked positions.final void
reset
(long position) Moves to the given position in the stream and discards all marks at or after that position.abstract void
seek
(long position) Moves to the given position in the stream, relative to the stream position at construction time.final void
setBitOffset
(int bitOffset) Sets the bit offset to the given value.final void
setStreamPosition
(long position) Sets the current byte position of the stream.final void
Moves the stream position to the next byte boundary.toString()
Returns a string representation of this object for debugging purpose.
-
Field Details
-
BIT_OFFSET_SIZE
private static final int BIT_OFFSET_SIZENumber of bits needed for storing the bit offset inbitPosition
. The following condition must hold:- See Also:
-
filename
A short identifier (typically a filename without path) used for formatting error message. This is often the value given byStorageConnector.getStorageName()
. -
buffer
The buffer to use for transferring data between the channel to memory. -
channelOffset
public final long channelOffsetThe position of the channel when thisChannelData
has been created. This is almost always 0, but we allow other values in case the data to read or write are part of a bigger file.This value is added to the argument given to the
seek(long)
method. Users can ignore this field, unless they want to invokeSeekableByteChannel.position(long)
directly. -
bufferOffset
long bufferOffsetThe channel position where is located thebuffer
value at index 0. This is initially zero and shall be incremented as below:- By
Buffer.position()
every timeByteBuffer.compact()
is invoked. - By
Buffer.limit()
every timeByteBuffer.clear()
is invoked.
- By
-
bitPosition
private long bitPositionThe current bit position within the stream. The 3 lowest bits are the bit offset, and the remaining of thelong
value is the stream position where the bit offset is valid.- See Also:
-
mark
The most recent mark, ornull
if none. This is the tail of a chained list of marks.
-
-
Constructor Details
-
ChannelData
ChannelData(String filename, Channel channel, ByteBuffer buffer) throws IOException Creates a new instance for the given channel and using the given buffer. The channel is not stored by this class - it shall be stored by the subclass.- Parameters:
filename
- a short identifier (typically a filename without path) used for formatting error message.channel
- the channel from where data are read or where to wrote.buffer
- the buffer where to store the data.- Throws:
IOException
- if an error occurred while reading the channel.
-
ChannelData
ChannelData(ChannelData old) Creates a new instance from the givenChannelData
. This constructor is invoked when we need to change the implementation class. The oldChannelData
should not be used anymore after this constructor.- Parameters:
old
- the existing instance from which to takes the channel and buffer.
-
ChannelData
ChannelData(String filename, ByteBuffer data) 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.
-
-
Method Details
-
readBitFromBuffer
final int readBitFromBuffer()Implementation ofChannelDataInput.readBit()
provided here for performance reasons. It is caller responsibility to ensure that thebuffer
contains at least one byte. -
getBitOffset
public final int getBitOffset()Returns the current bit offset, as an integer between 0 and 7 inclusive.According
ImageInputStream
contract, the bit offset shall be reset to 0 by every call to anyread
orwrite
method exceptreadBit()
,readBits(int)
,writeBit(int)
andwriteBits(long, int)
.- Returns:
- the bit offset of the stream.
-
setBitOffset
public final void setBitOffset(int bitOffset) Sets the bit offset to the given value. The given value shall be between 0 inclusive to 8 exclusive.- Parameters:
bitOffset
- the new bit offset of the stream.- Throws:
IllegalArgumentException
- if the given offset is out of range.
-
skipRemainingBits
public final void skipRemainingBits()Moves the stream position to the next byte boundary. If the bit offset is zero, this method does nothing. Otherwise it skips the remaining bits in current byte. -
clearBitOffset
final void clearBitOffset()Sets the bit offset to zero. -
getStreamPosition
public long getStreamPosition()Returns the current byte position of the stream. The returned value is relative to the position that the stream had atChannelData
construction time.- Specified by:
getStreamPosition
in interfaceMarkable
- Returns:
- the position of the stream.
-
position
private long position()Returns the current byte position of the stream, ignoring overriding by subclasses. The returned value is relative to the position that the stream had atChannelData
construction time. -
setStreamPosition
public final void setStreamPosition(long position) Sets the current byte position of the stream. This method does not seeks the stream; this method only modifies the value to be returned bygetStreamPosition()
. This method can be invoked when some external code has performed some work with the channel and wants to inform thisChannelData
about the new position resulting from this work. Notes:- Invoking this method clears the bit offset and the marks.
- This method does not need to be invoked when only the buffer position has changed.
- Parameters:
position
- the new position of the stream.
-
getFlushedPosition
public final long getFlushedPosition()Returns the earliest position in the stream to which seeking may be performed.- Returns:
- the earliest legal position for seeking.
-
flushBefore
Discards the initial portion of the stream prior to the indicated position. Attempting to seek to an offset within the flushed portion of the stream may result in anIndexOutOfBoundsException
.If the
buffer
is read-only, then this method does nothing. Otherwise this method moves the data starting at the given position to the beginning of thebuffer
, thus making more room for new data before the data at the given position is discarded.- Parameters:
position
- the length of the stream prefix that may be flushed.- Throws:
IOException
- if an I/O error occurred.
-
flushAndSetPosition
Writes (if applicable) the buffer content up to the given position, then sets the buffer position to the given value. The buffer limit is unchanged, and the buffer offset is incremented by the given value.- Throws:
IOException
-
seek
Moves to the given position in the stream, relative to the stream position at construction time.- Parameters:
position
- the position where to move.- Throws:
IOException
- if the stream cannot be moved to the given position.
-
mark
public final void mark()Pushes the current stream position onto a stack of marked positions. Note thatChannelData
maintains its own marks - the buffer's mark is left unchanged. -
reset
Resets the current stream byte and bit positions from the stack of marked positions. AnIOException
may be be thrown if the previous marked position lies in the discarded portion of the stream.Departure from Image I/O specification
TheImageInputStream.reset()
contract specifies that if there is no matching mark, then this method shall do nothing. This method throwsIOException
instead; silently ignoring mismatch is considered too dangerous. This is a departure fromImageInputStream
but is consistent withInputStream.reset()
contract.- Specified by:
reset
in interfaceMarkable
- Throws:
IOException
- if this stream cannot move to the last mark position.- See Also:
-
reset
Moves to the given position in the stream and discards all marks at or after that position. If a mark exists at the given position, the bit offset is also restored.- Specified by:
reset
in interfaceMarkable
- Parameters:
position
- position where to seek.- Throws:
IOException
- if this stream cannot move to the specified mark position.
-
onEmptyTransfer
Invoked when an operation between the channel and the buffer transferred no byte. Note that this is unrelated to end-of-file, in which caseReadableByteChannel.read(ByteBuffer)
returns -1. A return value of 0 happen for example if the channel is a socket in non-blocking mode and the socket buffer has not yet transferred new data.The current implementation sleeps an arbitrary number of time before to allow a new try. We do that in order to avoid high CPU consumption when data are expected to take more than a few nanoseconds to arrive.
- Throws:
IOException
- if the implementation chooses to stop the process.
-
toString
Returns a string representation of this object for debugging purpose.
-