Class 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 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 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 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.
      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
    • 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
      • readBytes

        public void readBytes​(byte[] bbuf)
                       throws java.io.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:
        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