BlockMappedInput (Starjava FITS API)

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

Class BlockMappedInput

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BLOCKSIZE

DEFAULT_EXPIRYMILLIS

Constructor Detail

BlockMappedInput

Method Detail

readByte

readShort

readInt

readLong

readFloat

readDouble

isRandom

seek

getOffset

skip

getBlockCount

acquireBlock

createInput

createInput