org.apache.flume.serialization

## Class ResettableFileInputStream

- java.lang.Object
- - org.apache.flume.serialization.ResettableInputStream
  - - org.apache.flume.serialization.ResettableFileInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable, LengthMeasurable, RemoteMarkable, Resettable, Seekable

      @InterfaceAudience.Private
      @InterfaceStability.Evolving
      public class ResettableFileInputStream
      extends ResettableInputStream
      implements RemoteMarkable, LengthMeasurable

  This class makes the following assumptions:

  1. The underlying file is not changing while it is being read

  The ability to `reset()` is dependent on the underlying `PositionTracker` instance's durability semantics.

  A note on surrogate pairs:

  The logic for decoding surrogate pairs is as follows: If no character has been decoded by a "normal" pass, and the buffer still has remaining bytes, then an attempt is made to read 2 characters in one pass. If it succeeds, then the first char (high surrogate) is returned; the second char (low surrogate) is recorded internally, and is returned at the next call to `readChar()`. If it fails, then it is assumed that EOF has been reached.

  Impacts on position, mark and reset: when a surrogate pair is decoded, the position is incremented by the amount of bytes taken to decode the entire pair (usually, 4). This is the most reasonable choice since it would not be advisable to reset a stream to a position pointing to the second char in a pair of surrogates: such a dangling surrogate would not be properly decoded without its counterpart.

  Thus the behaviour of mark and reset is as follows:

  1. If `mark()` is called after a high surrogate pair has been returned by `readChar()`, the marked position will be that of the character following the low surrogate, not that of the low surrogate itself.
  2. If `reset()` is called after a high surrogate pair has been returned by `readChar()`, the low surrogate is always returned by the next call to `readChar()`, before the stream is actually reset to the last marked position.

  This ensures that no dangling high surrogate could ever be read as long as the same instance is used to read the whole pair. However, if `reset()` is called after a high surrogate pair has been returned by `readChar()`, and a new instance of ResettableFileInputStream is used to resume reading, then the low surrogate char will be lost, resulting in a corrupted sequence of characters (dangling high surrogate). This situation is hopefully extremely unlikely to happen in real life.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_BUF_SIZE`
    `static int` | `MIN_BUF_SIZE` The minimum acceptable buffer size to store bytes read from the underlying file.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResettableFileInputStream(File file, PositionTracker tracker)`
    `ResettableFileInputStream(File file, PositionTracker tracker, int bufSize, Charset charset, DecodeErrorPolicy decodeErrorPolicy)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `long` | `getMarkPosition()` Return the saved mark position without moving the mark pointer.
    `long` | `length()` returns the total length of the stream or file
    `void` | `mark()` Marks the current position in this input stream.
    `void` | `markPosition(long position)` Indicate that the specified position should be returned to in the case of `Resettable.reset()` being called.
    `int` | `read()` Read a single byte of data from the stream.
    `int` | `read(byte[] b, int off, int len)` Read multiple bytes of data from the stream.
    `int` | `readChar()` Read a single character.
    `void` | `reset()` Reset stream position to that set by `ResettableInputStream.mark()`
    `void` | `seek(long newPos)` Seek to the specified byte position in the stream.
    `long` | `tell()` Tell the current byte position.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_BUF_SIZE

          public static final int DEFAULT_BUF_SIZE

      See Also:
        Constant Field Values

    - #### MIN_BUF_SIZE

          public static final int MIN_BUF_SIZE

      The minimum acceptable buffer size to store bytes read from the underlying file. A minimum size of 8 ensures that the buffer always has enough space to contain multi-byte characters, including special sequences such as surrogate pairs, Byte Order Marks, etc.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ResettableFileInputStream

          public ResettableFileInputStream(File file,
                                   PositionTracker tracker)
                                    throws IOException

      Parameters:
        `file` - File to read
        `tracker` - PositionTracker implementation to make offset position durable
      Throws:
        `FileNotFoundException` - If the file to read does not exist
        `IOException` - If the position reported by the tracker cannot be sought

    - #### ResettableFileInputStream

          public ResettableFileInputStream(File file,
                                   PositionTracker tracker,
                                   int bufSize,
                                   Charset charset,
                                   DecodeErrorPolicy decodeErrorPolicy)
                                    throws IOException

      Parameters:
        `file` - File to read
        `tracker` - PositionTracker implementation to make offset position durable
        `bufSize` - Size of the underlying buffer used for input. If lesser than `MIN_BUF_SIZE`, a buffer of length `MIN_BUF_SIZE` will be created instead.
        `charset` - Character set used for decoding text, as necessary
        `decodeErrorPolicy` - A `DecodeErrorPolicy` instance to determine how the decoder should behave in case of malformed input and/or unmappable character.
      Throws:
        `FileNotFoundException` - If the file to read does not exist
        `IOException` - If the position reported by the tracker cannot be sought

  - ### Method Detail

    - #### read

          public int read()
                   throws IOException

      Description copied from class: `ResettableInputStream`
      Read a single byte of data from the stream.
      Specified by:
        `read` in class `ResettableInputStream`
      Returns:
        the next byte of data, or `-1` if the end of the stream has been reached.
      Throws:
        `IOException`

    - #### read

          public int read(byte[] b,
                 int off,
                 int len)
                   throws IOException

      Description copied from class: `ResettableInputStream`
      Read multiple bytes of data from the stream.
      Specified by:
        `read` in class `ResettableInputStream`
      Parameters:
        `b` - the buffer into which the data is read.
        `off` - Offset into the array `b` at which the data is written.
        `len` - the maximum number of bytes to read.
      Returns:
        the total number of bytes read into the buffer, or `-1` if the end of the stream has been reached.
      Throws:
        `IOException`

    - #### readChar

          public int readChar()
                       throws IOException

      Description copied from class: `ResettableInputStream`

      Read a single character.

      Note that this may lead to returning only one character in a 2-char surrogate pair sequence. When this happens, the underlying implementation should never persist a mark between two chars of a two-char surrogate pair sequence.

      Specified by:
        `readChar` in class `ResettableInputStream`
      Returns:
        The character read, as an integer in the range 0 to 65535 (0x00-0xffff), or -1 if the end of the stream has been reached
      Throws:
        `IOException`

    - #### mark

          public void mark()
                    throws IOException

      Description copied from class: `ResettableInputStream`
      Marks the current position in this input stream. A subsequent call to the `reset` method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

      Marking a closed stream should not have any effect on the stream.

      Specified by:
        `mark` in interface `Resettable`
      Specified by:
        `mark` in class `ResettableInputStream`
      Throws:
        `IOException` - If there is an error while setting the mark position.
      See Also:
        `InputStream.mark(int)`, `InputStream.reset()`

    - #### markPosition

          public void markPosition(long position)
                            throws IOException

      Description copied from interface: `RemoteMarkable`
      Indicate that the specified position should be returned to in the case of `Resettable.reset()` being called.
      Specified by:
        `markPosition` in interface `RemoteMarkable`
      Throws:
        `IOException`

    - #### getMarkPosition

          public long getMarkPosition()
                               throws IOException

      Description copied from interface: `RemoteMarkable`
      Return the saved mark position without moving the mark pointer.
      Specified by:
        `getMarkPosition` in interface `RemoteMarkable`
      Throws:
        `IOException`

    - #### reset

          public void reset()
                     throws IOException

      Description copied from class: `ResettableInputStream`
      Reset stream position to that set by `ResettableInputStream.mark()`
      Specified by:
        `reset` in interface `Resettable`
      Specified by:
        `reset` in class `ResettableInputStream`
      Throws:
        `IOException`

    - #### length

          public long length()
                      throws IOException

      Description copied from interface: `LengthMeasurable`
      returns the total length of the stream or file
      Specified by:
        `length` in interface `LengthMeasurable`
      Throws:
        `IOException`

    - #### tell

          public long tell()
                    throws IOException

      Description copied from class: `ResettableInputStream`
      Tell the current byte position.
      Specified by:
        `tell` in interface `Seekable`
      Specified by:
        `tell` in class `ResettableInputStream`
      Returns:
        the current absolute byte position in the stream
      Throws:
        `IOException`

    - #### seek

          public void seek(long newPos)
                    throws IOException

      Description copied from class: `ResettableInputStream`
      Seek to the specified byte position in the stream.
      Specified by:
        `seek` in interface `Seekable`
      Specified by:
        `seek` in class `ResettableInputStream`
      Parameters:
        `newPos` - Absolute byte offset to seek to
      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in class `ResettableInputStream`
      Throws:
        `IOException`

Copyright © 2009-2016 Apache Software Foundation. All Rights Reserved.