Package uk.ac.starlink.fits

## Class BlockInput

- java.lang.Object
- - uk.ac.starlink.fits.BlockInput

- All Implemented Interfaces:
    `BasicInput`
  Direct Known Subclasses:
    `BlockMappedInput`, `MultiByteBufferInput`

      public abstract class BlockInput
      extends java.lang.Object
      implements BasicInput

  Partial random-access BasicInput implementation based on a set of ByteBuffers. These may be obtained eagerly or lazily, as defined by the implementation.
  Since:
    18 Mar 2021
  Author:
    Mark Taylor

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `BlockInput​(int nblock)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract java.nio.ByteBuffer` | `acquireBlock​(int iblock)` | Obtains a buffer corresponding to a named block of the stream.
    `void` | `close()` | Releases resources belonging to this object.
    `int` | `getBlockCount()` | Returns the number of mapped blocks used.
    `abstract long` | `getBlockOffset​(int iblock, int offsetInBlock)` | Returns the offset into this stream corresponding to a given block index and offset into that block.
    `abstract int[]` | `getBlockPos​(long offset)` | Returns the block location of a given byte offset.
    `long` | `getOffset()` | Returns the curent position in this stream (optional operation).
    `boolean` | `isRandom()` | Indicates whether this object supports random access.
    `byte` | `readByte()` | Reads a byte from the stream.
    `void` | `readBytes​(byte[] bbuf)` | Reads bytes into an array from the stream.
    `double` | `readDouble()` | Reads an 8-byte floating point value from the stream.
    `float` | `readFloat()` | Reads a 4-byte floating point value from the stream.
    `int` | `readInt()` | Reads a 4-byte integer from the stream.
    `long` | `readLong()` | Reads an 8-byte integer from the stream.
    `short` | `readShort()` | Reads a 2-byte integer from the stream.
    `void` | `seek​(long offset)` | Moves the current position of this stream to a given byte offset (optional operation).
    `void` | `skip​(long nbyte)` | Skips a given number of bytes forwards through the stream.

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

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

- - ### Constructor Detail

    - #### BlockInput

          protected BlockInput​(int nblock)

      Constructor.
      Parameters:
        `nblock` - number of buffers

  - ### Method Detail

    - #### readByte

          public byte readByte()
                        throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads a byte from the stream. The current position is advanced.
      Specified by:
        `readByte` in interface `BasicInput`
      Returns:
        byte value
      Throws:
        `java.io.IOException`

    - #### readShort

          public short readShort()
                          throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads a 2-byte integer from the stream. The current position is advanced.
      Specified by:
        `readShort` in interface `BasicInput`
      Returns:
        short value
      Throws:
        `java.io.IOException`

    - #### readInt

          public int readInt()
                      throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads a 4-byte integer from the stream. The current position is advanced.
      Specified by:
        `readInt` in interface `BasicInput`
      Returns:
        int value
      Throws:
        `java.io.IOException`

    - #### readLong

          public long readLong()
                        throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads an 8-byte integer from the stream. The current position is advanced.
      Specified by:
        `readLong` in interface `BasicInput`
      Returns:
        long value
      Throws:
        `java.io.IOException`

    - #### readFloat

          public float readFloat()
                          throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads a 4-byte floating point value from the stream. The current position is advanced.
      Specified by:
        `readFloat` in interface `BasicInput`
      Returns:
        float value
      Throws:
        `java.io.IOException`

    - #### readDouble

          public double readDouble()
                            throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads an 8-byte floating point value from the stream. The current position is advanced.
      Specified by:
        `readDouble` in interface `BasicInput`
      Returns:
        double value
      Throws:
        `java.io.IOException`

    - #### readBytes

          public void readBytes​(byte[] bbuf)
                         throws java.io.IOException

      Description copied from interface: `BasicInput`
      Reads bytes into an array from the stream. The current position is advanced.
      Specified by:
        `readBytes` in interface `BasicInput`
      Parameters:
        `bbuf` - array into which the bytes are read; the number of bytes read is the length of the array
      Throws:
        `java.io.IOException`

    - #### close

          public void close()

      Description copied from interface: `BasicInput`
      Releases resources belonging to this object. Attempts to use it after a call to this method result in undefined behaviour.
      Specified by:
        `close` in interface `BasicInput`

    - #### isRandom

          public boolean isRandom()

      Description copied from interface: `BasicInput`
      Indicates whether this object supports random access. The seek and getOffset methods may only be called if this method returns true.
      Specified by:
        `isRandom` in interface `BasicInput`
      Returns:
        true iff random access is supported

    - #### getBlockPos

          public abstract int[] getBlockPos​(long offset)

      Returns the block location of a given byte offset.

      This does the opposite of `getBlockOffset`.

      Parameters:
        `offset` - offset into this input stream
      Returns:
        2-element array giving [blockIndex, offsetInBlock]

    - #### getBlockOffset

          public abstract long getBlockOffset​(int iblock,
                                              int offsetInBlock)

      Returns the offset into this stream corresponding to a given block index and offset into that block.

      This does the opposite of `getBlockPos`.

      Parameters:
        `iblock` - block index
        `offsetInBlock` - offset into that block
      Returns:
        offset into stream

    - #### acquireBlock

          protected abstract java.nio.ByteBuffer acquireBlock​(int iblock)
                                                       throws java.io.IOException

      Obtains a buffer corresponding to a named block of the stream. The buffer's position must be zero. This method is called whenever a buffer is required which is not the same as the most recently used one.
      Parameters:
        `iblock` - block index
      Returns:
        byte buffer for given block, positioned at start
      Throws:
        `java.io.IOException`

    - #### seek

          public void seek​(long offset)
                    throws java.io.IOException

      Description copied from interface: `BasicInput`
      Moves the current position of this stream to a given byte offset (optional operation).
      Specified by:
        `seek` in interface `BasicInput`
      Throws:
        `java.io.IOException`

    - #### getOffset

          public long getOffset()

      Description copied from interface: `BasicInput`
      Returns the curent position in this stream (optional operation).
      Specified by:
        `getOffset` in interface `BasicInput`

    - #### skip

          public void skip​(long nbyte)
                    throws java.io.IOException

      Description copied from interface: `BasicInput`
      Skips a given number of bytes forwards through the stream. An exception is thrown if there are not enough bytes left.
      Specified by:
        `skip` in interface `BasicInput`
      Parameters:
        `nbyte` - number of bytes to skip
      Throws:
        `java.io.IOException`

    - #### getBlockCount

          public int getBlockCount()

      Returns the number of mapped blocks used.
      Returns:
        block count