|
Side of Software Persistence Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object sos.db.AbstractDatabase
public abstract class AbstractDatabase
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
.
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 |
---|
public AbstractDatabase()
AbstractDatabase
.
Method Detail |
---|
public void abortTransaction()
Database
abortTransaction
in interface Database
Database.commitTransaction(sos.db.Progress)
,
Database.startTransaction()
,
Database.isOpen()
public java.lang.Object addObject(java.lang.Object object) throws TransactionAbortedException
Database
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.
addObject
in interface Database
object
- object to add to the database
object
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.Database.containsObject(java.lang.Object)
,
Database.isOpen()
,
Database.startTransaction()
,
Database.commitTransaction(sos.db.Progress)
public void close() throws java.io.IOException
Database
close
in interface Database
java.io.IOException
- if an I/O error occurspublic void commitTransaction(Progress progress) throws TransactionAbortedException
Database
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 TransactionAbortenull
dException.
commitTransaction
in interface Database
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)
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.Database.startTransaction()
,
Database.abortTransaction()
,
Database.isOpen()
public boolean containsObject(java.lang.Object object)
Database
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.
containsObject
in interface Database
object
- the object to check for containment
true
if this database contains object
Database.addObject(java.lang.Object)
,
Database.isOpen()
public boolean create(java.lang.Object root) throws java.io.IOException
Database
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.
create
in interface Database
root
- the root of this database
true
if this database does not exist and is successfully created;
false
if this database already exists
java.io.IOException
- if an I/O error occursDatabase.getRoot()
public boolean delete() throws java.io.IOException
Database
delete
in interface Database
true
if this database is successfully deleted
java.io.IOException
- if an I/O error occursDatabase.close()
,
Database.isOpen()
protected abstract void doAbortTransaction() throws TransactionAbortedException
abortTransaction
. This method is called
inside abortTransaction
if this database is in
an acceptable state. It has the same semantics as
abortTransaction
.
NoTransactionException
- if the calling thread does not have an
active transaction
TransactionAbortedException
abortTransaction()
protected abstract java.lang.Object doAddObject(java.lang.Object object) throws TransactionAbortedException
addObject
. This method is called
inside addObject
if this database is in
an acceptable state. It has the same semantics as
addObject
.
object
- object to add to the database
object
java.lang.NullPointerException
- if object
is null
TransactionAbortedException
- if this database cannot add object
and the transaction has been aborted as a resultaddObject(java.lang.Object)
protected abstract void doClose() throws java.io.IOException
close
. This method is called
inside close
if this database is in
an acceptable state. It has the same semantics as
close
.
java.io.IOException
- if an I/O error occursclose()
protected abstract void doCommitTransaction(Progress progress) throws TransactionAbortedException
commitTransaction
. This method is called
inside commitTransaction
if this database is in
an acceptable state. It has the same semantics as
commitTransaction
.
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)
NoTransactionException
- if the calling thread does not have an
active transaction
TransactionAbortedException
- if this database cannot commit
the transaction or if the progress is canceledcommitTransaction(sos.db.Progress)
protected abstract boolean doContainsObject(java.lang.Object object)
containsObject
. This method is called
inside containsObject
if this database is in
an acceptable state. It has the same semantics as
containsObject
.
object
- the object to check for containment
true
if this database contains object
protected abstract boolean doCreate(java.lang.Object root) throws java.io.IOException
create
. This method is called
inside create
if this database is in
an acceptable state. It has the same semantics as
create
.
root
- the root of this database
true
if this database does not exist and was successfully created;
false
if this database already exists
java.io.IOException
- if an I/O error occurs
java.lang.NullPointerException
- if root
is null
and this
database does not allow a null
rootcreate(java.lang.Object)
protected abstract boolean doDelete() throws java.io.IOException
delete
. This method is called
inside delete
if this database is in
an acceptable state. It has the same semantics as
delete
.
true
if this database is successfully deleted
java.io.IOException
- if an I/O error occursdelete()
protected abstract boolean doExists()
exists
. This method is called
inside exists
if this database is in
an acceptable state. It has the same semantics as
exists
.
true
if this database existsexists()
protected abstract java.lang.Object doGetRoot() throws TransactionAbortedException
getRoot
. This method is called
inside getRoot
if this database is in
an acceptable state. It has the same semantics as
getRoot
.
null
)
TransactionAbortedException
- if the root object cannot
be retrieved and the transaction has been aborted as a result.getRoot()
protected abstract void doOpen(boolean readOnly) throws java.io.IOException
open
. This method is called
inside open
if this database is in
an acceptable state. It has the same semantics as
open
.
readOnly
- true
if database updates are not allowed
java.io.IOException
- if an I/O error occursopen
protected abstract void doStartTransaction() throws TransactionAbortedException
startTransaction
. This method is called
inside startTransaction
if this database is in
an acceptable state. It has the same semantics as
startTransaction
.
TransactionAbortedException
- if the transaction cannot
be startedstartTransaction()
protected abstract int doTransactionDepth()
transactionDepth
. This method is called
inside transactionDepth
if this database is in
an acceptable state. It has the same semantics as
transactionDepth
.
transactionDepth()
public boolean exists()
Database
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
.
exists
in interface Database
true
if this database existsDatabase.open(boolean)
public java.lang.Object getRoot() throws TransactionAbortedException
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.
getRoot
in interface Database
null
)
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.Database.create(java.lang.Object)
,
Database.isOpen()
public boolean isOpen()
Database
true
if this database is open and ready to accept
requests.
isOpen
in interface Database
true
if this database is openDatabase.open(boolean)
,
Database.close()
public void open(boolean readOnly) throws java.io.IOException
Database
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.
open
in interface Database
readOnly
- true
if database updates are not allowed
java.io.IOException
- if an I/O error occursDatabase.exists()
public void startTransaction() throws TransactionAbortedException
Database
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.
startTransaction
in interface Database
TransactionAbortedException
- if the transaction cannot
be started. The cause of the exception
can be obtained with getCause
.
This exception is intended to be caught.Database.abortTransaction()
,
Database.commitTransaction(sos.db.Progress)
,
Database.isOpen()
public int transactionDepth()
Database
transactionDepth
in interface Database
|
Side of Software Persistence Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |