uk.ac.starlink.fits
Class BlockMappedInput

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

All Implemented Interfaces:

BasicInput

public abstract class BlockMappedInput
extends 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

Field Summary

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

protected

BlockMappedInput(FileChannel channel, long pos, long size, String logName, int blockSize) Constructor.

Method Summary

protected abstract MappedByteBuffer	acquireBlock(int iblock) Obtains a buffer corresponding to a named block of the stream.
static BlockMappedInput	createInput(FileChannel channel, long pos, long size, String logName, boolean caching) Constructs an instance that does or does not support caching.
static BlockMappedInput	createInput(FileChannel channel, long pos, long size, 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(FileChannel channel,
                           long pos,
                           long size,
                           String logName,
                           int blockSize)
                    throws 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:

IOException

Method Detail

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

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

acquireBlock

protected abstract MappedByteBuffer 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

createInput

public static BlockMappedInput createInput(FileChannel channel,
                                           long pos,
                                           long size,
                                           String logName,
                                           boolean caching)
                                    throws 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:

IOException

createInput

public static BlockMappedInput createInput(FileChannel channel,
                                           long pos,
                                           long size,
                                           String logName,
                                           int blockSize,
                                           long expiryMillis)
                                    throws 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:

IOException