fabric.store.db

Class ObjectDB

java.lang.Object

fabric.store.db.ObjectDB

Direct Known Subclasses:

BdbDB, MemoryDB

public abstract class ObjectDB
extends java.lang.Object

An ObjectDB encapsulates the persistent state of the Store. It is responsible for storing and retrieving objects, and also for checking permissions.

The ObjectDB interface is designed to support a two-phase commit protocol. Consequently to insert or modify an object, users must first call the prepare() method, passing in the set of objects to update. These objects will be stored, but will remain unavailable until the commit() method is called with the returned transaction identifier.

In general, implementations of ObjectDB are not thread-safe. Only TransactionManager should be interacting directly with ObjectDB implementations; it is responsible for ensuring safe use of ObjectDB.

All ObjectDB implementations should provide a constructor which takes the name of the store and its private key, and opens the appropriate back-end database if it exists, or creates it if it doesn't exist.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ObjectDB.PendingTransaction The data stored for a partially prepared transaction.
static class	ObjectDB.UpdateMode

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	name The store's name.
protected ConcurrentLongKeyMap<OidKeyHashMap<ObjectDB.PendingTransaction>>	pendingByTid The table of partially prepared transactions.
protected ConcurrentLongKeyMap<fabric.store.db.ObjectLocks>	rwLocks Maps onums to ObjectLocks.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ObjectDB(java.lang.String name, java.security.PrivateKey privateKey)

Method Summary

Modifier and Type	Method and Description
void	abortPrepare(long tid, Principal worker) Rolls back a partially prepared transaction.
void	beginTransaction(long tid, Principal worker) Opens a new transaction.
abstract void	close() Gracefully shuts down the object database.
abstract void	commit(long tid, RemoteIdentity<RemoteWorker> workerIdentity, SubscriptionManager sm) Causes the objects prepared in transaction [tid] to be committed.
void	ensureInit() Ensures that the object database has been properly initialized.
abstract boolean	exists(long onum) Checks whether an object with the corresponding onum exists, in either prepared or committed form.
abstract void	finishPrepare(long tid, Principal worker) Notifies the database that the given transaction is finished preparing.
java.lang.String	getName() Returns the name of this store.
int	getVersion(long onum) Returns the version number on the object stored at a particular onum.
protected abstract boolean	isInitialized() Determines whether the object database has been initialized.
boolean	isPrepared(long onum, long tid) Determines whether an onum has an outstanding uncommitted conflicting change or read.
boolean	isWritten(long onum) Determines whether an onum has outstanding uncommitted changes.
abstract long[]	newOnums(int num) Returns a set of onums that aren't currently occupied.
protected void	notifyCommittedUpdate(SubscriptionManager sm, long onum, RemoteWorker worker) Performs operations in response to a committed object update.
void	prepareRead(long tid, Principal worker, long onum, int version, LongKeyMap<SerializedObject> versionConflicts) Prepares a read against the database.
void	prepareUpdate(long tid, Principal worker, SerializedObject obj, LongKeyMap<SerializedObject> versionConflicts, ObjectDB.UpdateMode mode) Prepares a create/write against the database.
abstract SerializedObject	read(long onum) Returns the object stored at a particular onum.
GroupContainer	readGroup(long onum) Returns a GroupContainer for the object stored at a particular onum.
abstract void	rollback(long tid, Principal worker) Causes the objects prepared in transaction [tid] to be discarded.
protected abstract void	setInitialized() Sets a flag to indicate that the object database has been initialized.
protected void	unpin(ObjectDB.PendingTransaction tx) Adjusts rwLocks to account for the fact that the given transaction is about to be committed or aborted.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected final java.lang.String name

The store's name.

pendingByTid

protected final ConcurrentLongKeyMap<OidKeyHashMap<ObjectDB.PendingTransaction>> pendingByTid

The table of partially prepared transactions. Note that this does not need to be saved to stable storage, since we only need to persist transactions that are fully prepared.

Maps tids to principal oids to PendingTransactions.

rwLocks

protected final ConcurrentLongKeyMap<fabric.store.db.ObjectLocks> rwLocks

Maps onums to ObjectLocks. This should be recomputed from the set of prepared transactions when restoring from stable storage.

Constructor Detail

ObjectDB

protected ObjectDB(java.lang.String name,
                   java.security.PrivateKey privateKey)

Method Detail

beginTransaction

public final void beginTransaction(long tid,
                                   Principal worker)
                            throws AccessException

Opens a new transaction.

Parameters:

worker - the worker under whose authority the transaction is running.

Throws:

AccessException - if the worker has insufficient privileges.

prepareRead

public final void prepareRead(long tid,
                              Principal worker,
                              long onum,
                              int version,
                              LongKeyMap<SerializedObject> versionConflicts)
                       throws TransactionPrepareFailedException

Prepares a read against the database.

Parameters:

tid - the identifier for the transaction preparing the read.

worker - the worker preparing the read.

onum - the object number that was read.

version - the version that was read.

versionConflicts - a map containing the transaction's version-conflict information. If the object read was out of date, then a new entry will be added to this map, binding the object's onum to its current version.

Throws:

TransactionPrepareFailedException

prepareUpdate

public final void prepareUpdate(long tid,
                                Principal worker,
                                SerializedObject obj,
                                LongKeyMap<SerializedObject> versionConflicts,
                                ObjectDB.UpdateMode mode)
                         throws TransactionPrepareFailedException

Prepares a create/write against the database.

Parameters:

tid - the identifier for the transaction preparing the create/write.

worker - the worker preparing the create/write.

obj - the modified object.

versionConflicts - a map containing the transaction's version-conflict information. If the object modified was out of date, then a new entry will be added to this map, binding the object's onum to its current version.

Throws:

TransactionPrepareFailedException

abortPrepare

public final void abortPrepare(long tid,
                               Principal worker)

Rolls back a partially prepared transaction. (i.e., one for which finishPrepare() has yet to be called.)

finishPrepare

public abstract void finishPrepare(long tid,
                                   Principal worker)

Notifies the database that the given transaction is finished preparing. The transaction is not considered to be prepared until this is called. After calling this method, there should not be any further calls to registerRead() or registerUpdate() for the given transaction. This method MUST be called before calling commit().

Upon receiving this call, the object database should save the prepared transaction to stable storage so that it can be recovered in case of failure.

commit

public abstract void commit(long tid,
                            RemoteIdentity<RemoteWorker> workerIdentity,
                            SubscriptionManager sm)
                     throws AccessException

Causes the objects prepared in transaction [tid] to be committed. The changes will hereafter be visible to read.

Parameters:

tid - the transaction id

workerIdentity - the remote worker that is performing the commit

Throws:

AccessException - if the principal differs from the caller of prepare()

rollback

public abstract void rollback(long tid,
                              Principal worker)
                       throws AccessException

Causes the objects prepared in transaction [tid] to be discarded.

Parameters:

tid - the transaction id

worker - the principal requesting the rollback

Throws:

AccessException - if the principal differs from the caller of prepare()

read

public abstract SerializedObject read(long onum)

Returns the object stored at a particular onum.

Parameters:

onum - the identifier

Returns:

the object or null if no object exists at the given onum

readGroup

public final GroupContainer readGroup(long onum)

Returns a GroupContainer for the object stored at a particular onum.

getVersion

public int getVersion(long onum)
               throws AccessException

Returns the version number on the object stored at a particular onum.

Throws:

AccessException - if no object exists at the given onum.

notifyCommittedUpdate

protected final void notifyCommittedUpdate(SubscriptionManager sm,
                                           long onum,
                                           RemoteWorker worker)

Performs operations in response to a committed object update. Removes from cache the glob associated with the onum and notifies the subscription manager of the update.

Parameters:

onum - the onum of the object that was updated.

worker - the worker that performed the update.

isPrepared

public final boolean isPrepared(long onum,
                                long tid)

Determines whether an onum has an outstanding uncommitted conflicting change or read. Outstanding uncommitted changes are always considered conflicting. Outstanding uncommitted reads are considered conflicting if they are by transactions whose tid is different from the one given.

Parameters:

onum - the object number in question

isWritten

public final boolean isWritten(long onum)

Determines whether an onum has outstanding uncommitted changes.

Parameters:

onum - the object number in question

Returns:

true if the object has been changed by a transaction that hasn't been committed or rolled back.

unpin

protected final void unpin(ObjectDB.PendingTransaction tx)

Adjusts rwLocks to account for the fact that the given transaction is about to be committed or aborted.

newOnums

public abstract long[] newOnums(int num)

Returns a set of onums that aren't currently occupied. The ObjectDB may return the same onum more than once from this method, althogh doing so would encourage collisions. There is no assumption of unpredictability or randomness about the returned ids.

The returned onums should be packed in the lower 48 bits. We assume that the object database is never full, and can always provide new onums

Parameters:

num - the number of onums to return

Returns:

num fresh onums

exists

public abstract boolean exists(long onum)

Checks whether an object with the corresponding onum exists, in either prepared or committed form.

Parameters:

onum - the onum of to check

Returns:

true if an object exists for onum

getName

public final java.lang.String getName()

Returns the name of this store.

close

public abstract void close()
                    throws java.io.IOException

Gracefully shuts down the object database.

Throws:

java.io.IOException

isInitialized

protected abstract boolean isInitialized()

Determines whether the object database has been initialized.

setInitialized

protected abstract void setInitialized()

Sets a flag to indicate that the object database has been initialized.

ensureInit

public final void ensureInit()

Ensures that the object database has been properly initialized. This creates, for example, the name-service map and the store's principal, if they do not already exist in the database.