uk.ac.starlink.fits

## Class BlockMappedInput

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

- All Implemented Interfaces:
    BasicInput

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

  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
  Author:
    Mark Taylor

- - ### 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 Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract java.nio.MappedByteBuffer` | `acquireBlock(int iblock)` Obtains a buffer corresponding to a named block of the stream.
    `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.
    `int` | `getBlockCount()` Returns the number of mapped blocks used.
    `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.
    `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`

    - ### Methods inherited from interface uk.ac.starlink.fits.BasicInput

      `close`

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

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

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

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

    - #### acquireBlock

          protected abstract java.nio.MappedByteBuffer 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`

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

Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.