Class BankBuf

  • All Implemented Interfaces:
    Buf

    public abstract class BankBuf
    extends java.lang.Object
    implements Buf
    Abstract Buf implementation that divides the byte sequence into one or more contiguous data banks. Each bank contains a run of bytes short enough to be indexed by a 4-byte integer.
    Since:
    18 Jun 2013
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  BankBuf.Bank
      Data bank for use within BankBuf class and its subclasses.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected BankBuf​(long size, boolean isBit64, boolean isBigendian)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.io.InputStream createInputStream​(long offset)
      Returns an input stream consisting of all the bytes in this buf starting from the given offset.
      static BankBuf createMultiBankBuf​(java.nio.ByteBuffer[] byteBuffers, boolean isBit64, boolean isBigendian)
      Returns a BankBuf based on an array of supplied ByteBuffers.
      static BankBuf createMultiBankBuf​(java.nio.channels.FileChannel channel, long size, int bankSize, boolean isBit64, boolean isBigendian)
      Returns a BankBuf based on supplied file channel.
      static BankBuf createSingleBankBuf​(java.nio.ByteBuffer byteBuffer, boolean isBit64, boolean isBigendian)
      Returns a BankBuf based on a single supplied ByteBuffer.
      Buf fillNewBuf​(long count, java.io.InputStream in)
      Creates a new Buf of a given length populated from a given input stream.
      protected abstract BankBuf.Bank getBank​(long offset, int count)
      Returns the bank which can read a given number of bytes starting at the given offset.
      protected abstract java.util.Iterator<BankBuf.Bank> getBankIterator​(long offset)
      Returns an iterator over banks starting with the one containing the given offset.
      protected abstract java.util.List<BankBuf.Bank> getExistingBanks()
      Returns a list of active banks.
      long getLength()
      Returns the extent of this buf in bytes.
      boolean isBigendian()
      Determines the data encoding of this buf.
      boolean isBit64()
      Determines the 64bit-ness of this buf.
      java.lang.String readAsciiString​(Pointer ptr, int nbyte)
      Reads a fixed number of bytes interpreting them as ASCII characters and returns the result as a string.
      void readDataBytes​(long offset, int count, byte[] array)
      Reads a sequence of byte values from this buf into an array.
      void readDataDoubles​(long offset, int count, double[] array)
      Reads a sequence of double values from this buf into an array.
      void readDataFloats​(long offset, int count, float[] array)
      Reads a sequence of float values from this buf into an array.
      void readDataInts​(long offset, int count, int[] array)
      Reads a sequence of int values from this buf into an array.
      void readDataLongs​(long offset, int count, long[] array)
      Reads a sequence of long integer values from this buf into an array.
      void readDataShorts​(long offset, int count, short[] array)
      Reads a sequence of short values from this buf into an array.
      int readInt​(Pointer ptr)
      Reads a signed big-endian 4-byte integer from the pointer position.
      long readOffset​(Pointer ptr)
      Reads a file offset or size from the pointer position.
      int readUnsignedByte​(Pointer ptr)
      Reads a single byte from the pointer position, returning a value in the range 0..255.
      void setBit64​(boolean isBit64)
      Sets the 64bit-ness of this buf.
      void setEncoding​(boolean bigend)
      Sets the encoding for reading numeric values as performed by the readData* methods.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • BankBuf

        protected BankBuf​(long size,
                          boolean isBit64,
                          boolean isBigendian)
        Constructor.
        Parameters:
        size - total size of buffer
        isBit64 - 64bit-ness of buf
        isBigendian - true for big-endian data, false for little-endian
    • Method Detail

      • getBank

        protected abstract BankBuf.Bank getBank​(long offset,
                                                int count)
                                         throws java.io.IOException
        Returns the bank which can read a given number of bytes starting at the given offset.

        Implementation: in most cases this will return one of the large banks that this object has allocated. However, in the case that the requested run straddles a bank boundary it may be necessary to generate a short-lived bank just to return from this method.

        Parameters:
        offset - start of required sequence
        count - number of bytes in required sequence
        Returns:
        bank
        Throws:
        java.io.IOException
      • getExistingBanks

        protected abstract java.util.List<BankBuf.Bank> getExistingBanks()
        Returns a list of active banks. Banks which have not been created yet do not need to be included.
      • getBankIterator

        protected abstract java.util.Iterator<BankBuf.Bank> getBankIterator​(long offset)
        Returns an iterator over banks starting with the one containing the given offset. If followed to the end, the returned sequence will go all the way to the end of the buf. The first bank does not need to start at the given offset, only to contain it.
        Parameters:
        offset - starting byte offset into buf
        Returns:
        iterator over data banks
      • getLength

        public long getLength()
        Description copied from interface: Buf
        Returns the extent of this buf in bytes.
        Specified by:
        getLength in interface Buf
        Returns:
        buffer length
      • readUnsignedByte

        public int readUnsignedByte​(Pointer ptr)
                             throws java.io.IOException
        Description copied from interface: Buf
        Reads a single byte from the pointer position, returning a value in the range 0..255. Pointer position is moved on appropriately.
        Specified by:
        readUnsignedByte in interface Buf
        Parameters:
        ptr - pointer
        Returns:
        byte value
        Throws:
        java.io.IOException
      • readInt

        public int readInt​(Pointer ptr)
                    throws java.io.IOException
        Description copied from interface: Buf
        Reads a signed big-endian 4-byte integer from the pointer position. Pointer position is moved on appropriately.
        Specified by:
        readInt in interface Buf
        Parameters:
        ptr - pointer
        Returns:
        integer value
        Throws:
        java.io.IOException
      • readOffset

        public long readOffset​(Pointer ptr)
                        throws java.io.IOException
        Description copied from interface: Buf
        Reads a file offset or size from the pointer position. This is a signed big-endian integer, occupying either 4 or 8 bytes according to the return value of Buf.isBit64(). Pointer position is moved on appropriately.
        Specified by:
        readOffset in interface Buf
        Returns:
        buffer size or offset value
        Throws:
        java.io.IOException
      • readAsciiString

        public java.lang.String readAsciiString​(Pointer ptr,
                                                int nbyte)
                                         throws java.io.IOException
        Description copied from interface: Buf
        Reads a fixed number of bytes interpreting them as ASCII characters and returns the result as a string. If a character 0x00 appears before nbyte bytes have been read, it is taken as the end of the string. Pointer position is moved on appropriately.
        Specified by:
        readAsciiString in interface Buf
        Parameters:
        ptr - pointer
        nbyte - maximum number of bytes in string
        Returns:
        ASCII string
        Throws:
        java.io.IOException
      • setBit64

        public void setBit64​(boolean isBit64)
        Description copied from interface: Buf
        Sets the 64bit-ness of this buf. This determines whether readOffset reads 4- or 8-byte values.

        This method should be called before the readOffset method is invoked.

        Specified by:
        setBit64 in interface Buf
        Parameters:
        isBit64 - true for 8-byte offsets, false for 4-byte offsets
      • isBit64

        public boolean isBit64()
        Description copied from interface: Buf
        Determines the 64bit-ness of this buf. This determines whether readOffset reads 4- or 8-byte values.
        Specified by:
        isBit64 in interface Buf
        Returns:
        true for 8-byte offsets, false for 4-byte offsets
      • setEncoding

        public void setEncoding​(boolean bigend)
        Description copied from interface: Buf
        Sets the encoding for reading numeric values as performed by the readData* methods.

        As currently specified, there are only two possibiliies, Big-Endian and Little-Endian. Interface and implementation would need to be reworked somewhat to accommodate the (presumably, rarely seen in this day and age) D_FLOAT and G_FLOAT encodings supported by the CDF standard.

        This method should be called before any of the readData* methods are invoked.

        Specified by:
        setEncoding in interface Buf
        Parameters:
        bigend - true for big-endian, false for little-endian
      • isBigendian

        public boolean isBigendian()
        Description copied from interface: Buf
        Determines the data encoding of this buf.
        Specified by:
        isBigendian in interface Buf
        Returns:
        true for big-endian, false for little-endian
      • readDataBytes

        public void readDataBytes​(long offset,
                                  int count,
                                  byte[] array)
                           throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of byte values from this buf into an array.
        Specified by:
        readDataBytes in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of byte values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • readDataShorts

        public void readDataShorts​(long offset,
                                   int count,
                                   short[] array)
                            throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of short values from this buf into an array.
        Specified by:
        readDataShorts in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of short values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • readDataInts

        public void readDataInts​(long offset,
                                 int count,
                                 int[] array)
                          throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of int values from this buf into an array.
        Specified by:
        readDataInts in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of int values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • readDataLongs

        public void readDataLongs​(long offset,
                                  int count,
                                  long[] array)
                           throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of long integer values from this buf into an array.
        Specified by:
        readDataLongs in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of long values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • readDataFloats

        public void readDataFloats​(long offset,
                                   int count,
                                   float[] array)
                            throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of float values from this buf into an array.
        Specified by:
        readDataFloats in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of float values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • readDataDoubles

        public void readDataDoubles​(long offset,
                                    int count,
                                    double[] array)
                             throws java.io.IOException
        Description copied from interface: Buf
        Reads a sequence of double values from this buf into an array.
        Specified by:
        readDataDoubles in interface Buf
        Parameters:
        offset - position sequence start in this buffer in bytes
        count - number of double values to read
        array - array to receive values, starting at array element 0
        Throws:
        java.io.IOException
      • createInputStream

        public java.io.InputStream createInputStream​(long offset)
        Description copied from interface: Buf
        Returns an input stream consisting of all the bytes in this buf starting from the given offset.
        Specified by:
        createInputStream in interface Buf
        Parameters:
        offset - position of first byte in buf that will appear in the returned stream
        Returns:
        input stream
      • fillNewBuf

        public Buf fillNewBuf​(long count,
                              java.io.InputStream in)
                       throws java.io.IOException
        Description copied from interface: Buf
        Creates a new Buf of a given length populated from a given input stream. The new buf object must have the same data encoding and 64bit-ness as this one.
        Specified by:
        fillNewBuf in interface Buf
        Parameters:
        count - size of new buffer in bytes
        in - input stream capable of supplying (at least) count bytes
        Returns:
        new buffer of length count filled with bytes from in
        Throws:
        java.io.IOException
      • createSingleBankBuf

        public static BankBuf createSingleBankBuf​(java.nio.ByteBuffer byteBuffer,
                                                  boolean isBit64,
                                                  boolean isBigendian)
        Returns a BankBuf based on a single supplied ByteBuffer.
        Parameters:
        byteBuffer - NIO buffer containing data
        isBit64 - 64bit-ness of buf
        isBigendian - true for big-endian data, false for little-endian
        Returns:
        new buf
      • createMultiBankBuf

        public static BankBuf createMultiBankBuf​(java.nio.ByteBuffer[] byteBuffers,
                                                 boolean isBit64,
                                                 boolean isBigendian)
        Returns a BankBuf based on an array of supplied ByteBuffers.
        Parameters:
        byteBuffers - NIO buffers containing data (when concatenated)
        isBit64 - 64bit-ness of buf
        isBigendian - true for big-endian data, false for little-endian
        Returns:
        new buf
      • createMultiBankBuf

        public static BankBuf createMultiBankBuf​(java.nio.channels.FileChannel channel,
                                                 long size,
                                                 int bankSize,
                                                 boolean isBit64,
                                                 boolean isBigendian)
        Returns a BankBuf based on supplied file channel.
        Parameters:
        channel - readable file containing data
        size - number of bytes in channel
        bankSize - maximum size for individual data banks
        isBit64 - 64bit-ness of buf
        isBigendian - true for big-endian data, false for little-endian
        Returns:
        new buf