java.lang.Object
- db.DBHandle

Direct Known Subclasses:

PackedDBHandle
```
public class DBHandle
extends java.lang.Object
```
DBHandle provides access to an open database.

Field Summary

Fields
Change Modifier and Type Field Description

NEW protected BufferMgr bufferMgr

Constructor Summary

Constructors
Change	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
Change	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.
	`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.
NEW	`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.
	`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.
NEW	`protected 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.
NEW	`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
  - bufferMgr NEW
    
    protected BufferMgr bufferMgr

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
- isConsistent
```
public boolean isConsistent(TaskMonitor monitor)
                     throws CancelledException
```
  Check the consistency of this database.
  
  Returns:
  
  true if consistency check passed, else false
  
  Throws:
  
  CancelledException
- 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 !!!
- checkTransaction
```
public void checkTransaction()
```
  Verify that a valid transaction has been started.
  
  Throws:
  
  NoTransactionException - if transaction has not been started
  
  TerminatedTransactionException - transaction was prematurely terminated
- isTransactionActive NEW
```
protected 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 NEW
```
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 -
  
  Returns:
  
  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
  
  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
- setTableName
```
public boolean setTableName(java.lang.String oldName,
                            java.lang.String newName)
                     throws DuplicateNameException
```
  Parameters:
  
  table -
  
  id -
  
  Throws:
  
  DuplicateNameException
- 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 NEW
```
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.

Class DBHandle

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

bufferMgr NEW

Constructor Detail

DBHandle

DBHandle

DBHandle

DBHandle

DBHandle

DBHandle

Method Detail

isConsistent

rebuild

resetDatabaseId

getDatabaseId

getRecoveryChangeSetFile

takeRecoverySnapshot

getScratchPad

closeScratchPad

addListener

enablePreCache

checkTransaction

isTransactionActive NEW

startTransaction

endTransaction

hasUncommittedChanges

terminateTransaction

canUndo

undo

getAvailableUndoCount

getAvailableRedoCount

canRedo

redo

setMaxUndos

getTableCount

close

close

isChanged

isClosed

save

saveAs

saveAs NEW

saveAs

createBuffer

getBuffer

canUpdate

getTable

getTables

createTable

createTable

setTableName

deleteTable

getCacheHits

getCacheMisses

getLowBufferCount

finalize NEW

getBufferSize