Package db

Class DBHandle

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

Modifier and Type	Field	Description
protected BufferMgr	bufferMgr

Constructor Summary

Constructors

Constructor	Description
DBHandle()	Construct a temporary database handle.
DBHandle(int requestedBufferSize)	Construct a temporary database handle.
DBHandle(int requestedBufferSize, 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

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 and schema.
Table	createTable(java.lang.String name, Schema schema, int[] indexedColumns)	Creates a new table with the given name and schema.
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()
int	getAvailableUndoCount()
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()
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()
boolean	isClosed()
boolean	isConsistent(TaskMonitor monitor)	Check the consistency of this database.
boolean	isTransactionActive()
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)	Changes the name of an existing table.
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

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 - if a IO error occurs

DBHandle

public DBHandle(int requestedBufferSize)
         throws java.io.IOException

Construct a temporary database handle. The saveAs method must be used to save the database.

Parameters:

requestedBufferSize - requested buffer size. Actual buffer size may vary.

Throws:

java.io.IOException - if a IO error occurs

DBHandle

public DBHandle(int requestedBufferSize,
                long approxCacheSize)
         throws java.io.IOException

Construct a temporary database handle. The saveAs method must be used to save the database.

Parameters:

requestedBufferSize - requested buffer size. Actual buffer size may vary.

approxCacheSize - approximate size of cache in Bytes.

Throws:

java.io.IOException - if a IO error occurs

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 - if buffer file recovery is cancelled

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 - if IO error occurs

Method Detail

isConsistent

public boolean isConsistent(TaskMonitor monitor)
                     throws CancelledException

Check the consistency of this database.

Parameters:

monitor - task monitor

Returns:

true if consistency check passed, else false

Throws:

CancelledException - if consistency check is cancelled

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.

Parameters:

monitor - task monitor

Returns:

true if rebuild succeeded, else false

Throws:

CancelledException - if rebuild is cancelled

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 - database buffer file to be updated

Throws:

java.io.IOException - if IO error occurs

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.

Returns:

recovery changeSet data file for reading or null if one is not available.

Throws:

java.io.IOException - if IO error occurs

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 - if IO error occurs

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.

Returns:

shared temporary database handle.

Throws:

java.io.IOException - if IO error occurs

closeScratchPad

public void closeScratchPad()

Close the scratch-pad database handle if it open.

addListener

public void addListener(DBListener listener)

Add Database listener

Parameters:

listener - database 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

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 - if IO error occurs

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 - if IO error occurs

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 - if IO error occurs

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 - true if existing recovery data should be retained or false to remove any recovery data

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

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

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.

Parameters:

name - of requested table

Returns:

table instance or null if not found

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 and schema.

Parameters:

name - table name

schema - table schema

Returns:

new table instance

Throws:

java.io.IOException - if IO error occurs during table creation

createTable

public Table createTable(java.lang.String name,
                         Schema schema,
                         int[] indexedColumns)
                  throws java.io.IOException

Creates a new table with the given name and schema. Create secondary indexes as specified by the array of column indexes.

Parameters:

name - table name

schema - table schema

indexedColumns - array of column indices which should have an index associated with them

Returns:

new table instance

Throws:

java.io.IOException - if IO error occurs during table creation

setTableName

public boolean setTableName(java.lang.String oldName,
                            java.lang.String newName)
                     throws DuplicateNameException

Changes the name of an existing table.

Parameters:

oldName - the old name of the table

newName - the new name of the table

Returns:

true if the name was changed successfully

Throws:

DuplicateNameException - if a table with the new name already exists

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.

Returns:

buffer size utilized by this database