Package db

Class ChainedBuffer

java.lang.Object
db.ChainedBuffer
All Implemented Interfaces:
Buffer
public class ChainedBuffer extends Object implements Buffer
DBBuffer provides storage for large data objects utilizing a common buffer management system. Smaller data buffers are allocated and chained as needed. All instances of DBBuffer must be immediately discarded following an undo or redo on the associated DBHandle.

The largest supported chained buffer is about 2-GBytes. This limit may be slightly smaller based upon the underlying database buffer size.

The buffer may consist of either a single Data Node or a series of Index Nodes which reference Data Nodes. 

 Data Node (Non-indexed):
   | 9 (1) | Obfuscation/DataLength(4) | Data ...
 
 Data Node (Indexed):
   | 9 (1) | Data ...
 
 Index Node:
   | 8 (1) | Obfuscation/DataLength(4) | NextIndexId(4) | DataBuffer1Id(4) | ... | DataBufferNId(4) |
   Number of index entries computed based upon data length and buffer size.  The index for 
   the entire data space is divided among a series of Index Nodes which
   are chained together using the NextIndexId field. Each Index Node identifies 
   Data Nodes which have been allocated by a DataBufferId.  A DataBufferId of -1 indicates an
   non-allocated data node.  The DataLength field is only used in the first index buffer.
   
 Obfuscation:
   Data obfuscation is indicated by a '1' in the most-significant bit of the Obfuscation/DataLength 
   field.
Once a DBBuffer is deleted or appended to another DBBuffer, it becomes invalid and may no longer be used.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ChainedBuffer(int size, boolean enableObfuscation, Buffer uninitializedDataSource, int unintializedDataSourceOffset, BufferMgr bufferMgr)
    Construct a new chained buffer with optional obfuscation and uninitialized data source.
    ChainedBuffer(int size, boolean enableObfuscation, BufferMgr bufferMgr)
    Construct a new chained buffer with optional obfuscation.
    ChainedBuffer(int size, BufferMgr bufferMgr)
    Construct a new chained buffer.
    ChainedBuffer(BufferMgr bufferMgr, int bufferId)
    Construct an existing chained buffer.
    ChainedBuffer(BufferMgr bufferMgr, int bufferId, Buffer uninitializedDataSource, int unintializedDataSourceOffset)
    Construct an existing chained buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    append(ChainedBuffer dbBuf)
    Append the contents of the specified dbBuf onto the end of this buffer.
    void
    delete()
    Delete and release all underlying DataBuffers.
    void
    fill(int startOffset, int endOffset, byte fillByte)
    Fill the buffer over the specified range with a byte value.
    void
    fill(InputStream in)
    Fill buffer with data provided by InputStream.
    void
    get(int offset, byte[] data)
    Get the byte data located at the specified offset and store into the bytes array provided.
    void
    get(int offset, byte[] data, int dataOffset, int length)
    Get the byte data located at the specified offset and store into the data array at the specified data offset.
    byte[]
    get(int offset, int length)
    Get the byte data located at the specified offset.
    byte
    getByte(int offset)
    Get the 8-bit byte value located at the specified offset.
    int
    getId()
    Get the first buffer ID associated with this chained buffer.
    int
    getInt(int offset)
    Get the 32-bit integer value located at the specified offset.
    long
    getLong(int offset)
    Get the 64-bit long value located at the specified offset.
    short
    getShort(int offset)
    Get the 16-bit short value located at the specified offset.
    boolean
    hasObfuscatedStorage()
     
    int
    length()
    Get the length of the buffer in bytes.
    int
    put(int offset, byte[] bytes)
    Put the bytes provided into the buffer at the specified offset.
    int
    put(int offset, byte[] data, int dataOffset, int length)
    Put a specified number of bytes from the array provided into the buffer at the specified offset.
    int
    putByte(int offset, byte b)
    Put the 8-bit byte value into the buffer at the specified offset.
    int
    putInt(int offset, int v)
    Put the 32-bit integer value into the buffer at the specified offset.
    int
    putLong(int offset, long v)
    Put the 64-bit long value into the buffer at the specified offset.
    int
    putShort(int offset, short v)
    Put the 16-bit short value into the buffer at the specified offset.
    void
    setReadOnly()
    Set the read-only state of this ChainedBuffer.
    void
    setSize(int size, boolean preserveData)
    Set the new size for this DBBuffer object.
    ChainedBuffer
    split(int offset)
    Split this DBBuffer object into two separate DBBuffers.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ChainedBuffer

      public ChainedBuffer(int size, boolean enableObfuscation, Buffer uninitializedDataSource, int unintializedDataSourceOffset, BufferMgr bufferMgr) throws IOException
      Construct a new chained buffer with optional obfuscation and uninitialized data source. This method may only be invoked while a database transaction is in progress.
      Parameters:
      size - buffer size (0 < size <= 0x7fffffff)
      enableObfuscation - true to enable xor-ing of stored data to facilitate data obfuscation.
      uninitializedDataSource - optional data source for uninitialized data. This should be a read-only buffer which will always be used when re-instantiating the same stored ChainedBuffer. This should not be specified if buffer will be completely filled/initialized.
      unintializedDataSourceOffset - uninitialized data source offset which corresponds to this buffers contents.
      bufferMgr - database buffer manager
      Throws:
      IOException - thrown if an IO error occurs

    • ChainedBuffer

      public ChainedBuffer(int size, boolean enableObfuscation, BufferMgr bufferMgr) throws IOException
      Construct a new chained buffer with optional obfuscation. This method may only be invoked while a database transaction is in progress.
      Parameters:
      size - buffer size (0 < size <= 0x7fffffff)
      enableObfuscation - true to enable xor-ing of stored data to facilitate data obfuscation.
      bufferMgr - database buffer manager
      Throws:
      IOException - thrown if an IO error occurs

    • ChainedBuffer

      public ChainedBuffer(int size, BufferMgr bufferMgr) throws IOException
      Construct a new chained buffer. This method may only be invoked while a database transaction is in progress.
      Parameters:
      size - buffer size (0 < size <= 0x7fffffff)
      bufferMgr - database buffer manager
      Throws:
      IOException - thrown if an IO error occurs

    • ChainedBuffer

      public ChainedBuffer(BufferMgr bufferMgr, int bufferId, Buffer uninitializedDataSource, int unintializedDataSourceOffset) throws IOException
      Construct an existing chained buffer.
      Parameters:
      bufferMgr - database buffer manager
      bufferId - database buffer ID which corresponds to a stored ChainedBuffer
      uninitializedDataSource - optional data source for uninitialized data. This should be a read-only buffer which will always be used when re-instantiating the same stored ChainedBuffer. This should not be specified if buffer will be completely filled/initialized.
      unintializedDataSourceOffset - uninitialized data source offset which corresponds to this buffers contents.
      Throws:
      IOException - thrown if an IO error occurs

    • ChainedBuffer

      public ChainedBuffer(BufferMgr bufferMgr, int bufferId) throws IOException
      Construct an existing chained buffer.
      Parameters:
      bufferMgr - database buffer manager
      bufferId - database buffer ID which corresponds to a stored ChainedBuffer
      Throws:
      IOException - thrown if an IO error occurs

  • Method Details

    • hasObfuscatedStorage

      public boolean hasObfuscatedStorage()
      Returns:
      true if obfuscated data storage has been enabled

    • setReadOnly

      public void setReadOnly()
      Set the read-only state of this ChainedBuffer. After invoking this method any attempt to alter this buffer will result in an UnsupportedOperation exception.

    • setSize

      public void setSize(int size, boolean preserveData) throws IOException
      Set the new size for this DBBuffer object.
      Parameters:
      size - new size
      preserveData - if true, existing data is preserved at the original offsets. If false, no additional effort will be expended to preserve data.
      Throws:
      UnsupportedOperationException - thrown if this ChainedBuffer utilizes an Uninitialized Data Source or is read-only
      IOException - thrown if an IO error occurs.

    • split

      public ChainedBuffer split(int offset) throws IndexOutOfBoundsException, IOException
      Split this DBBuffer object into two separate DBBuffers. This DBBuffer remains valid but its new size is equal offset. The newly created DBBuffer is returned.
      Parameters:
      offset - the split point. The byte at this offset becomes the first byte within the new buffer.
      Returns:
      the new DBBuffer object.
      Throws:
      UnsupportedOperationException - thrown if this ChainedBuffer is read-only
      IndexOutOfBoundsException - if offset is invalid.
      IOException - thrown if an IO error occurs

    • append

      public void append(ChainedBuffer dbBuf) throws IOException
      Append the contents of the specified dbBuf onto the end of this buffer. The size of this buffer increases by the size of dbBuf. When the operation is complete, dbBuf object is no longer valid and must not be used.
      Parameters:
      dbBuf - the buffer to be appended to this buffer.
      Throws:
      IOException - thrown if an IO error occurs
      UnsupportedOperationException - if read-only, uninitialized data source is used, or both buffers do not have the same obfuscation enablement

    • getId

      public int getId()
      Get the first buffer ID associated with this chained buffer. This DBBuffer may be reinstatiated using the returned buffer ID provided subsequent changes are not made.
      Specified by:
      getId in interface Buffer
      Returns:
      buffer ID

    • delete

      public void delete() throws IOException
      Delete and release all underlying DataBuffers.
      Throws:
      IOException - thrown if an IO error occurs

    • get

      public void get(int offset, byte[] data, int dataOffset, int length) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the byte data located at the specified offset and store into the data array at the specified data offset.
      Specified by:
      get in interface Buffer
      Parameters:
      offset - byte offset from the start of the buffer.
      data - byte array to store the data.
      dataOffset - offset into the data buffer
      length - amount of data to read
      Throws:
      IndexOutOfBoundsException - if an invalid offset, dataOffset, or length is specified.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • get

      public void get(int offset, byte[] data) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the byte data located at the specified offset and store into the bytes array provided.
      Specified by:
      get in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      data - byte array to store data
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • get

      public byte[] get(int offset, int length) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the byte data located at the specified offset.
      Specified by:
      get in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      length - number of bytes to be read and returned
      Returns:
      the byte array.
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified or the end of the buffer was encountered while reading the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • getByte

      public byte getByte(int offset) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the 8-bit byte value located at the specified offset.
      Specified by:
      getByte in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      Returns:
      the byte value at the specified offset.
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • getInt

      public int getInt(int offset) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the 32-bit integer value located at the specified offset.
      Specified by:
      getInt in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      Returns:
      the integer value at the specified offset.
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified or the end of the buffer was encountered while reading the value.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • getLong

      public long getLong(int offset) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the 64-bit long value located at the specified offset.
      Specified by:
      getLong in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      Returns:
      the long value at the specified offset.
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified or the end of the buffer was encountered while reading the value.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • getShort

      public short getShort(int offset) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Get the 16-bit short value located at the specified offset.
      Specified by:
      getShort in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      Returns:
      the short value at the specified offset.
      Throws:
      IndexOutOfBoundsException - is thrown if an invalid offset is specified or the end of the buffer was encountered while reading the value.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • length

      public int length()
      Description copied from interface: Buffer
      Get the length of the buffer in bytes. The length reflects the number of bytes which have been allocated to the buffer.
      Specified by:
      length in interface Buffer
      Returns:
      length of allocated buffer.

    • fill

      public void fill(int startOffset, int endOffset, byte fillByte) throws IndexOutOfBoundsException, IOException
      Fill the buffer over the specified range with a byte value.
      Parameters:
      startOffset - starting offset, inclusive
      endOffset - ending offset, inclusive
      fillByte - byte value
      Throws:
      IndexOutOfBoundsException - if an invalid offsets are provided or the end of buffer was encountered while storing the data.
      IOException - thrown if an IO error occurs

    • fill

      public void fill(InputStream in) throws IOException
      Fill buffer with data provided by InputStream. If stream is exhausted, the remainder of the buffer will be filled with 0's.
      Parameters:
      in - data source
      Throws:
      IOException - thrown if IO error occurs.

    • put

      public int put(int offset, byte[] data, int dataOffset, int length) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put a specified number of bytes from the array provided into the buffer at the specified offset. The number of bytes stored is specified by the length specified.
      Specified by:
      put in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      data - the byte data to be stored.
      dataOffset - the starting offset into the data.
      length - the number of bytes to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided or the end of buffer was encountered while storing the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • put

      public int put(int offset, byte[] bytes) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put the bytes provided into the buffer at the specified offset. The number of bytes stored is determined by the length of the bytes array.
      Specified by:
      put in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      bytes - the byte data to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided or the end of buffer was encountered while storing the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • putByte

      public int putByte(int offset, byte b) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put the 8-bit byte value into the buffer at the specified offset.
      Specified by:
      putByte in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      b - the byte value to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • putInt

      public int putInt(int offset, int v) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put the 32-bit integer value into the buffer at the specified offset.
      Specified by:
      putInt in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      v - the integer value to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided or the end of buffer was encountered while storing the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • putLong

      public int putLong(int offset, long v) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put the 64-bit long value into the buffer at the specified offset.
      Specified by:
      putLong in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      v - the long value to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided or the end of buffer was encountered while storing the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.

    • putShort

      public int putShort(int offset, short v) throws IndexOutOfBoundsException, IOException
      Description copied from interface: Buffer
      Put the 16-bit short value into the buffer at the specified offset.
      Specified by:
      putShort in interface Buffer
      Parameters:
      offset - byte offset from start of buffer.
      v - the short value to be stored.
      Returns:
      the next available offset into the buffer, or -1 if the buffer is full.
      Throws:
      IndexOutOfBoundsException - if an invalid offset is provided or the end of buffer was encountered while storing the data.
      IOException - is thrown if an error occurs while accessing the underlying storage.