uk.ac.starlink.fits

## Interface BasicInput

- All Known Implementing Classes:
    BlockInput, BlockMappedInput, BufferedRandomInput, ByteBufferInput, MultiByteBufferInput, SimpleMappedInput

      public interface BasicInput

  Interface defining the basic data input operations required for the FITS reading classes. All the read operations operate at the current position of the assumed stream and advance the current position past the item they just read. Storage is FITS-like, which, happily, matches ByteBuffer conventions. Random access may or may not be supported.

  This interface has some similarities to `DataInput`, and that interface could have been used instead, but this one is explicitly used for the hand-coded FITS reader implementation to make clear which operations need to be efficient. At present no multi-byte (or multi-other-primitive-type) read operations are included, since it's not clear that these are required in practice for efficient table input, though for (uncommon?) tables that have columns with large array values that might not be true. If that turns out to be an important use case, such methods can be added to this interface, implemented in its implementations, and used in the clients of this interface.

  Instances of this are not expected to be safe for use from multiple threads. Depending on the implementation, ignoring that fact may be a very bad idea indeed.

  Since:
    1 Dec 2014

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Releases resources belonging to this object.
    `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[] buf)` 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.

- - ### Method Detail

    - #### readByte

          byte readByte()
                 throws java.io.IOException

      Reads a byte from the stream. The current position is advanced.
      Returns:
        byte value
      Throws:
        `java.io.IOException`

    - #### readShort

          short readShort()
                   throws java.io.IOException

      Reads a 2-byte integer from the stream. The current position is advanced.
      Returns:
        short value
      Throws:
        `java.io.IOException`

    - #### readInt

          int readInt()
               throws java.io.IOException

      Reads a 4-byte integer from the stream. The current position is advanced.
      Returns:
        int value
      Throws:
        `java.io.IOException`

    - #### readLong

          long readLong()
                 throws java.io.IOException

      Reads an 8-byte integer from the stream. The current position is advanced.
      Returns:
        long value
      Throws:
        `java.io.IOException`

    - #### readFloat

          float readFloat()
                   throws java.io.IOException

      Reads a 4-byte floating point value from the stream. The current position is advanced.
      Returns:
        float value
      Throws:
        `java.io.IOException`

    - #### readDouble

          double readDouble()
                     throws java.io.IOException

      Reads an 8-byte floating point value from the stream. The current position is advanced.
      Returns:
        double value
      Throws:
        `java.io.IOException`

    - #### readBytes

          void readBytes(byte[] buf)
                  throws java.io.IOException

      Reads bytes into an array from the stream. The current position is advanced.
      Parameters:
        `buf` - array into which the bytes are read; the number of bytes read is the length of the array
      Throws:
        `java.io.IOException`

    - #### skip

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

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

    - #### close

          void close()
              throws java.io.IOException

      Releases resources belonging to this object. Attempts to use it after a call to this method result in undefined behaviour.
      Throws:
        `java.io.IOException`

    - #### isRandom

          boolean isRandom()

      Indicates whether this object supports random access. The seek and getOffset methods may only be called if this method returns true.
      Returns:
        true iff random access is supported

    - #### seek

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

      Moves the current position of this stream to a given byte offset (optional operation).
      Throws:
        `java.lang.UnsupportedOperationException` - if not random-access
        `java.io.IOException`

    - #### getOffset

          long getOffset()

      Returns the curent position in this stream (optional operation).
      Throws:
        `java.lang.UnsupportedOperationException` - if not random-access