Package db

Class DBHandle

  • Direct Known Subclasses:
    PackedDBHandle
    public class DBHandle
extends java.lang.Object
    DBHandle provides access to an open database.

    • Constructor Summary

      Constructors 
      Constructor Description
      DBHandle()
      Construct a temporary database handle.
      DBHandle​(int requestBufferSize)
      Construct a temporary database handle.
      DBHandle​(int requestBufferSize, long approxCacheSize)
      Construct a temporary database handle.
      DBHandle​(BufferFile bufferFile)
      Open the database contained within the specified bufferFile.
      DBHandle​(BufferFile bufferFile, boolean recover, TaskMonitor monitor)
      Open the database contained within the specified bufferFile.
      DBHandle​(java.io.File file)
      Open a specific buffer file containing a database for non-update use.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListener​(DBListener listener)
      Add Database listener
      boolean canRedo()
      Determine if there are any changes which can be redone
      boolean canUndo()
      Determine if there are any changes which can be undone.
      boolean canUpdate()
      Determine if this database can be updated.
      void checkTransaction()
      Verify that a valid transaction has been started.
      void close()
      Close the database and dispose of the underlying buffer manager.
      void close​(boolean keepRecoveryData)
      Close the database and dispose of the underlying buffer manager.
      void closeScratchPad()
      Close the scratch-pad database handle if it open.
      DBBuffer createBuffer​(int length)
      Create a new buffer with the specified length.
      DBBuffer createBuffer​(DBBuffer shadowBuffer)
      Create a new buffer that layers on top of another buffer.
      Table createTable​(java.lang.String name, Schema schema)
      Creates a new table with the given name, version and type.
      Table createTable​(java.lang.String name, Schema schema, int[] indexedColumns)
      Creates a new table with the given name, version and type.
      void deleteTable​(java.lang.String name)
      Delete the specified table from the database.
      void enablePreCache()
      Enable and start source file pre-cache if appropriate.
      boolean endTransaction​(long id, boolean commit)
      Terminate transaction.
      protected void finalize()  
      int getAvailableRedoCount()
      Returns the number of redo-able transactions
      int getAvailableUndoCount()
      Returns number of undo-able transactions
      DBBuffer getBuffer​(int id)
      Get an existing buffer.
      DBBuffer getBuffer​(int id, DBBuffer shadowBuffer)
      Get an existing buffer that uses a shadowBuffer for byte values if they haven't been explicitly changed in this buffer.
      int getBufferSize()
      Returns size of buffers utilized within the underlying buffer file.
      long getCacheHits()  
      long getCacheMisses()  
      long getDatabaseId()
      Returns unique database ID or 0 if this is an older read-only database.
      int getLowBufferCount()  
      LocalBufferFile getRecoveryChangeSetFile()
      Returns the recovery changeSet data file for reading or null if one is not available.
      DBHandle getScratchPad()
      Returns a shared temporary database handle.
      Table getTable​(java.lang.String name)
      Returns the Table that was created with the given name or null if no such table exists.
      int getTableCount()
      Return the number of tables defined within the master table.
      Table[] getTables()
      Get all tables defined within the database.
      boolean hasUncommittedChanges()
      Returns true if there are uncommitted changes to the database.
      boolean isChanged()
      Returns true if unsaved changes have been made.
      boolean isClosed()
      Returns true if this database handle has been closed.
      boolean isConsistent​(TaskMonitor monitor)
      Check the consistency of this database.
      boolean isTransactionActive()
      Returns true if transaction is currently active
      boolean rebuild​(TaskMonitor monitor)
      Rebuild database tables to resolve certain consistency problems.
      boolean redo()
      Redo previously undone transaction checkpoint.
      static void resetDatabaseId​(java.io.File file)
      Reset the database ID contained within the specified database file.
      void save​(java.lang.String comment, DBChangeSet changeSet, TaskMonitor monitor)
      Save this database to a new version.
      void saveAs​(BufferFile outFile, boolean associateWithNewFile, TaskMonitor monitor)
      Save the database to the specified buffer file.
      protected void saveAs​(BufferFile outFile, java.lang.Long newDatabaseId, TaskMonitor monitor)
      Save the database to the specified buffer file and a newDatabaseId.
      void saveAs​(java.io.File file, boolean associateWithNewFile, TaskMonitor monitor)
      Save the database to the specified buffer file.
      void setMaxUndos​(int maxUndos)
      Set the maximum number of undo transaction checkpoints maintained by the underlying buffer manager.
      boolean setTableName​(java.lang.String oldName, java.lang.String newName)  
      long startTransaction()
      Start a new transaction
      boolean takeRecoverySnapshot​(DBChangeSet changeSet, TaskMonitor monitor)
      Request a recovery snapshot be taken of any unsaved changes;
      void terminateTransaction​(long id, boolean commit)  
      boolean undo()
      Undo changes made during the previous transaction checkpoint.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

    • Constructor Detail

      • DBHandle

        public DBHandle()
         throws java.io.IOException
        Construct a temporary database handle. The saveAs method must be used to save the database.
        Throws:
        java.io.IOException

      • DBHandle

        public DBHandle​(int requestBufferSize)
         throws java.io.IOException
        Construct a temporary database handle. The saveAs method must be used to save the database.
        Throws:
        java.io.IOException

      • DBHandle

        public DBHandle​(int requestBufferSize,
                long approxCacheSize)
         throws java.io.IOException
        Construct a temporary database handle. The saveAs method must be used to save the database.
        Throws:
        java.io.IOException

      • DBHandle

        public DBHandle​(BufferFile bufferFile)
         throws java.io.IOException
        Open the database contained within the specified bufferFile. The update mode is determined by the buffer file.
        Parameters:
        bufferFile - database buffer file
        Throws:
        java.io.IOException - if IO error occurs

      • DBHandle

        public DBHandle​(BufferFile bufferFile,
                boolean recover,
                TaskMonitor monitor)
         throws java.io.IOException,
                CancelledException
        Open the database contained within the specified bufferFile. The update mode is determined by the buffer file.
        Parameters:
        bufferFile - database buffer file
        recover - if true an attempt will be made to recover unsaved data if the file is open for update
        monitor - recovery monitor
        Throws:
        java.io.IOException - if IO error occurs
        CancelledException

      • DBHandle

        public DBHandle​(java.io.File file)
         throws java.io.IOException
        Open a specific buffer file containing a database for non-update use. This method is provided primarily for testing.
        Parameters:
        file - buffer file
        Throws:
        java.io.IOException

    • Method Detail

      • rebuild

        public boolean rebuild​(TaskMonitor monitor)
                throws CancelledException
        Rebuild database tables to resolve certain consistency problems. Use of this method does not recover lost data which may have occurred during original database corruption.
        Returns:
        true if rebuild succeeded, else false
        Throws:
        CancelledException

      • resetDatabaseId

        public static void resetDatabaseId​(java.io.File file)
                            throws java.io.IOException
        Reset the database ID contained within the specified database file. This method is intended to be used when unpacking a packed database to ensure that a duplicate database ID does not exist within the project. WARNING! Use with extreme caution since this modifies the original file and could destroy data if used improperly.
        Parameters:
        file -
        Throws:
        java.io.IOException

      • getDatabaseId

        public long getDatabaseId()
        Returns unique database ID or 0 if this is an older read-only database.

      • 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.
        Throws:
        java.io.IOException

      • takeRecoverySnapshot

        public boolean takeRecoverySnapshot​(DBChangeSet changeSet,
                                    TaskMonitor monitor)
                             throws CancelledException,
                                    java.io.IOException
        Request a recovery snapshot be taken of any unsaved changes;
        Parameters:
        changeSet - an optional database-backed change set which reflects changes made since the last version.
        monitor - task monitor
        Returns:
        true if snapshot successful or not needed, false if an active transaction prevented snapshot
        Throws:
        CancelledException - if cancelled by monitor
        java.io.IOException

      • getScratchPad

        public DBHandle getScratchPad()
                       throws java.io.IOException
        Returns a shared temporary database handle. This temporary handle will remain open unitl either this handle is closed or closeScratchPad is invoked.
        Throws:
        java.io.IOException

      • closeScratchPad

        public void closeScratchPad()
        Close the scratch-pad database handle if it open.

      • addListener

        public void addListener​(DBListener listener)
        Add Database listener
        Parameters:
        listener -

      • enablePreCache

        public void enablePreCache()
        Enable and start source file pre-cache if appropriate. WARNING! EXPERIMENTAL !!!

      • isTransactionActive

        public boolean isTransactionActive()
        Returns true if transaction is currently active

      • startTransaction

        public long startTransaction()
        Start a new transaction
        Returns:
        transaction ID

      • endTransaction

        public boolean endTransaction​(long id,
                              boolean commit)
                       throws java.io.IOException
        Terminate transaction. If commit is false, Table instances may be added or removed/invalidated.
        Parameters:
        id - transaction ID
        commit - if true a new checkpoint will be established, if false all changes since the previous checkpoint will be discarded.
        Returns:
        true if new checkpoint established.
        Throws:
        java.io.IOException

      • hasUncommittedChanges

        public boolean hasUncommittedChanges()
        Returns true if there are uncommitted changes to the database.
        Returns:
        true if there are uncommitted changes to the database.

      • terminateTransaction

        public void terminateTransaction​(long id,
                                 boolean commit)
                          throws java.io.IOException
        Throws:
        java.io.IOException

      • canUndo

        public boolean canUndo()
        Determine if there are any changes which can be undone.
        Returns:
        true if an undo can be performed.

      • undo

        public boolean undo()
             throws java.io.IOException
        Undo changes made during the previous transaction checkpoint. All upper-levels must clear table-based cached data prior to invoking this method.
        Returns:
        true if an undo was successful
        Throws:
        java.io.IOException

      • getAvailableUndoCount

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

      • getAvailableRedoCount

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

      • canRedo

        public boolean canRedo()
        Determine if there are any changes which can be redone
        Returns:
        true if a redo can be performed.

      • redo

        public boolean redo()
             throws java.io.IOException
        Redo previously undone transaction checkpoint. Moves forward by one checkpoint only. All upper-levels must clear table-based cached data prior to invoking this method.
        Returns:
        boolean
        Throws:
        java.io.IOException

      • setMaxUndos

        public void setMaxUndos​(int maxUndos)
        Set the maximum number of undo transaction checkpoints maintained by the underlying buffer manager.
        Parameters:
        maxUndos - maximum number of undo checkpoints. An illegal value restores the default value.

      • getTableCount

        public int getTableCount()
        Return the number of tables defined within the master table.
        Returns:
        int number of tables.

      • close

        public void close()
        Close the database and dispose of the underlying buffer manager. Any existing recovery data will be discarded.

      • close

        public void close​(boolean keepRecoveryData)
        Close the database and dispose of the underlying buffer manager.
        Parameters:
        keepRecoveryData -

      • isChanged

        public boolean isChanged()
        Returns true if unsaved changes have been made.

      • isClosed

        public boolean isClosed()
        Returns true if this database handle has been closed.

      • save

        public void save​(java.lang.String comment,
                 DBChangeSet changeSet,
                 TaskMonitor monitor)
          throws java.io.IOException,
                 CancelledException
        Save this database to a new version.
        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 - progress monitor
        Throws:
        CancelledException - if task monitor cancelled operation.
        java.io.IOException - thrown if an IO error occurs.

      • saveAs

        public void saveAs​(BufferFile outFile,
                   boolean associateWithNewFile,
                   TaskMonitor monitor)
            throws java.io.IOException,
                   CancelledException
        Save the database to the specified buffer file.
        Parameters:
        outFile - buffer file open for writing
        associateWithNewFile - if true the outFile will be associated with this DBHandle as the current source file, if false no change will be made to this DBHandle's state and the outFile will be written and set as read-only. The caller is responsbile for disposing the outFile if this parameter is false.
        monitor - progress monitor
        associateWithNewFile - if true this handle will be associated with the new file
        Throws:
        java.io.IOException - if IO error occurs
        CancelledException - if monitor cancels operation

      • saveAs

        protected void saveAs​(BufferFile outFile,
                      java.lang.Long newDatabaseId,
                      TaskMonitor monitor)
               throws java.io.IOException,
                      CancelledException
        Save the database to the specified buffer file and a newDatabaseId. Open handle will always be associated with the new file. NOTE: This method is intended for use in transforming one database to match another existing database.
        Parameters:
        outFile - buffer file open for writing
        newDatabaseId - database ID to be forced for new database or null to generate new database ID
        monitor - progress monitor
        associateWithNewFile - if true this handle will be associated with the new file
        Throws:
        java.io.IOException - if IO error occurs
        CancelledException - if monitor cancels operation

      • saveAs

        public void saveAs​(java.io.File file,
                   boolean associateWithNewFile,
                   TaskMonitor monitor)
            throws java.io.IOException,
                   CancelledException
        Save the database to the specified buffer file.
        Parameters:
        file - buffer file to be created
        associateWithNewFile - if true the outFile will be associated with this DBHandle as the current source file, if false no change will be made to this DBHandle's state and the outFile will be written and set as read-only. The caller is responsbile for disposing the outFile if this parameter is false.
        monitor - progress monitor
        Throws:
        DuplicateFileException - if file already exists.
        java.io.IOException - if IO error occurs
        CancelledException - if monitor cancels operation

      • createBuffer

        public DBBuffer createBuffer​(int length)
                      throws java.io.IOException
        Create a new buffer with the specified length. This method may only be invoked while a database transaction is in progress. A database transaction must also be in progress when invoking the various put, delete and setSize methods on the returned buffer.
        Parameters:
        length - the size of the buffer to create
        Returns:
        Buffer the newly created buffer
        Throws:
        java.io.IOException - if an I/O error occurs while creating the buffer.

      • createBuffer

        public DBBuffer createBuffer​(DBBuffer shadowBuffer)
                      throws java.io.IOException
        Create a new buffer that layers on top of another buffer. This buffer will return values from the shadowBuffer unless they have been changed in this buffer. This method may only be invoked while a database transaction is in progress. A database transaction must also be in progress when invoking the various put, delete and setSize methods on the returned buffer.
        Parameters:
        shadowBuffer - the source of the byte values to use unless they have been changed.
        Returns:
        Buffer the newly created buffer
        Throws:
        java.io.IOException - if an I/O error occurs while creating the buffer.

      • getBuffer

        public DBBuffer getBuffer​(int id)
                   throws java.io.IOException
        Get an existing buffer. This method should be used with care to avoid providing an improper id. A database transaction must be in progress when invoking the various put, delete and setSize methods on the returned buffer.
        Parameters:
        id - the buffer id.
        Returns:
        Buffer the buffer associated with the given id.
        Throws:
        java.io.IOException - if an I/O error occurs while getting the buffer.

      • getBuffer

        public DBBuffer getBuffer​(int id,
                          DBBuffer shadowBuffer)
                   throws java.io.IOException
        Get an existing buffer that uses a shadowBuffer for byte values if they haven't been explicitly changed in this buffer. This method should be used with care to avoid providing an improper id. A database transaction must be in progress when invoking the various put, delete and setSize methods on the returned buffer.
        Parameters:
        id - the buffer id.
        shadowBuffer - the buffer to use for byte values if they haven't been changed in this buffer.
        Returns:
        Buffer the buffer associated with the given id.
        Throws:
        java.io.IOException - if an I/O error occurs while getting the buffer.

      • canUpdate

        public boolean canUpdate()
        Determine if this database can be updated.
        Returns:
        true if this database handle is intended for update

      • getTable

        public Table getTable​(java.lang.String name)
        Returns the Table that was created with the given name or null if no such table exists.

      • getTables

        public Table[] getTables()
        Get all tables defined within the database.
        Returns:
        Table[] tables

      • createTable

        public Table createTable​(java.lang.String name,
                         Schema schema)
                  throws java.io.IOException
        Creates a new table with the given name, version and type.
        Throws:
        java.io.IOException

      • createTable

        public Table createTable​(java.lang.String name,
                         Schema schema,
                         int[] indexedColumns)
                  throws java.io.IOException
        Creates a new table with the given name, version and type. Create secondary indexes as specified by the array of column indexes.
        Throws:
        java.io.IOException

      • deleteTable

        public void deleteTable​(java.lang.String name)
                 throws java.io.IOException
        Delete the specified table from the database.
        Parameters:
        name - table name
        Throws:
        java.io.IOException - if there is an I/O error or the table does not exist

      • getCacheHits

        public long getCacheHits()
        Returns:
        number of buffer cache hits

      • getCacheMisses

        public long getCacheMisses()
        Returns:
        number of buffer cache misses

      • getLowBufferCount

        public int getLowBufferCount()
        Returns:
        low water mark (minimum buffer pool size)

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable

      • getBufferSize

        public int getBufferSize()
        Returns size of buffers utilized within the underlying buffer file. This may be larger than than the requested buffer size. This value may be used to instatiate a new BufferFile which is compatible with this database when using the saveAs method.