SeekableStream
Date: 2016-04-28

org.apache.xmlgraphics.image.codec.util

## Class SeekableStream

- java.lang.Object
- - java.io.InputStream
  - - org.apache.xmlgraphics.image.codec.util.SeekableStream

- All Implemented Interfaces:
    java.io.Closeable, java.io.DataInput, java.lang.AutoCloseable
  Direct Known Subclasses:
    FileCacheSeekableStream, ForwardSeekableStream, ImageInputStreamSeekableStreamAdapter, MemoryCacheSeekableStream, SeekableStreamAdapter

      public abstract class SeekableStream
      extends java.io.InputStream
      implements java.io.DataInput

  An abstract subclass of `java.io.InputStream` that allows seeking within the input, similar to the `RandomAccessFile` class. Additionally, the `DataInput` interface is supported and extended to include support for little-endian representations of fundamental data types.

  In addition to the familiar methods from `InputStream`, the methods `getFilePointer()`, `seek()`, are defined as in the `RandomAccessFile` class. The `canSeekBackwards()` method will return `true` if it is permissible to seek to a position earlier in the stream than the current value of `getFilePointer()`. Some subclasses of `SeekableStream` guarantee the ability to seek backwards while others may not offer this feature in the interest of providing greater efficiency for those users who do not require it.

  The `DataInput` interface is supported as well. This included the `skipBytes()` and `readFully()` methods and a variety of `read` methods for various data types.

  Three classes are provided for the purpose of adapting a standard `InputStream` to the `SeekableStream` interface. `ForwardSeekableStream` does not allows seeking backwards, but is inexpensive to use. `FileCacheSeekableStream` maintains a copy of all of the data read from the input in a temporary file; this file will be discarded automatically when the `FileSeekableStream` is finalized, or when the JVM exits normally. `FileCacheSeekableStream` is intended to be reasonably efficient apart from the unavoidable use of disk space. In circumstances where the creation of a temporary file is not possible, `MemoryCacheSeekableStream` may be used. `MemoryCacheSeekableStream` creates a potentially large in-memory buffer to store the stream data and so should be avoided when possible.

  The `FileSeekableStream` class wraps a `File` or `RandomAccessFile`. It forwards requests to the real underlying file. It performs a limited amount of caching in order to avoid excessive I/O costs.

  The `SegmentedSeekableStream` class performs a different sort of function. It creates a `SeekableStream` from another `SeekableStream` by selecting a series of portions or "segments". Each segment starts at a specified location within the source `SeekableStream` and extends for a specified number of bytes. The `StreamSegmentMapper` interface and `StreamSegment` class may be used to compute the segment positions dynamically.

  A convenience methods, `wrapInputStream` is provided to construct a suitable `SeekableStream` instance whose data is supplied by a given `InputStream`. The caller, by means of the `canSeekBackwards` parameter, determines whether support for seeking backwards is required.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `markPos` Marked position, shared by `ForwardSeekableStream`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SeekableStream()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canSeekBackwards()` Returns `true` if this object supports calls to `seek(pos)` with an offset `pos` smaller than the current offset, as returned by `getFilePointer`.
    `protected void` | `finalize()` Releases any system resources associated with this stream by calling the `close()` method.
    `abstract long` | `getFilePointer()` Returns the current offset in this stream.
    `void` | `mark(int readLimit)` Marks the current file position for later return using the `reset()` method.
    `boolean` | `markSupported()` Returns `true` if marking is supported.
    `abstract int` | `read()` Reads the next byte of data from the input stream.
    `abstract int` | `read(byte[] b, int off, int len)` Reads up to `len` bytes of data from the input stream into an array of bytes.
    `boolean` | `readBoolean()` Reads a `boolean` from this stream.
    `byte` | `readByte()` Reads a signed eight-bit value from this stream.
    `char` | `readChar()` Reads a Unicode character from this stream.
    `char` | `readCharLE()` Reads a Unicode character from this stream in little-endian order.
    `double` | `readDouble()` Reads a `double` from this stream.
    `double` | `readDoubleLE()` Reads a `double` from this stream in little-endian order.
    `float` | `readFloat()` Reads a `float` from this stream.
    `float` | `readFloatLE()` Reads a `float` from this stream in little-endian order.
    `void` | `readFully(byte[] b)` Reads `b.length` bytes from this stream into the byte array, starting at the current stream pointer.
    `void` | `readFully(byte[] b, int off, int len)` Reads exactly `len` bytes from this stream into the byte array, starting at the current stream pointer.
    `int` | `readInt()` Reads a signed 32-bit integer from this stream.
    `int` | `readIntLE()` Reads a signed 32-bit integer from this stream in little-endian order.
    `java.lang.String` | `readLine()` Reads the next line of text from this stream.
    `long` | `readLong()` Reads a signed 64-bit integer from this stream.
    `long` | `readLongLE()` Reads a signed 64-bit integer from this stream in little-endian order.
    `short` | `readShort()` Reads a signed 16-bit number from this stream.
    `short` | `readShortLE()` Reads a signed 16-bit number from this stream in little-endian order.
    `int` | `readUnsignedByte()` Reads an unsigned eight-bit number from this stream.
    `long` | `readUnsignedInt()` Reads an unsigned 32-bit integer from this stream.
    `long` | `readUnsignedIntLE()` Reads an unsigned 32-bit integer from this stream in little-endian order.
    `int` | `readUnsignedShort()` Reads an unsigned 16-bit number from this stream.
    `int` | `readUnsignedShortLE()` Reads an unsigned 16-bit number from this stream in little-endian order.
    `java.lang.String` | `readUTF()` Reads in a string from this stream.
    `void` | `reset()` Returns the file position to its position at the time of the immediately previous call to the `mark()` method.
    `abstract void` | `seek(long pos)` Sets the offset, measured from the beginning of this stream, at which the next read occurs.
    `int` | `skipBytes(int n)` Attempts to skip over `n` bytes of input discarding the skipped bytes.
    `static SeekableStream` | `wrapInputStream(java.io.InputStream is, boolean canSeekBackwards)` Returns a `SeekableStream` that will read from a given `InputStream`, optionally including support for seeking backwards.

    - ### Methods inherited from class java.io.InputStream

      `available, close, read, skip`

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

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

- - ### Field Detail

    - #### markPos

          protected long markPos

      Marked position, shared by `ForwardSeekableStream`

  - ### Constructor Detail

    - #### SeekableStream

          public SeekableStream()

  - ### Method Detail

    - #### wrapInputStream

          public static SeekableStream wrapInputStream(java.io.InputStream is,
                                       boolean canSeekBackwards)

      Returns a `SeekableStream` that will read from a given `InputStream`, optionally including support for seeking backwards. This is a convenience method that avoids the need to instantiate specific subclasses of `SeekableStream` depending on the current security model.
      Parameters:
        `is` - An `InputStream`.
        `canSeekBackwards` - `true` if the ability to seek backwards in the output is required.
      Returns:
        An instance of `SeekableStream`.

    - #### read

          public abstract int read()
                            throws java.io.IOException

      Reads the next byte of data from the input stream. The value byte is returned as an `int` in the range `0` to `255`. If no byte is available because the end of the stream has been reached, the value `-1` is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

      A subclass must provide an implementation of this method.

      Specified by:
        `read` in class `java.io.InputStream`
      Returns:
        the next byte of data, or `-1` if the end of the stream is reached.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### read

          public abstract int read(byte[] b,
                 int off,
                 int len)
                            throws java.io.IOException

      Reads up to `len` bytes of data from the input stream into an array of bytes. An attempt is made to read as many as `len` bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer.

      This method blocks until input data is available, end of stream is detected, or an exception is thrown.

      If `b` is `null`, a `NullPointerException` is thrown.

      If `off` is negative, or `len` is negative, or `off+len` is greater than the length of the array `b`, then an `IndexOutOfBoundsException` is thrown.

      If `len` is zero, then no bytes are read and `0` is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of stream, the value `-1` is returned; otherwise, at least one byte is read and stored into `b`.

      The first byte read is stored into element `b[off]`, the next one into `b[off+1]`, and so on. The number of bytes read is, at most, equal to `len`. Let k be the number of bytes actually read; these bytes will be stored in elements `b[off]` through `b[off+`k`-1]`, leaving elements `b[off+`k`]` through `b[off+len-1]` unaffected.

      In every case, elements `b[0]` through `b[off]` and elements `b[off+len]` through `b[b.length-1]` are unaffected.

      If the first byte cannot be read for any reason other than end of stream, then an `IOException` is thrown. In particular, an `IOException` is thrown if the input stream has been closed.

      A subclass must provide an implementation of this method.

      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `b` - the buffer into which the data is read.
        `off` - the start offset in 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 there is no more data because the end of the stream has been reached.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### mark

          public void mark(int readLimit)

      Marks the current file position for later return using the `reset()` method.
      Overrides:
        `mark` in class `java.io.InputStream`

    - #### reset

          public void reset()
                     throws java.io.IOException

      Returns the file position to its position at the time of the immediately previous call to the `mark()` method.
      Overrides:
        `reset` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### markSupported

          public boolean markSupported()

      Returns `true` if marking is supported. Marking is automatically supported for `SeekableStream` subclasses that support seeking backeards. Subclasses that do not support seeking backwards but do support marking must override this method.
      Overrides:
        `markSupported` in class `java.io.InputStream`

    - #### canSeekBackwards

          public boolean canSeekBackwards()

      Returns `true` if this object supports calls to `seek(pos)` with an offset `pos` smaller than the current offset, as returned by `getFilePointer`.

    - #### getFilePointer

          public abstract long getFilePointer()
                                       throws java.io.IOException

      Returns the current offset in this stream.
      Returns:
        the offset from the beginning of the stream, in bytes, at which the next read occurs.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### seek

          public abstract void seek(long pos)
                             throws java.io.IOException

      Sets the offset, measured from the beginning of this stream, at which the next read occurs.

      If `canSeekBackwards()` returns `false`, then setting `pos` to an offset smaller than the current value of `getFilePointer()` will have no effect.

      Parameters:
        `pos` - the offset position, measured in bytes from the beginning of the stream, at which to set the stream pointer.
      Throws:
        `java.io.IOException` - if `pos` is less than `0` or if an I/O error occurs.

    - #### readFully

          public final void readFully(byte[] b)
                               throws java.io.IOException

      Reads `b.length` bytes from this stream into the byte array, starting at the current stream pointer. This method reads repeatedly from the stream until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.
      Specified by:
        `readFully` in interface `java.io.DataInput`
      Parameters:
        `b` - the buffer into which the data is read.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading all the bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readFully

          public final void readFully(byte[] b,
                       int off,
                       int len)
                               throws java.io.IOException

      Reads exactly `len` bytes from this stream into the byte array, starting at the current stream pointer. This method reads repeatedly from the stream until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.
      Specified by:
        `readFully` in interface `java.io.DataInput`
      Parameters:
        `b` - the buffer into which the data is read.
        `off` - the start offset of the data.
        `len` - the number of bytes to read.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading all the bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### skipBytes

          public int skipBytes(int n)
                        throws java.io.IOException

      Attempts to skip over `n` bytes of input discarding the skipped bytes.

      This method may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of stream before `n` bytes have been skipped is only one possibility. This method never throws an `EOFException`. The actual number of bytes skipped is returned. If `n` is negative, no bytes are skipped.

      Specified by:
        `skipBytes` in interface `java.io.DataInput`
      Parameters:
        `n` - the number of bytes to be skipped.
      Returns:
        the actual number of bytes skipped.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### readBoolean

          public final boolean readBoolean()
                                    throws java.io.IOException

      Reads a `boolean` from this stream. This method reads a single byte from the stream, starting at the current stream pointer. A value of `0` represents `false`. Any other value represents `true`. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.
      Specified by:
        `readBoolean` in interface `java.io.DataInput`
      Returns:
        the `boolean` value read.
      Throws:
        `java.io.EOFException` - if this stream has reached the end.
        `java.io.IOException` - if an I/O error occurs.

    - #### readByte

          public final byte readByte()
                              throws java.io.IOException

      Reads a signed eight-bit value from this stream. This method reads a byte from the stream, starting from the current stream pointer. If the byte read is `b`, where `0 <= b <= 255`, then the result is:

      >          (byte)(b)

      This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readByte` in interface `java.io.DataInput`
      Returns:
        the next byte of this stream as a signed eight-bit `byte`.
      Throws:
        `java.io.EOFException` - if this stream has reached the end.
        `java.io.IOException` - if an I/O error occurs.

    - #### readUnsignedByte

          public final int readUnsignedByte()
                                     throws java.io.IOException

      Reads an unsigned eight-bit number from this stream. This method reads a byte from this stream, starting at the current stream pointer, and returns that byte.

      This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readUnsignedByte` in interface `java.io.DataInput`
      Returns:
        the next byte of this stream, interpreted as an unsigned eight-bit number.
      Throws:
        `java.io.EOFException` - if this stream has reached the end.
        `java.io.IOException` - if an I/O error occurs.

    - #### readShort

          public final short readShort()
                                throws java.io.IOException

      Reads a signed 16-bit number from this stream. The method reads two bytes from this stream, starting at the current stream pointer. If the two bytes read, in order, are `b1` and `b2`, where each of the two values is between `0` and `255`, inclusive, then the result is equal to:

      >          (short)((b1 << 8) | b2)

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readShort` in interface `java.io.DataInput`
      Returns:
        the next two bytes of this stream, interpreted as a signed 16-bit number.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readShortLE

          public final short readShortLE()
                                  throws java.io.IOException

      Reads a signed 16-bit number from this stream in little-endian order. The method reads two bytes from this stream, starting at the current stream pointer. If the two bytes read, in order, are `b1` and `b2`, where each of the two values is between `0` and `255`, inclusive, then the result is equal to:

      >          (short)((b2 << 8) | b1)

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next two bytes of this stream, interpreted as a signed 16-bit number.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readUnsignedShort

          public final int readUnsignedShort()
                                      throws java.io.IOException

      Reads an unsigned 16-bit number from this stream. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1` and `b2`, where `0 <= b1, b2 <= 255`, then the result is equal to:

      >          (b1 << 8) | b2

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readUnsignedShort` in interface `java.io.DataInput`
      Returns:
        the next two bytes of this stream, interpreted as an unsigned 16-bit integer.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readUnsignedShortLE

          public final int readUnsignedShortLE()
                                        throws java.io.IOException

      Reads an unsigned 16-bit number from this stream in little-endian order. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1` and `b2`, where `0 <= b1, b2 <= 255`, then the result is equal to:

      >          (b2 << 8) | b1

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next two bytes of this stream, interpreted as an unsigned 16-bit integer.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readChar

          public final char readChar()
                              throws java.io.IOException

      Reads a Unicode character from this stream. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1` and `b2`, where `0 <= b1, b2 <= 255`, then the result is equal to:

      >          (char)((b1 << 8) | b2)

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readChar` in interface `java.io.DataInput`
      Returns:
        the next two bytes of this stream as a Unicode character.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readCharLE

          public final char readCharLE()
                                throws java.io.IOException

      Reads a Unicode character from this stream in little-endian order. This method reads two bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1` and `b2`, where `0 <= b1, b2 <= 255`, then the result is equal to:

      >          (char)((b2 << 8) | b1)

      This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next two bytes of this stream as a Unicode character.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading two bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readInt

          public final int readInt()
                            throws java.io.IOException

      Reads a signed 32-bit integer from this stream. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, and `b4`, where `0 <= b1, b2, b3, b4 <= 255`, then the result is equal to:

      >          (b1 << 24) | (b2 << 16) + (b3 << 8) + b4

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readInt` in interface `java.io.DataInput`
      Returns:
        the next four bytes of this stream, interpreted as an `int`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readIntLE

          public final int readIntLE()
                              throws java.io.IOException

      Reads a signed 32-bit integer from this stream in little-endian order. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, and `b4`, where `0 <= b1, b2, b3, b4 <= 255`, then the result is equal to:

      >          (b4 << 24) | (b3 << 16) + (b2 << 8) + b1

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next four bytes of this stream, interpreted as an `int`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readUnsignedInt

          public final long readUnsignedInt()
                                     throws java.io.IOException

      Reads an unsigned 32-bit integer from this stream. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, and `b4`, where `0 <= b1, b2, b3, b4 <= 255`, then the result is equal to:

      >          (b1 << 24) | (b2 << 16) + (b3 << 8) + b4

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next four bytes of this stream, interpreted as a `long`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readUnsignedIntLE

          public final long readUnsignedIntLE()
                                       throws java.io.IOException

      Reads an unsigned 32-bit integer from this stream in little-endian order. This method reads 4 bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, and `b4`, where `0 <= b1, b2, b3, b4 <= 255`, then the result is equal to:

      >          (b4 << 24) | (b3 << 16) + (b2 << 8) + b1

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next four bytes of this stream, interpreted as a `long`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readLong

          public final long readLong()
                              throws java.io.IOException

      Reads a signed 64-bit integer from this stream. This method reads eight bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, `b4`, `b5`, `b6`, `b7`, and `b8,` where:

      >          0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,

      then the result is equal to:

      >          ((long)b1 << 56) + ((long)b2 << 48)
      >          + ((long)b3 << 40) + ((long)b4 << 32)
      >          + ((long)b5 << 24) + ((long)b6 << 16)
      >          + ((long)b7 << 8) + b8

      This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readLong` in interface `java.io.DataInput`
      Returns:
        the next eight bytes of this stream, interpreted as a `long`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading eight bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readLongLE

          public final long readLongLE()
                                throws java.io.IOException

      Reads a signed 64-bit integer from this stream in little-endian order. This method reads eight bytes from the stream, starting at the current stream pointer. If the bytes read, in order, are `b1`, `b2`, `b3`, `b4`, `b5`, `b6`, `b7`, and `b8,` where:

      >          0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,

      then the result is equal to:

      >          ((long)b1 << 56) + ((long)b2 << 48)
      >          + ((long)b3 << 40) + ((long)b4 << 32)
      >          + ((long)b5 << 24) + ((long)b6 << 16)
      >          + ((long)b7 << 8) + b8

      This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next eight bytes of this stream, interpreted as a `long`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading eight bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readFloat

          public final float readFloat()
                                throws java.io.IOException

      Reads a `float` from this stream. This method reads an `int` value, starting at the current stream pointer, as if by the `readInt` method and then converts that `int` to a `float` using the `intBitsToFloat` method in class `Float`.

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readFloat` in interface `java.io.DataInput`
      Returns:
        the next four bytes of this stream, interpreted as a `float`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readFloatLE

          public final float readFloatLE()
                                  throws java.io.IOException

      Reads a `float` from this stream in little-endian order. This method reads an `int` value, starting at the current stream pointer, as if by the `readInt` method and then converts that `int` to a `float` using the `intBitsToFloat` method in class `Float`.

      This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next four bytes of this stream, interpreted as a `float`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading four bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readDouble

          public final double readDouble()
                                  throws java.io.IOException

      Reads a `double` from this stream. This method reads a `long` value, starting at the current stream pointer, as if by the `readLong` method and then converts that `long` to a `double` using the `longBitsToDouble` method in class `Double`.

      This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readDouble` in interface `java.io.DataInput`
      Returns:
        the next eight bytes of this stream, interpreted as a `double`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading eight bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readDoubleLE

          public final double readDoubleLE()
                                    throws java.io.IOException

      Reads a `double` from this stream in little-endian order. This method reads a `long` value, starting at the current stream pointer, as if by the `readLong` method and then converts that `long` to a `double` using the `longBitsToDouble` method in class `Double`.

      This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

      Returns:
        the next eight bytes of this stream, interpreted as a `double`.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading eight bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readLine

          public final java.lang.String readLine()
                                          throws java.io.IOException

      Reads the next line of text from this stream. This method successively reads bytes from the stream, starting at the current stream pointer, until it reaches a line terminator or the end of the stream. Each byte is converted into a character by taking the byte's value for the lower eight bits of the character and setting the high eight bits of the character to zero. This method does not, therefore, support the full Unicode character set.

      A line of text is terminated by a carriage-return character (`'\r'`), a newline character (`'\n'`), a carriage-return character immediately followed by a newline character, or the end of the stream. Line-terminating characters are discarded and are not included as part of the string returned.

      This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is reached, or an exception is thrown.

      Specified by:
        `readLine` in interface `java.io.DataInput`
      Returns:
        the next line of text from this stream, or null if end of stream is encountered before even one byte is read.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### readUTF

          public final java.lang.String readUTF()
                                         throws java.io.IOException

      Reads in a string from this stream. The string has been encoded using a modified UTF-8 format.

      The first two bytes are read, starting from the current stream pointer, as if by `readUnsignedShort`. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

      This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

      Specified by:
        `readUTF` in interface `java.io.DataInput`
      Returns:
        a Unicode string.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading all the bytes.
        `java.io.IOException` - if an I/O error occurs.
        `java.io.UTFDataFormatException` - if the bytes do not represent valid UTF-8 encoding of a Unicode string.

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Releases any system resources associated with this stream by calling the `close()` method.
      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`