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 Details

  • 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

    • getModCount

      public long getModCount()
      Provides a means of detecting changes to the underlying database during a transaction.
      Returns:
      current modification count

    • 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

    • setDBVersionedSourceFile

      public void setDBVersionedSourceFile(LocalManagedBufferFile versionedSourceBufferFile) throws IOException
      Set the source buffer file with a newer local buffer file version. Intended for use following a merge or commit operation only where a local checkout has been retained.
      Parameters:
      versionedSourceBufferFile - updated local source buffer file opened for versioning update (NOTE: file itself is read-only).
      Throws:
      IOException - if an IO error occurs

    • 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()