Package db.buffers

# Class BufferMgr

java.lang.Object
db.buffers.BufferMgr

public class BufferMgr extends Object
`BufferMgr` provides low-level buffer management and caching. Checkpointing and buffer versioning is supported along with an undo/redo capability.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ALWAYS_PRECACHE_PROPERTY`
  `static final int`
  `DEFAULT_BUFFER_SIZE`
  `static final int`
  `DEFAULT_CACHE_SIZE`
  `static final int`
  `DEFAULT_CHECKPOINT_COUNT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BufferMgr()`
  Construct a new buffer manager with no underlying source file using the default buffer size, cache size and maximum undo count.
  `BufferMgr(int requestedBufferSize, long approxCacheSize, int maxUndos)`
  Construct a new buffer manager with no underlying source file.
  `BufferMgr(BufferFile sourceFile)`
  Construct a buffer manager for a given source file using default cache size and maximum undo count.
  `BufferMgr(BufferFile sourceFile, long approxCacheSize, int maxUndos)`
  Construct a buffer manager for a given source file using default cache size and maximum undo count.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `atCheckpoint()`
  `static boolean`
  `canRecover(BufferFileManager bfMgr)`
  Determine if unsaved changes can be recovered for the current BufferFile associated with the specified bfMgr.
  `boolean`
  `canSave()`
  `boolean`
  `checkpoint()`
  Completes a transaction by closing the current checkpoint.
  `static void`
  `cleanupOldCacheFiles()`
  `void`
  `clearCheckpoints()`
  Clear all checkpoints and re-baseline buffers
  `void`
  `clearRecoveryFiles()`
  Immediately following instantiation of this BufferMgr, discard any pre-existing recovery snapshots.
  `DataBuffer`
  `createBuffer()`
  Get a new or recycled buffer.
  `void`
  `deleteBuffer(int id)`
  Delete buffer.
  `void`
  `dispose()`
  Dispose of all buffer manager resources including any source buffer file.
  `void`
  `dispose(boolean keepRecoveryData)`
  Dispose of all buffer manager resources including any source buffer file.
  `void`
  `enablePreCache()`
  Enable and start source buffer file pre-cache if appropriate.
  `protected void`
  `finalize()`
  Dispose of buffer manager when finalized.
  `int`
  `getAllocatedBufferCount()`
  `int`
  `getAvailableRedoCount()`
  `int`
  `getAvailableUndoCount()`
  `DataBuffer`
  `getBuffer(int id)`
  Get the specified buffer.
  `int`
  `getBufferSize()`
  `long`
  `getCacheHits()`
  `long`
  `getCacheMisses()`
  `int`
  `getFreeBufferCount()`
  `int`
  `getLockCount()`
  Get the current number of locked buffers.
  `int`
  `getLowBufferCount()`
  `int`
  `getMaxUndos()`
  Get the maximum number of checkpoints retained.
  `LocalBufferFile`
  `getRecoveryChangeSetFile()`
  Returns the recovery changeSet data file for reading or null if one is not available.
  `BufferFile`
  `getSourceFile()`
  `String`
  `getStatusInfo()`
  `boolean`
  `hasRedoCheckpoints()`
  Indicates whether checkpoint versions are available for redo.
  `boolean`
  `hasUndoCheckpoints()`
  Indicates whether checkpoint versions are available for undo.
  `boolean`
  `isChanged()`
  `boolean`
  `isCorrupted()`
  Determine if BufferMgr has become corrupted (IOException has occurred).
  `boolean`
  `modifiedSinceSnapshot()`
  `boolean`
  `recover(TaskMonitor monitor)`
  Immediately following instatiation of this BufferMgr, attempt a unsaved data recovery.
  `boolean`
  `redo()`
  Redo next checkpoint.
  `void`
  `releaseBuffer(DataBuffer buf)`
  Release buffer back to buffer manager.
  `void`
  `resetCacheStatistics()`
  `void`
  `save(String comment, DBChangeSet changeSet, TaskMonitor monitor)`
  Save the current set of buffers to a new version of the source buffer file.
  `void`
  `saveAs(BufferFile outFile, boolean associateWithNewFile, TaskMonitor monitor)`
  Save the current set of buffers to a new buffer file.
  `void`
  `setCorruptedState()`
  Set the corrupt state flag for this buffer manager.
  `void`
  `setMaxUndos(int maxUndos)`
  Set the maximum number of undoable checkpoints maintained by buffer manager.
  `boolean`
  `takeRecoverySnapshot(DBChangeSet changeSet, TaskMonitor monitor)`
  Generate recovery snapshot of unsaved data.
  `boolean`
  `undo(boolean redoable)`
  Backup to previous checkpoint.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### ALWAYS_PRECACHE_PROPERTY

    public static final String ALWAYS_PRECACHE_PROPERTY
    See Also:
      - Constant Field Values

  - ### DEFAULT_BUFFER_SIZE

    public static final int DEFAULT_BUFFER_SIZE
    See Also:
      - Constant Field Values

  - ### DEFAULT_CHECKPOINT_COUNT

    public static final int DEFAULT_CHECKPOINT_COUNT
    See Also:
      - Constant Field Values

  - ### DEFAULT_CACHE_SIZE

    public static final int DEFAULT_CACHE_SIZE
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### BufferMgr

    public BufferMgr() throws IOException
    Construct a new buffer manager with no underlying source file using the default buffer size, cache size and maximum undo count.
    Throws:
      `IOException` - if a cache file access error occurs

  - ### BufferMgr

    public BufferMgr(int requestedBufferSize, long approxCacheSize, int maxUndos) throws IOException
    Construct a new buffer manager with no underlying source file.
    Parameters:
      `requestedBufferSize` - requested buffer size. Actual buffer size may vary.
      `approxCacheSize` - approximate size of cache in Bytes.
      `maxUndos` - maximum number of checkpoints retained for undo (Minimum=1).
    Throws:
      `IOException` - if a cache file access error occurs

  - ### BufferMgr

    public BufferMgr(BufferFile sourceFile) throws IOException
    Construct a buffer manager for a given source file using default cache size and maximum undo count.
    Parameters:
      `sourceFile` - buffer file
    Throws:
      `IOException` - if source or cache file access error occurs

  - ### BufferMgr

    public BufferMgr(BufferFile sourceFile, long approxCacheSize, int maxUndos) throws IOException
    Construct a buffer manager for a given source file using default cache size and maximum undo count.
    Parameters:
      `sourceFile` - buffer file
      `approxCacheSize` - approximate size of cache in Bytes.
      `maxUndos` - maximum number of checkpoints retained for undo (Minimum=1).
    Throws:
      `IOException` - if source or cache file access error occurs

- ## Method Details

  - ### enablePreCache

    public void enablePreCache()
    Enable and start source buffer file pre-cache if appropriate. This may be forced for all use cases by setting the System property db.always.precache=true WARNING! EXPERIMENTAL !!!

  - ### setCorruptedState

    public void setCorruptedState()
    Set the corrupt state flag for this buffer manager. This will cause any snapshot attempt to fail and cause most public access methods to throw an IOException. The caller should log this action and the reason for it.

  - ### isCorrupted

    public boolean isCorrupted()
    Determine if BufferMgr has become corrupted (IOException has occurred).
    Returns:
      true if this BufferMgr is corrupt.

  - ### getLockCount

    public int getLockCount()
    Get the current number of locked buffers.
    Returns:
      int

  - ### getBufferSize

    public int getBufferSize()
    Returns:
      the size of each buffer in bytes.

  - ### getSourceFile

    public BufferFile getSourceFile()
    Returns:
      returns the source file

  - ### finalize

    protected void finalize() throws Throwable
    Dispose of buffer manager when finalized.
    Overrides:
      `finalize` in class `Object`
    Throws:
      `Throwable`

  - ### dispose

    public void dispose()
    Dispose of all buffer manager resources including any source buffer file. Any existing recovery data will be discarded. This method should be called when this buffer manager instance is no longer needed.

  - ### dispose

    public void dispose(boolean keepRecoveryData)
    Dispose of all buffer manager resources including any source buffer file. This method should be called when this buffer manager instance is no longer needed.
    Parameters:
      `keepRecoveryData` - true if existing snapshot recovery files should not be deleted.

  - ### setMaxUndos

    public void setMaxUndos(int maxUndos)
    Set the maximum number of undoable checkpoints maintained by buffer manager. Existing redo checkpoints are cleared and the stack of undo checkpoints will be reduced if maxUndos is less than the current setting.
    Parameters:
      `maxUndos` - maximum number of undo checkpoints. A negative value restores the default value.

  - ### clearCheckpoints

    public void clearCheckpoints()
    Clear all checkpoints and re-baseline buffers

  - ### getMaxUndos

    public int getMaxUndos()
    Get the maximum number of checkpoints retained.
    Returns:
      int

  - ### getBuffer

    public DataBuffer getBuffer(int id) throws IOException
    Get the specified buffer. When done working with the buffer, the method releaseBuffer must be used to return it to the buffer manager. Buffers should not be held for long periods.
    Parameters:
      `id` - buffer id
    Returns:
      buffer object, or null if buffer not found
    Throws:
      `IOException` - if source or cache file access error occurs

  - ### createBuffer

    public DataBuffer createBuffer() throws IOException
    Get a new or recycled buffer. New buffer is always returned with update enabled. When done working with the buffer, the method releaseBuffer must be used to return it to the buffer manager. Buffers should not be held for long periods.
    Returns:
      buffer object, or null if buffer not found
    Throws:
      `IOException` - if a cache file access error occurs

  - ### releaseBuffer

    public void releaseBuffer(DataBuffer buf) throws IOException
    Release buffer back to buffer manager. After invoking this method, the buffer object should not be used and all references should be dropped.
    Parameters:
      `buf` - data buffer
    Throws:
      `IOException` - if IO error occurs

  - ### deleteBuffer

    public void deleteBuffer(int id) throws IOException
    Delete buffer. DataBuffer is added to the free list for reuse.
    Parameters:
      `id` - buffer id
    Throws:
      `IOException` - if source or cache file access error occurs

  - ### atCheckpoint

    public boolean atCheckpoint()
    Returns:
      true if no buffers have been updated since last checkpoint.

  - ### checkpoint

    public boolean checkpoint()
    Completes a transaction by closing the current checkpoint. All modified buffers since the previous invocation of this method will be contained within "transaction". The redo stack will be cleared.
    Returns:
      true if checkpoint successful, or false if buffers are read-only

  - ### isChanged

    public boolean isChanged()
    Returns:
      true if unsaved "buffer" changes exist. If no changes have been made, or all changes have been "undone", false will be returned. Parameter changes are no considered.

  - ### hasUndoCheckpoints

    public boolean hasUndoCheckpoints()
    Indicates whether checkpoint versions are available for undo.
    Returns:
      true if undo is available

  - ### hasRedoCheckpoints

    public boolean hasRedoCheckpoints()
    Indicates whether checkpoint versions are available for redo.
    Returns:
      true if redo is available

  - ### getAvailableUndoCount

    public int getAvailableUndoCount()
    Returns:
      number of undo-able transactions

  - ### getAvailableRedoCount

    public int getAvailableRedoCount()
    Returns:
      the number of redo-able transactions

  - ### undo

    public boolean undo(boolean redoable) throws IOException
    Backup to previous checkpoint. Method should not be invoked when one or more buffers are locked.
    Parameters:
      `redoable` - true if currrent checkpoint should be moved to redo stack
    Returns:
      true if successful else false
    Throws:
      `IOException` - if IO error occurs

  - ### redo

    public boolean redo()
    Redo next checkpoint. Method should not be invoked when one or more buffers are locked.
    Returns:
      true if successful else false

  - ### canSave

    public boolean canSave() throws IOException
    Returns:
      true if save operation can be performed.
    Throws:
      `IOException` - if IO error occurs

  - ### modifiedSinceSnapshot

    public boolean modifiedSinceSnapshot()
    Returns:
      true if buffers have been modified since opening or since last snapshot.

  - ### takeRecoverySnapshot

    public boolean takeRecoverySnapshot(DBChangeSet changeSet, TaskMonitor monitor) throws IOException, CancelledException
    Generate recovery snapshot of unsaved data.
    Parameters:
      `changeSet` - an optional database-backed change set which reflects changes made since the last version.
      `monitor` - task monitor
    Returns:
      true if snapshot successful, false if
    Throws:
      `IOException` - if IO error occurs
      `CancelledException` - if task monitor is cancelled

  - ### getRecoveryChangeSetFile

    public LocalBufferFile getRecoveryChangeSetFile() throws IOException
    Returns the recovery changeSet data file for reading or null if one is not available. The caller must dispose of the returned file before peforming generating any new recovery snapshots.
    Returns:
      recovery change set buffer file
    Throws:
      `IOException` - if IO error occurs

  - ### clearRecoveryFiles

    public void clearRecoveryFiles()
    Immediately following instantiation of this BufferMgr, discard any pre-existing recovery snapshots.

  - ### recover

    public boolean recover(TaskMonitor monitor) throws IOException, CancelledException
    Immediately following instatiation of this BufferMgr, attempt a unsaved data recovery. If successful, the method getRecoveryChangeSetFile should be invoked to obtain/open the changeSet data file which must be used by the application to recover the changeSet. If recovery is cancelled, this buffer manager must be disposed. since the underlying state will be corrupt.
    Parameters:
      `monitor` - task monitor
    Returns:
      true if recovery successful else false
    Throws:
      `IOException` - if IO error occurs
      `CancelledException` - if task monitor is cancelled

  - ### canRecover

    public static boolean canRecover(BufferFileManager bfMgr)
    Determine if unsaved changes can be recovered for the current BufferFile associated with the specified bfMgr.
    Parameters:
      `bfMgr` - buffer file manager
    Returns:
      true if a recover is possible

  - ### save

    public void save(String comment, DBChangeSet changeSet, TaskMonitor monitor) throws IOException, CancelledException
    Save the current set of buffers to a new version of the source buffer file. If the buffer manager was not instantiated with a source file an IllegalStateException will be thrown.
    Parameters:
      `comment` - if version history is maintained, this comment will be associated with the new version.
      `changeSet` - an optional database-backed change set which reflects changes made since the last version.
      `monitor` - a cancellable task monitor. This method will establish the maximum progress count.
    Throws:
      `CancelledException` - if the task monitor cancelled the operation.
      `IOException` - if source, cache or destination file access error occurs

  - ### saveAs

    public void saveAs(BufferFile outFile, boolean associateWithNewFile, TaskMonitor monitor) throws IOException, CancelledException
    Save the current set of buffers to a new buffer file.
    Parameters:
      `outFile` - an empty buffer file open for writing
      `associateWithNewFile` - if true the outFile will be associated with this BufferMgr as the current source file, if false no change will be made to this BufferMgr's state and the outFile will be written and set as read-only. The caller is responsible for disposing the outFile if this parameter is false.
      `monitor` - a cancelable task monitor. This method will establish the maximum progress count.
    Throws:
      `CancelledException` - if the task monitor canceled the operation.
      `IOException` - if source, cache or destination file access error occurs

  - ### getCacheHits

    public long getCacheHits()

  - ### getCacheMisses

    public long getCacheMisses()

  - ### getLowBufferCount

    public int getLowBufferCount()

  - ### resetCacheStatistics

    public void resetCacheStatistics()

  - ### getStatusInfo

    public String getStatusInfo()

  - ### getAllocatedBufferCount

    public int getAllocatedBufferCount()

  - ### getFreeBufferCount

    public int getFreeBufferCount()

  - ### cleanupOldCacheFiles

    public static void cleanupOldCacheFiles()