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 Type
    Method
    Description
    long
    Returns the current byte position of the stream.
    void
    Pushes the current stream position onto a stack of marked positions.
    void
    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

      long getStreamPosition() throws IOException
      Returns the current byte position of the stream.
      Returns:
      the position of the stream.
      Throws:
      IOException - if the position cannot be obtained.
    • mark

      void mark() throws IOException
      Pushes the current stream position onto a stack of marked positions. A subsequent call to the reset() method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. Calls to mark() and reset() can be nested arbitrarily.
      Throws:
      IOException - if this stream cannot mark the current position.
      See Also:
    • reset

      void reset() throws IOException
      Resets the current stream byte and bit positions from the stack of marked positions. An IOException may be be thrown if the previous marked position lies in the discarded portion of the stream.

      Behavior if there is no mark

      Calls to reset() without a corresponding call to mark() 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 this Markable interface we recommend to throw an IOException.
      Throws:
      IOException - if this stream cannot move to the last mark position.
      See Also:
    • reset

      void reset(long mark) throws IOException
      Resets the stream position to the mark at the given position. Invoking this method is similar to invoking seek(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.