Interface Markable
- All Known Implementing Classes:
ChannelData
,ChannelDataInput
,ChannelDataOutput
,ChannelImageInputStream
,ChannelImageOutputStream
,InputStreamAdapter
,OutputStreamAdapter
public interface Markable
Stream reader or writer capable to mark its current position and reset to that position later.
The stream shall support nested marks.
Use case:
this interface can be used when we need to move to a previously marked position, but we do not know how many nested
mark()
method calls may have been performed (typically because the stream has been used by arbitrary code).
We can compare getStreamPosition()
value after reset()
method calls with the expected position.
Design note:
an alternative could be to support the
seek(long)
method. But using marks instead allows the stream
to invalidate the marks if needed (for example when ChannelData.setStreamPosition(long)
is invoked).
- Since:
- 0.8
- Version:
- 1.2
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionlong
Returns the current byte position of the stream.void
mark()
Pushes the current stream position onto a stack of marked positions.void
reset()
Resets the current stream byte and bit positions from the stack of marked positions.void
reset
(long mark) Resets the stream position to the mark at the given position.
-
Method Details
-
getStreamPosition
Returns the current byte position of the stream.- Returns:
- the position of the stream.
- Throws:
IOException
- if the position cannot be obtained.
-
mark
Pushes the current stream position onto a stack of marked positions. A subsequent call to thereset()
method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. Calls tomark()
andreset()
can be nested arbitrarily.- Throws:
IOException
- if this stream cannot mark the current position.- See Also:
-
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.Behavior if there is no mark
Calls toreset()
without a corresponding call tomark()
have different behavior depending on which interface defines the mark/reset methods:InputStream.reset()
specifies that we might move to the file beginning or throw an exception.ImageInputStream.reset()
specifies that we shall do nothing. For thisMarkable
interface we recommend to throw anIOException
.- Throws:
IOException
- if this stream cannot move to the last mark position.- See Also:
-
reset
Resets the stream position to the mark at the given position. Invoking this method is similar to invokingseek(mark)
except that it may work on non-seekable stream if a mark has been set on that position.- Parameters:
mark
- position where to seek. Should be a position where a mark has been created.- Throws:
IOException
- if this stream cannot move to the specified mark position.
-