Side of Software
Persistence Library 2.0

sos.db
Class AbstractDatabase

java.lang.Object
  extended by 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:

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

Side of Software
Persistence Library 2.0

Copyright 2004-08 Side of Software (SOS). All rights reserved.