Package db.buffers

Class BufferMgr

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

    • Constructor Detail

      • BufferMgr

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

      • BufferMgr

        public BufferMgr​(int requestedBufferSize,
                 long approxCacheSize,
                 int maxUndos)
          throws java.io.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:
        java.io.IOException - if a cache file access error occurs

      • BufferMgr

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

      • BufferMgr

        public BufferMgr​(BufferFile sourceFile,
                 long approxCacheSize,
                 int maxUndos)
          throws java.io.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:
        java.io.IOException - if source or cache file access error occurs

    • Method Detail

      • 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 java.lang.Throwable
        Dispose of buffer manager when finalized.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.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 java.io.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:
        java.io.IOException - if source or cache file access error occurs

      • createBuffer

        public DataBuffer createBuffer()
                        throws java.io.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:
        java.io.IOException - if a cache file access error occurs

      • releaseBuffer

        public void releaseBuffer​(DataBuffer buf)
                   throws java.io.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:
        java.io.IOException - if IO error occurs

      • deleteBuffer

        public void deleteBuffer​(int id)
                  throws java.io.IOException
        Delete buffer. DataBuffer is added to the free list for reuse.
        Parameters:
        id - buffer id
        Throws:
        java.io.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 java.io.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:
        java.io.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 java.io.IOException
        Returns:
        true if save operation can be performed.
        Throws:
        java.io.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 java.io.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:
        java.io.IOException - if IO error occurs
        CancelledException - if task monitor is cancelled

      • getRecoveryChangeSetFile

        public LocalBufferFile getRecoveryChangeSetFile()
                                         throws java.io.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:
        java.io.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 java.io.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:
        java.io.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​(java.lang.String comment,
                 DBChangeSet changeSet,
                 TaskMonitor monitor)
          throws java.io.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.
        java.io.IOException - if source, cache or destination file access error occurs

      • saveAs

        public void saveAs​(BufferFile outFile,
                   boolean associateWithNewFile,
                   TaskMonitor monitor)
            throws java.io.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.
        java.io.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 java.lang.String getStatusInfo()

      • getAllocatedBufferCount

        public int getAllocatedBufferCount()

      • getFreeBufferCount

        public int getFreeBufferCount()

      • cleanupOldCacheFiles

        public static void cleanupOldCacheFiles()