java.lang.Object
- db.ChainedBuffer

All Implemented Interfaces:: Buffer

public class ChainedBuffer
extends java.lang.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

All Methods Instance Methods Concrete Methods
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(java.io.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 Detail
  - ChainedBuffer
```
public ChainedBuffer(int size,
                     boolean enableObfuscation,
                     Buffer uninitializedDataSource,
                     int unintializedDataSourceOffset,
                     BufferMgr bufferMgr)
              throws java.io.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:
    
    java.io.IOException - thrown if an IO error occurs
  - ChainedBuffer
```
public ChainedBuffer(int size,
                     boolean enableObfuscation,
                     BufferMgr bufferMgr)
              throws java.io.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:
    
    java.io.IOException - thrown if an IO error occurs
  - ChainedBuffer
```
public ChainedBuffer(int size,
                     BufferMgr bufferMgr)
              throws java.io.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:
    
    java.io.IOException - thrown if an IO error occurs
  - ChainedBuffer
```
public ChainedBuffer(BufferMgr bufferMgr,
                     int bufferId,
                     Buffer uninitializedDataSource,
                     int unintializedDataSourceOffset)
              throws java.io.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:
    
    java.io.IOException - thrown if an IO error occurs
  - ChainedBuffer
```
public ChainedBuffer(BufferMgr bufferMgr,
                     int bufferId)
              throws java.io.IOException
```
    Construct an existing chained buffer.
    
    Parameters:
    
    bufferMgr - database buffer manager
    
    bufferId - database buffer ID which corresponds to a stored ChainedBuffer
    
    Throws:
    
    java.io.IOException - thrown if an IO error occurs
- Method Detail
  - 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 java.io.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:
    
    java.lang.UnsupportedOperationException - thrown if this ChainedBuffer utilizes an Uninitialized Data Source or is read-only
    
    java.io.IOException - thrown if an IO error occurs.
    
    java.lang.UnsupportedOperationException - if read-only or uninitialized data source is used
  - split
```
public ChainedBuffer split(int offset)
                    throws java.io.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:
    
    java.lang.UnsupportedOperationException - thrown if this ChainedBuffer is read-only
    
    java.lang.ArrayIndexOutOfBoundsException - if offset is invalid.
    
    java.io.IOException - thrown if an IO error occurs
  - append
```
public void append(ChainedBuffer dbBuf)
            throws java.io.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:
    
    java.io.IOException - thrown if an IO error occurs
    
    java.lang.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 java.io.IOException
```
    Delete and release all underlying DataBuffers.
    
    Throws:
    
    java.io.IOException - thrown if an IO error occurs
  - get
```
public void get(int offset,
                byte[] data,
                int dataOffset,
                int length)
         throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - get
```
public void get(int offset,
                byte[] data)
         throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - get
```
public byte[] get(int offset,
                  int length)
           throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - getByte
```
public byte getByte(int offset)
             throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - getInt
```
public int getInt(int offset)
           throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - getLong
```
public long getLong(int offset)
             throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - getShort
```
public short getShort(int offset)
               throws java.io.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:
    
    java.io.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 java.io.IOException
```
    Fill the buffer over the specified range with a byte value.
    
    Parameters:
    
    startOffset - starting offset, inclusive
    
    endOffset - ending offset, exclusive
    
    fillByte - byte value
    
    Throws:
    
    java.io.IOException - thrown if an IO error occurs
  - fill
```
public void fill(java.io.InputStream in)
          throws java.io.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:
    
    java.io.IOException - thrown if IO error occurs.
  - put
```
public int put(int offset,
               byte[] data,
               int dataOffset,
               int length)
        throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - put
```
public int put(int offset,
               byte[] bytes)
        throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - putByte
```
public int putByte(int offset,
                   byte b)
            throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - putInt
```
public int putInt(int offset,
                  int v)
           throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - putLong
```
public int putLong(int offset,
                   long v)
            throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.
  - putShort
```
public int putShort(int offset,
                    short v)
             throws java.io.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:
    
    java.io.IOException - is thrown if an error occurs while accessing the underlying storage.

Class ChainedBuffer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ChainedBuffer

ChainedBuffer

ChainedBuffer

ChainedBuffer

ChainedBuffer

Method Detail

hasObfuscatedStorage

setReadOnly

setSize

split

append

getId

delete

get

get

get

getByte

getInt

getLong

getShort

length

fill

fill

put

put

putByte

putInt

putLong

putShort