uk.ac.starlink.fits

## Class BlockMappedInput

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

- All Implemented Interfaces:
    BasicInput

      public abstract class BlockMappedInput
      extends BlockInput

  Random-access BasicInput implementation that maps a given region of a file as a number of byte buffers. The most recently-used buffer is always kept, but there is a choice of what to do with less-recently used ones. Concrete subclasses are provided that either discard them automatically or keep them around for a period of time before discarding them. If and when a buffer is discarded, an attempt is made to unmap it.

  Note: DO NOT use an instance of this class from multiple threads - see `Unmapper`.

  Since:
    2 Dec 2014

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_BLOCKSIZE` Default maximum size in bytes for mapped blocks.
    `static long` | `DEFAULT_EXPIRYMILLIS` Default time in milliseconds after which buffers will be discarded.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BlockMappedInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, int blockSize)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Releases resources belonging to this object.
    `static BlockMappedInput` | `createInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, boolean caching)` Constructs an instance that does or does not support caching.
    `static BlockMappedInput` | `createInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, int blockSize, long expiryMillis)` Constructs an instance with explicit configuration.
    `long` | `getBlockOffset(int iblock, int offsetInBlock)` Returns the offset into this stream corresponding to a given block index and offset into that block.
    `int[]` | `getBlockPos(long offset)` Returns the block location of a given byte offset.

    - ### Methods inherited from class uk.ac.starlink.fits.BlockInput

      `acquireBlock, getBlockCount, getOffset, isRandom, readByte, readBytes, readDouble, readFloat, readInt, readLong, readShort, seek, skip`

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

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

- - ### Field Detail

    - #### DEFAULT_BLOCKSIZE

          public static final int DEFAULT_BLOCKSIZE

      Default maximum size in bytes for mapped blocks.
      See Also:
        Constant Field Values

    - #### DEFAULT_EXPIRYMILLIS

          public static final long DEFAULT_EXPIRYMILLIS

      Default time in milliseconds after which buffers will be discarded.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BlockMappedInput

          protected BlockMappedInput(java.nio.channels.FileChannel channel,
                                     long pos,
                                     long size,
                                     java.lang.String logName,
                                     int blockSize)
                              throws java.io.IOException

      Constructor.
      Parameters:
        `channel` - file channel, preferably read-only
        `pos` - offset into file of stream start
        `size` - number of bytes in stream
        `logName` - name for mapped region used in logging messages
        `blockSize` - (maximum) number of bytes per mapped block
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### getBlockPos

          public int[] getBlockPos(long offset)

      Description copied from class: `BlockInput`
      Returns the block location of a given byte offset.

      This does the opposite of `getBlockOffset`.

      Specified by:
        `getBlockPos` in class `BlockInput`
      Parameters:
        `offset` - offset into this input stream
      Returns:
        2-element array giving [blockIndex, offsetInBlock]

    - #### getBlockOffset

          public long getBlockOffset(int iblock,
                                     int offsetInBlock)

      Description copied from class: `BlockInput`
      Returns the offset into this stream corresponding to a given block index and offset into that block.

      This does the opposite of `getBlockPos`.

      Specified by:
        `getBlockOffset` in class `BlockInput`
      Parameters:
        `iblock` - block index
        `offsetInBlock` - offset into that block
      Returns:
        offset into stream

    - #### 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`
      Overrides:
        `close` in class `BlockInput`

    - #### createInput

          public static BlockMappedInput createInput(java.nio.channels.FileChannel channel,
                                                     long pos,
                                                     long size,
                                                     java.lang.String logName,
                                                     boolean caching)
                                              throws java.io.IOException

      Constructs an instance that does or does not support caching. If caching is requested, recently used block buffers are kept around for a while in case they are needed again. If not, as soon as a new block is used, any others are discarded. A default block size is used.
      Parameters:
        `channel` - file channel, preferably read-only
        `pos` - offset into file of stream start
        `size` - number of bytes in stream
        `logName` - name for mapped region used in logging messages
        `caching` - whether buffers are cached
      Returns:
        new instance
      Throws:
        `java.io.IOException`

    - #### createInput

          public static BlockMappedInput createInput(java.nio.channels.FileChannel channel,
                                                     long pos,
                                                     long size,
                                                     java.lang.String logName,
                                                     int blockSize,
                                                     long expiryMillis)
                                              throws java.io.IOException

      Constructs an instance with explicit configuration. The `expiryMillis` parameter controls caching. If zero, the current buffer is discarded an unmapped as soon as a different one is used. Otherwise, an attempt is made to discard buffers only after they have been unused for a certain number of milliseconds.
      Parameters:
        `channel` - file channel, preferably read-only
        `pos` - offset into file of stream start
        `size` - number of bytes in stream
        `logName` - name for mapped region used in logging messages
        `blockSize` - maximum number of bytes per block
        `expiryMillis` - buffer caching period in milliseconds
      Returns:
        new instance
      Throws:
        `java.io.IOException`