sos.db
Class AbstractDatabase

java.lang.Object
  sos.db.AbstractDatabase

All Implemented Interfaces:

Database

Direct Known Subclasses:

AbstractSerializationDatabase

public abstract class AbstractDatabase
extends java.lang.Object
implements Database

A partial implementation of a database.

This abstract class handles the state of a database. Subclasses must implement the following methods, which are named "do" plus the name of the Database methods:

• void doAbortTransaction()
• Object doAddObject( Object )
• void doClose() throws IOException
• void doCommitTransaction()
• boolean doContainsObject( Object )
• boolean doCreate( Object ) throws IOException
• boolean doDelete() throws IOException
• boolean doExists()
• Object doGetRoot()
• void doOpen( boolean ) throws IOException
• void doStartTransaction()
• int doTransactionDepth()

These methods are invoked only when the database is in the appropriate state. If the database is not in the appropriate state, then this class throws an IllegalStateException.

Since:

1.0

See Also:

Database

Field Summary

Fields inherited from interface sos.db.Database

logger

Constructor Summary

AbstractDatabase()
Creates a new instance of AbstractDatabase.

Method Summary

void	abortTransaction() Aborts all changes under the calling thread's current transaction.
java.lang.Object	addObject(java.lang.Object object) Adds the specified object to this database and returns a proxy object that the client should use instead.
void	close() Closes this database.
void	commitTransaction(Progress progress) Commits all changes under the calling thread's current transaction.
boolean	containsObject(java.lang.Object object) Returns true if this database contains the specified object.
boolean	create(java.lang.Object root) Creates a new database if and only if it does not exist.
boolean	delete() Deletes this database.
protected abstract void	doAbortTransaction() Performs the action of abortTransaction.
protected abstract java.lang.Object	doAddObject(java.lang.Object object) Performs the action of addObject.
protected abstract void	doClose() Performs the action of close.
protected abstract void	doCommitTransaction(Progress progress) Performs the action of commitTransaction.
protected abstract boolean	doContainsObject(java.lang.Object object) Performs the action of containsObject.
protected abstract boolean	doCreate(java.lang.Object root) Performs the action of create.
protected abstract boolean	doDelete() Performs the action of delete.
protected abstract boolean	doExists() Performs the action of exists.
protected abstract java.lang.Object	doGetRoot() Performs the action of getRoot.
protected abstract void	doOpen(boolean readOnly) Performs the action of open.
protected abstract void	doStartTransaction() Performs the action of startTransaction.
protected abstract int	doTransactionDepth() Performs the action of transactionDepth.
boolean	exists() Returns true if this database exists.
java.lang.Object	getRoot() Returns the root object of this database.
boolean	isOpen() Returns true if this database is open and ready to accept requests.
void	open(boolean readOnly) Opens this database.
void	startTransaction() Starts a new (potentially nested) transaction for the calling thread.
int	transactionDepth() Returns the nesting depth of the transaction associated with the current thread.

Methods inherited from class java.lang.Object

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

Methods inherited from interface sos.db.Database

getName, getTransactionPolicy

Constructor Detail

AbstractDatabase

public AbstractDatabase()

Creates a new instance of AbstractDatabase.

Method Detail

abortTransaction

public void abortTransaction()

Description copied from interface: Database

Aborts all changes under the calling thread's current transaction. The state of the system is "rolled back" to that prior to the start of the transaction. The parent transaction (if any) is not affected.

Specified by:

abortTransaction in interface Database

See Also:

Database.commitTransaction(sos.db.Progress), Database.startTransaction(), Database.isOpen()

addObject

public java.lang.Object addObject(java.lang.Object object)
                           throws TransactionAbortedException

Description copied from interface: Database

Adds the specified object to this database and returns a proxy object that the client should use instead. Any subsequent changes to the original object may cause the database to be in an inconsistent state. It is essential to only update the original object through the returned proxy object.

The proxy object will implement the same interfaces as object. Specifically, the interfaces returned by invoking getClass().getInterfaces() on the proxy object will be (in order) the interfaces implemented by the top-most superclass, the interfaces of the next lower superclass, etc. down to the interfaces of the object's class. Also, an interface will not be listed again if a superclass implements the same interface.

Any updates made to the proxy object will get propagated to the original object and the changes will automatically get saved in the database when the top-most transaction enclosing the updates commits.

The object will be automatically removed from this database after it becomes unreachable.

If there is no active transaction for the calling thread, addObject is atomic only with itself. That is, it is as if startTransaction is invoked immediately before the call to addObject and commitTransaction immediately after.

Specified by:

addObject in interface Database

Parameters:

object - object to add to the database

Returns:

a proxy object that implements the same interfaces as object

Throws:

TransactionAbortedException - if this database cannot add object and the transaction has been aborted as a result. The cause of the abort can be obtained with getCause. This exception is intended to be caught.

See Also:

Database.containsObject(java.lang.Object), Database.isOpen(), Database.startTransaction(), Database.commitTransaction(sos.db.Progress)

close

public void close()
           throws java.io.IOException

Description copied from interface: Database

Closes this database. It is the client's responsibilty to ensure that all active transactions have finished.

Specified by:

close in interface Database

Throws:

java.io.IOException - if an I/O error occurs

commitTransaction

public void commitTransaction(Progress progress)
                       throws TransactionAbortedException

Description copied from interface: Database

Commits all changes under the calling thread's current transaction. The changes are guaranteed to persist only if the transaction is a top- level transaction. If the transaction's parent later aborts, the commit will change to an abort.

Callers of this method have a chance to follow the method's progress and to suggest an abort in the middle of committing. A custom Progress parameter can be passed in to update a progress bar in the user interface or to respond to a cancel button, for example. If the progress is canceled, this method aborts with a TransactionAbortenulldException.

Specified by:

commitTransaction in interface Database

Parameters:

progress - an object to be updated and checked while the commit is in progress (may be null to indicate that no updating/checking is necessary)

Throws:

TransactionAbortedException - if this database cannot commit the transaction or if the progress is canceled. The cause of the abort can be obtained with getCause. This exception is intended to be caught.

See Also:

Database.startTransaction(), Database.abortTransaction(), Database.isOpen()

containsObject

public boolean containsObject(java.lang.Object object)

Description copied from interface: Database

Returns true if this database contains the specified object. object must be a proxy object returned by addObject in order for the method to return true. If object is null, the method returns false. If this database is closed, then the method throws an IllegalStateException.

No transactions are used or created when checking for containment, so TransactionAbortedException is never thrown.

Specified by:

containsObject in interface Database

Parameters:

object - the object to check for containment

Returns:

true if this database contains object

See Also:

Database.addObject(java.lang.Object), Database.isOpen()

create

public boolean create(java.lang.Object root)
               throws java.io.IOException

Description copied from interface: Database

Creates a new database if and only if it does not exist.

The root object should be an index-type object (like a map) that will hold references to objects added to this database. The primary way to retrieve database objects is through this root object.

After the invocation of this method, clients should no longer reference root. They should instead invoke getRoot and reference the returned object.

Specified by:

create in interface Database

Parameters:

root - the root of this database

Returns:

true if this database does not exist and is successfully created; false if this database already exists

Throws:

java.io.IOException - if an I/O error occurs

See Also:

Database.getRoot()

delete

public boolean delete()
               throws java.io.IOException

Description copied from interface: Database

Deletes this database. This database must already by unopened or closed. All system resources pertaining to this database (such as data, index, or log files) are deleted.

Specified by:

delete in interface Database

Returns:

true if this database is successfully deleted

Throws:

java.io.IOException - if an I/O error occurs

See Also:

Database.close(), Database.isOpen()

doAbortTransaction

protected abstract void doAbortTransaction()
                                    throws TransactionAbortedException

Performs the action of abortTransaction. This method is called inside abortTransaction if this database is in an acceptable state. It has the same semantics as abortTransaction.

Throws:

NoTransactionException - if the calling thread does not have an active transaction

TransactionAbortedException

See Also:

abortTransaction()

doAddObject

protected abstract java.lang.Object doAddObject(java.lang.Object object)
                                         throws TransactionAbortedException

Performs the action of addObject. This method is called inside addObject if this database is in an acceptable state. It has the same semantics as addObject.

Parameters:

object - object to add to the database

Returns:

a proxy object that implements the same interfaces as object

Throws:

java.lang.NullPointerException - if object is null

TransactionAbortedException - if this database cannot add object and the transaction has been aborted as a result

See Also:

addObject(java.lang.Object)

doClose

protected abstract void doClose()
                         throws java.io.IOException

Performs the action of close. This method is called inside close if this database is in an acceptable state. It has the same semantics as close.

Throws:

java.io.IOException - if an I/O error occurs

See Also:

close()

doCommitTransaction

protected abstract void doCommitTransaction(Progress progress)
                                     throws TransactionAbortedException

Performs the action of commitTransaction. This method is called inside commitTransaction if this database is in an acceptable state. It has the same semantics as commitTransaction.

Parameters:

progress - an object to be updated and checked while the commit is in progress (may be null to indicate that no updating/checking is necessary)

Throws:

NoTransactionException - if the calling thread does not have an active transaction

TransactionAbortedException - if this database cannot commit the transaction or if the progress is canceled

See Also:

commitTransaction(sos.db.Progress)

doContainsObject

protected abstract boolean doContainsObject(java.lang.Object object)

Performs the action of containsObject. This method is called inside containsObject if this database is in an acceptable state. It has the same semantics as containsObject.

Parameters:

object - the object to check for containment

Returns:

true if this database contains object

Since:

2.0

doCreate

protected abstract boolean doCreate(java.lang.Object root)
                             throws java.io.IOException

Performs the action of create. This method is called inside create if this database is in an acceptable state. It has the same semantics as create.

Parameters:

root - the root of this database

Returns:

true if this database does not exist and was successfully created; false if this database already exists

Throws:

java.io.IOException - if an I/O error occurs

java.lang.NullPointerException - if root is null and this database does not allow a null root

See Also:

create(java.lang.Object)

doDelete

protected abstract boolean doDelete()
                             throws java.io.IOException

Performs the action of delete. This method is called inside delete if this database is in an acceptable state. It has the same semantics as delete.

Returns:

true if this database is successfully deleted

Throws:

java.io.IOException - if an I/O error occurs

See Also:

delete()

doExists

protected abstract boolean doExists()

Performs the action of exists. This method is called inside exists if this database is in an acceptable state. It has the same semantics as exists.

Returns:

true if this database exists

See Also:

exists()

doGetRoot

protected abstract java.lang.Object doGetRoot()
                                       throws TransactionAbortedException

Performs the action of getRoot. This method is called inside getRoot if this database is in an acceptable state. It has the same semantics as getRoot.

Returns:

this database's root object (may be null)

Throws:

TransactionAbortedException - if the root object cannot be retrieved and the transaction has been aborted as a result.

See Also:

getRoot()

doOpen

protected abstract void doOpen(boolean readOnly)
                        throws java.io.IOException

Performs the action of open. This method is called inside open if this database is in an acceptable state. It has the same semantics as open.

Parameters:

readOnly - true if database updates are not allowed

Throws:

java.io.IOException - if an I/O error occurs

See Also:

open

doStartTransaction

protected abstract void doStartTransaction()
                                    throws TransactionAbortedException

Performs the action of startTransaction. This method is called inside startTransaction if this database is in an acceptable state. It has the same semantics as startTransaction.

Throws:

TransactionAbortedException - if the transaction cannot be started

See Also:

startTransaction()

doTransactionDepth

protected abstract int doTransactionDepth()

Performs the action of transactionDepth. This method is called inside transactionDepth if this database is in an acceptable state. It has the same semantics as transactionDepth.

Returns:

the nesting depth of the transaction associated with the current thread

See Also:

transactionDepth()

exists

public boolean exists()

Description copied from interface: Database

Returns true if this database exists. To exist, a database normally has to have been initialized with create. Normally, when a database exists, a call to open will put it in a state where it is ready to accept database operations such as addObject and getRoot.

Specified by:

exists in interface Database

Returns:

true if this database exists

See Also:

Database.open(boolean)

getRoot

public java.lang.Object getRoot()
                         throws TransactionAbortedException

Description copied from interface: Database

Returns the root object of this database.

This object may not be the same object provided in the original invocation of create; however, it will implement the same interfaces and forward any requests to the original object.

Specified by:

getRoot in interface Database

Returns:

this database's root object (may be null)

Throws:

TransactionAbortedException - if the root object cannot be retrieved and the transaction has been aborted as a result. The cause of the abort can be obtained with getCause. This exception is intended to be caught.

See Also:

Database.create(java.lang.Object), Database.isOpen()

isOpen

public boolean isOpen()

Description copied from interface: Database

Returns true if this database is open and ready to accept requests.

Specified by:

isOpen in interface Database

Returns:

true if this database is open

See Also:

Database.open(boolean), Database.close()

open

public void open(boolean readOnly)
          throws java.io.IOException

Description copied from interface: Database

Opens this database. If this database exists, calling open puts it into a state where it can accept database operations such as addObject and getRoot. If this database does not exists, this method throws an IllegalStateException. If this database is already open, no change to the database occurs.

Specified by:

open in interface Database

Parameters:

readOnly - true if database updates are not allowed

Throws:

java.io.IOException - if an I/O error occurs

See Also:

Database.exists()

startTransaction

public void startTransaction()
                      throws TransactionAbortedException

Description copied from interface: Database

Starts a new (potentially nested) transaction for the calling thread. The transaction lasts until a matching call to commitTransaction or abortTransaction by the same thread. A call to startTransaction by the same thread before the transaction finishes starts a nested transaction with the original transaction as its parent. Nested transactions are started and stopped in a stack-like fashion.

All operations on database objects during a transaction are treated as a single atomic operation with respect to this database. An application should use transactions like it would the synchronized statement.

Specified by:

startTransaction in interface Database

Throws:

TransactionAbortedException - if the transaction cannot be started. The cause of the exception can be obtained with getCause. This exception is intended to be caught.

See Also:

Database.abortTransaction(), Database.commitTransaction(sos.db.Progress), Database.isOpen()

transactionDepth

public int transactionDepth()

Description copied from interface: Database

Returns the nesting depth of the transaction associated with the current thread.

Specified by:

transactionDepth in interface Database

Returns:

the nesting depth of the transaction associated with the current thread