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 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

Modifier and Type
Method
Description
`protected abstract 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 Details

### BlockInput

protected BlockInput(int nblock)
Constructor.

Parameters:
  `nblock` - number of buffers

## Method Details

### readByte

public byte readByte() throws 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:
  `IOException`

### readShort

public short readShort() throws 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:
  `IOException`

### readInt

public int readInt() throws 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:
  `IOException`

### readLong

public long readLong() throws 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:
  `IOException`

### readFloat

public float readFloat() throws 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:
  `IOException`

### readDouble

public double readDouble() throws 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:
  `IOException`

### readBytes

public void readBytes(byte[] bbuf) throws 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:
  `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 ByteBuffer acquireBlock(int iblock) throws 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:
  `IOException`

### seek

public void seek(long offset) throws 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:
  `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 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:
  `IOException`

### getBlockCount

public int getBlockCount()
Returns the number of mapped blocks used.

Returns:
  block count