arlut.csd.ganymede
Class DBSession

java.lang.Object
  |
  +--arlut.csd.ganymede.DBSession

public final class DBSession

extends java.lang.Object

DBSession is the Ganymede server's DBStore-level session class. Each client or server process that interacts with the Ganymede database must eventually do so through a DBSession object. Clients and server processes generally interact directly with a GanymedeSession, by way of the Session interface on the part of the client. The GanymedeSession talks to the DBSession class to actually interact with the database.

Most particularly, DBSession handles transactions and namespace logic for the Ganymede server, as well as providing the actual check-out/create/ check-in methods that GanymedeSession calls. GanymedeSession tends to have the more high-level application/permissions logic, while DBSession is more concerned with internal database issues. As well, GanymedeSession is designed to be directly accessed and manipulated by the client, while DBSession is accessed only by (presumably trusted) server-side code, that needs to bypass the security logic in GanymedeSession.

The DBSession contains code and logic to actually manipulate the Ganymede database (the DBObjectBase, DBObject, and DBEditObject objects held in the DBStore). The DBSession class connects to the extensive transaction logic implemented in the DBEditSet class, as well as the database locking handled by the DBLock class.

Field Summary

(package private) static boolean	debug
(package private) DBEditSet	editSet Transaction handle for this session.
(package private) GanymedeSession	GSession User-level session reference.
(package private) java.lang.String	id Optional string identifying this session in logging, etc.
(package private) java.lang.Object	key Identifying key used in the lock system to identify owner of locks.
(package private) java.lang.String	lastError Deprecated error reporting string..
(package private) java.util.Vector	lockVect Vector of DBLock objects held by this session.
(package private) DBStore	store Root object of the Ganymede database system.
private boolean	terminating This flag will be set to true if this session is busy trying to commit or abandon a transaction, and no new objects should be editable by this transaction.

Constructor Summary

(package private)

DBSession(DBStore store, GanymedeSession GSession, java.lang.Object key) Constructor for DBSession.

Method Summary

ReturnVal	abortTransaction() abortTransaction causes all DBEditObjects that were pulled during the course of the session's transaction to be released without affecting the state of the database.
void	checkpoint(java.lang.String name) Convenience pass-through method
ReturnVal	commitTransaction() commitTransaction causes any changes made during the context of a current transaction to be performed.
ReturnVal	createDBObject(short object_type, Invid chosenSlot, java.util.Vector owners) Create a new object in the database.
ReturnVal	createDBObject(short object_type, java.util.Vector owners) Create a new object in the database.
ReturnVal	deleteDBObject(DBEditObject eObj) Remove an object from the database
ReturnVal	deleteDBObject(Invid invid) Remove an object from the database
ReturnVal	deleteDBObject(short baseID, int objectID) Remove an object from the database
DBEditObject	editDBObject(Invid invid) Pull an object out of the database for editing.
DBEditObject	editDBObject(short baseID, int objectID) Pull an object out of the database for editing.
GanymedeSession	getGSession() This method returns a handle to the Ganymede Session that owns this DBSession.
java.lang.String	getID() This method is responsible for providing an identifier string for the user who this session belongs to, and is used for logging and what-not.
java.lang.Object	getKey()
DBEditObject	getObjectHook(Invid invid) This method returns a handle to the objectHook for a particular Invid.
DBStore	getStore() This method is provided so that custom DBEditObject subclasses can get access to methods on our DBStore.
ReturnVal	inactivateDBObject(DBEditObject eObj) Inactivate an object in the database
boolean	isInteractive() This method returns true if this session is carrying out a transaction on behalf of an interactive client.
boolean	isLocked(DBLock lockParam) Returns true if the session's lock is currently locked, false otherwise.
boolean	isTerminating() This method returns true if this session is in the middle of committing or aborting this session's transaction.
boolean	isTransactionOpen() Returns true if this session has an transaction open
void	logout() Close out this DBSession, aborting any open transaction, and releasing any held read/write/dump locks.
DBDumpLock	openDumpLock() This method establishes a dump lock on all object bases in this Ganymede server.
DBReadLock	openReadLock() openReadLock establishes a read lock for the entire DBStore.
DBReadLock	openReadLock(java.util.Vector bases) Establishes a read lock for the DBObjectBases in bases.
void	openTransaction(java.lang.String describe) openTransaction establishes a transaction context for this session.
void	openTransaction(java.lang.String describe, boolean interactive) openTransaction establishes a transaction context for this session.
DBWriteLock	openWriteLock(java.util.Vector bases) Establishes a write lock for the DBObjectBases in bases.
boolean	popCheckpoint(java.lang.String name) Convenience pass-through method
ReturnVal	reactivateDBObject(DBEditObject eObj) Reactivates an object in the database.
void	releaseAllLocks() releaseAllLocks() releases all locks held by this session.
void	releaseLock(DBLock lock) releaseLock releases a particular lock held by this session.
boolean	rollback(java.lang.String name) Convenience pass-through method
static void	setDebug(boolean val)
void	setLastError(java.lang.String error) Deprecated. This method is obsoleted by the use of ReturnVal
java.lang.String	toString()
DBObject	viewDBObject(Invid invid) Get a reference to a read-only copy of an object in the DBStore.
DBObject	viewDBObject(Invid invid, boolean getOriginal) Get a reference to a read-only copy of an object in the DBStore.
DBObject	viewDBObject(short baseID, int objectID) Get a reference to a read-only copy of an object in the DBStore.
DBObject	viewDBObject(short baseID, int objectID, boolean getOriginal) Get a reference to a read-only copy of an object in the DBStore.

Methods inherited from class java.lang.Object

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

Field Detail

debug

static boolean debug

GSession

GanymedeSession GSession

User-level session reference. As mentioned above, GanymedeSession has the user-level permissions handling, while DBSession has the database handling.

store

DBStore store

Root object of the Ganymede database system.

lockVect

java.util.Vector lockVect

Vector of DBLock objects held by this session. This needs to be a Vector because a DBSession can legitimately hold multiple DBReadLock objects at a time. Only one writer lock is allowed at a time, however, to avoid deadlock.

The DBStore's DBLockSync object is used, in conjunction with the establish() methods in the DBReadLock, DBWriteLock, and DBDumpLock classes.

editSet

DBEditSet editSet

Transaction handle for this session.

lastError

java.lang.String lastError

Deprecated error reporting string.. like errno in the C standard library, this sort of interface isn't thread-friendly, so we've largely moved away from using this String to the per-method ReturnVal result object.

id

java.lang.String id

Optional string identifying this session in logging, etc.

Used by getID().

key

java.lang.Object key

Identifying key used in the lock system to identify owner of locks.

terminating

private boolean terminating

This flag will be set to true if this session is busy trying to commit or abandon a transaction, and no new objects should be editable by this transaction.

Constructor Detail

DBSession

DBSession(DBStore store,
          GanymedeSession GSession,
          java.lang.Object key)

Constructor for DBSession.

The key passed to the DBSession constructor is intended to be used to allow code to save an identifier in the DBSession.. this might be a thread object or a higher level session object or whatever. Eventually I expect I'll replace this generic key with some sort of reporting Interface object.

This constructor is intended to be called by the DBStore login() method.

Parameters:

store - The DBStore database this session belongs to.

GSession - The Ganymede session associated with this DBSession

key - An identifying key with meaning to whatever code is using arlut.csd.ganymede

Method Detail

setDebug

public static final void setDebug(boolean val)

logout

public void logout()

Close out this DBSession, aborting any open transaction, and releasing any held read/write/dump locks.

getStore

public DBStore getStore()

This method is provided so that custom DBEditObject subclasses can get access to methods on our DBStore.

createDBObject

public ReturnVal createDBObject(short object_type,
                                Invid chosenSlot,
                                java.util.Vector owners)

Create a new object in the database.

This method creates a slot in the object base of the proper object type. The created object is associated with the current transaction. When the transaction is committed, the created object will inserted into the database, and will become visible to other sessions.

The created object will be given an object id. The DBEditObject can be queried to determine its invid.

The created DBEditObject will have its fields initialized by the DBObjectBase objectHook custom DBEditObject's initializeNewObject() method.

This method will return null if the object could not be constructed and initialized for some reason.

Parameters:

object_type - Type of the object to be created

chosenSlot - Invid to create the new object with. normally only used in internal Ganymede code in conjunction with the addition of new kinds of built-in objects during development

owners - Vector of invids for owner group objects to make initial owners for the newly created object

See Also:

DBStore

createDBObject

public ReturnVal createDBObject(short object_type,
                                java.util.Vector owners)

Create a new object in the database.

This method creates a slot in the object base of the proper object type. The created object is associated with the current transaction. When the transaction is committed, the created object will inserted into the database, and will become visible to other sessions.

The created object will be given an object id. The DBEditObject can be queried to determine its invid.

The created DBEditObject will have its fields initialized by the DBObjectBase objectHook custom DBEditObject's initializeNewObject() method.

This method returns a ReturnVal object to convey the result of the creation. Call the getObject() method on the returned ReturnVal in order to get the created DBEditObject. Note that the ReturnVal.getObject() method is intended to support passing a remote db_object reference to the client, so on the server, it is necessary to cast the db_object reference to a DBEditObject reference for use on the server.

Parameters:

object_type - Type of the object to be created

See Also:

DBStore

editDBObject

public DBEditObject editDBObject(Invid invid)

Pull an object out of the database for editing.

This method is used to check an object out of the database for editing. Only one session can have a particular object checked out for editing at a time.

The session has to have a transaction opened before it can pull an object out for editing.

Parameters:

invid - The invariant id of the object to be modified.

Returns:

null if the object could not be found for editing

See Also:

DBObjectBase

editDBObject

public DBEditObject editDBObject(short baseID,
                                 int objectID)

Pull an object out of the database for editing.

This method is used to check an object out of the database for editing. Only one session can have a particular object checked out for editing at a time.

The session has to have a transaction opened before it can pull a new object out for editing. If the object specified by <baseID, objectID> is part of the current transaction, the transactional copy will be returned, and no readLock is strictly necessary in that case.

This method doesn't do permission checking.. that is performed at the GanymedeSession level.

Parameters:

baseID - The short id number of the DBObjectBase containing the object to be edited.

objectID - The int id number of the object to be edited within the specified object base.

Returns:

null if the object could not be found for editing

viewDBObject

public DBObject viewDBObject(Invid invid,
                             boolean getOriginal)

Get a reference to a read-only copy of an object in the DBStore.

If this session has a transaction currently open, this method will return the checked out shadow of invid, if it has been checked out by this transaction.

Note that unless the object has been checked out by the current session, this method will return access to the object as it is stored directly in the main datastore hashes. This means that the object will be read-only and will grant all accesses, as it will have no notion of what session or transaction owns it. If you need to have access to the object's fields be protected, use GanymedeSession's view_db_object() method to get the object.

Parameters:

invid - The invariant id of the object to be viewed.

getOriginal - if true, viewDBObject will return the original version of a DBEditObject in this session if the specified object is in the middle of being deleted

viewDBObject

public DBObject viewDBObject(Invid invid)

Get a reference to a read-only copy of an object in the DBStore.

If this session has a transaction currently open, this method will return the checked out shadow of invid, if it has been checked out by this transaction.

Note that unless the object has been checked out by the current session, this method will return access to the object as it is stored directly in the main datastore hashes. This means that the object will be read-only and will grant all accesses, as it will have no notion of what session or transaction owns it. If you need to have access to the object's fields be protected, use GanymedeSession's view_db_object() method to get the object.

Parameters:

invid - The invariant id of the object to be viewed.

viewDBObject

public DBObject viewDBObject(short baseID,
                             int objectID)

Get a reference to a read-only copy of an object in the DBStore.

If this session has a transaction currently open, this method will return the checked out shadow of invid, if it has been checked out by this transaction.

Note that unless the object has been checked out by the current session, this method will return access to the object as it is stored directly in the main datastore hashes. This means that the object will be read-only and will grant all accesses, as it will have no notion of what session or transaction owns it. If you need to have access to the object's fields be protected, use GanymedeSession's view_db_object() method to get the object.

Parameters:

baseID - The short id number of the DBObjectBase containing the object to be viewed.

objectID - The int id number of the object to be viewed within the specified object base.

viewDBObject

public DBObject viewDBObject(short baseID,
                             int objectID,
                             boolean getOriginal)

Get a reference to a read-only copy of an object in the DBStore.

If this session has a transaction currently open, this method will return the checked out shadow of invid, if it has been checked out by this transaction.

Note that unless the object has been checked out by the current session, this method will return access to the object as it is stored directly in the main datastore hashes. This means that the object will be read-only and will grant all accesses, as it will have no notion of what session or transaction owns it. If you need to have access to the object's fields be protected, use GanymedeSession's view_db_object() method to get the object.

Parameters:

baseID - The short id number of the DBObjectBase containing the object to be viewed.

objectID - The int id number of the object to be viewed within the specified object base.

getOriginal - if true, viewDBObject will return the original version of a DBEditObject in this session if the specified object is in the middle of being deleted

deleteDBObject

public ReturnVal deleteDBObject(Invid invid)

Remove an object from the database

This method method can only be called in the context of an open transaction. This method will mark an object for deletion. When the transaction is committed, the object is removed from the database. If the transaction is aborted, the object remains in the database unchanged.

Parameters:

invid - Invid of the object to be deleted

deleteDBObject

public ReturnVal deleteDBObject(short baseID,
                                int objectID)

Remove an object from the database

This method method can only be called in the context of an open transaction. This method will check an object out of the DBStore and add it to the editset's deletion list. When the transaction is committed, the object has its remove() method called to do cleanup, and the editSet nulls the object's slot in the DBStore. If the transaction is aborted, the object remains in the database unchanged.

Parameters:

baseID - id of the object base containing the object to be deleted

objectID - id of the object to be deleted

deleteDBObject

public ReturnVal deleteDBObject(DBEditObject eObj)

Remove an object from the database

This method method can only be called in the context of an open transaction. Because the object must be checked out (which is the only way to obtain a DBEditObject), no other locking is required. This method will take an object out of the DBStore, do whatever immediate removal logic is required, and mark it as deleted in the transaction. When the transaction is committed, the object will be expunged from the database.

Note that this method does not check to see whether permission has been obtained to delete the object.. that's done in GanymedeSession's remove_db_object() method.

Parameters:

eObj - An object checked out in the current transaction to be deleted

inactivateDBObject

public ReturnVal inactivateDBObject(DBEditObject eObj)

Inactivate an object in the database

This method method can only be called in the context of an open transaction. Because the object must be checked out (which is the only way to obtain a DBEditObject), no other locking is required. This method will take an object out of the DBStore and proceed to do whatever is necessary to cause that object to be 'inactivated'.

Note that this method does not check to see whether permission has been obtained to inactivate the object.. that's done in GanymedeSession.inactivate_db_object().

Parameters:

eObj - An object checked out in the current transaction to be inactivated

reactivateDBObject

public ReturnVal reactivateDBObject(DBEditObject eObj)

Reactivates an object in the database.

This method method can only be called in the context of an open transaction. Because the object must be checked out (which is the only way to obtain a DBEditObject), no other locking is required. This method will take an object out of the DBStore and proceed to do whatever is necessary to cause that object to be 'inactivated'.

Note that this method does not specifically check to see whether permission has been obtained to reactivate the object.. that's done in GanymedeSession.reactivate_db_object().

Parameters:

eObj - An object checked out in the current transaction to be reactivated

checkpoint

public final void checkpoint(java.lang.String name)

Convenience pass-through method

This method may block if another thread has already checkpointed this transaction. Checkpoints are intended to be of definite extent, as the interleaving of checkpoints by multiple threads would lead to trouble.

See Also:

DBEditSet.checkpoint(java.lang.String)

popCheckpoint

public final boolean popCheckpoint(java.lang.String name)

Convenience pass-through method

See Also:

DBEditSet.popCheckpoint(java.lang.String)

rollback

public final boolean rollback(java.lang.String name)

Convenience pass-through method

See Also:

DBEditSet.rollback(java.lang.String)

isLocked

public boolean isLocked(DBLock lockParam)

Returns true if the session's lock is currently locked, false otherwise.

openReadLock

public DBReadLock openReadLock(java.util.Vector bases)
                        throws java.lang.InterruptedException

Establishes a read lock for the DBObjectBases in bases.

The thread calling this method will block until the read lock can be established. If any of the DBObjectBases in the bases vector have transactions currently committing, the establishment of the read lock will be suspended until all such transactions are committed.

All viewDBObject calls done within the context of an open read lock will be transaction consistent. Other sessions may pull objects out for editing during the course of the session's read lock, but no visible changes will be made to those ObjectBases until the read lock is released.

openReadLock

public DBReadLock openReadLock()
                        throws java.lang.InterruptedException

openReadLock establishes a read lock for the entire DBStore.

The thread calling this method will block until the read lock can be established. If transactions on the database are currently committing, the establishment of the read lock will be suspended until all such transactions are committed.

All viewDBObject calls done within the context of an open read lock will be transaction consistent. Other sessions may pull objects out for editing during the course of the session's read lock, but no visible changes will be made to those ObjectBases until the read lock is released.

openWriteLock

public DBWriteLock openWriteLock(java.util.Vector bases)
                          throws java.lang.InterruptedException

Establishes a write lock for the DBObjectBases in bases.

The thread calling this method will block until the write lock can be established. If this DBSession already possesses a write lock, read lock, or dump lock, the openWriteLock() call will fail with an InterruptedException.

If one or more different DBSessions (besides this) have locks in place that would block acquisition of the write lock, this method will block until the lock can be acquired.

openDumpLock

public DBDumpLock openDumpLock()
                        throws java.lang.InterruptedException

This method establishes a dump lock on all object bases in this Ganymede server.

releaseLock

public void releaseLock(DBLock lock)

releaseLock releases a particular lock held by this session. This method will not force a lock being held by another thread to drop out of its establish method.. it is intended to be called by the same thread that established the lock.

This method must be synchronized to avoid conflicting with iterations on lockVect.

releaseAllLocks

public void releaseAllLocks()

releaseAllLocks() releases all locks held by this session.

This method is *not* synchronized. This method must only be called by code synchronized on this DBSession instance, as for instance logout() and commitTransaction().

openTransaction

public void openTransaction(java.lang.String describe)

openTransaction establishes a transaction context for this session. When this method returns, the session can call editDBObject() and createDBObject() to obtain DBEditObjects. Methods can then be called on the DBEditObjects to make changes to the database. These changes are actually performed when and if commitTransaction() is called.

Parameters:

describe - An optional string containing a comment to be stored in the modification history for objects modified by this transaction.

See Also:

DBEditObject

openTransaction

public void openTransaction(java.lang.String describe,
                            boolean interactive)

openTransaction establishes a transaction context for this session. When this method returns, the session can call editDBObject() and createDBObject() to obtain DBEditObjects. Methods can then be called on the DBEditObjects to make changes to the database. These changes are actually performed when and if commitTransaction() is called.

Parameters:

describe - An optional string containing a comment to be stored in the modification history for objects modified by this transaction.

interactive - If false, this transaction will operate in non-interactive mode. Certain Invid operations will be optimized to avoid doing choice list queries and bind checkpoint operations. When a transaction is operating in non-interactive mode, any failure that cannot be handled cleanly due to the optimizations will result in the transaction refusing to commit when commitTransaction() is attempted. This mode is intended for batch operations.

See Also:

DBEditObject

commitTransaction

public ReturnVal commitTransaction()

commitTransaction causes any changes made during the context of a current transaction to be performed. Appropriate portions of the database are locked, changes are made to the in-memory image of the database, and a description of the changes is placed in the DBStore journal file. Event logging / mail notification may take place.

The session must not hold any locks when commitTransaction is called. The symmetrical invid references between related objects and the atomic namespace management code should guarantee that no incompatible change is made with respect to any checked out objects while the Bases are unlocked.

Returns:

null if the transaction was committed successfully, a non-null ReturnVal if there was a commit failure.

See Also:

DBEditObject

abortTransaction

public ReturnVal abortTransaction()

abortTransaction causes all DBEditObjects that were pulled during the course of the session's transaction to be released without affecting the state of the database. Any changes made to DBObjects pulled for editing by this session during this transaction are abandoned. Any objects created or destroyed by this session during this transaction are abandoned / unaffected by the actions during the transaction.

Calling abortTransaction() has no affect on any locks held by this session, but generally no locks should be held here. abortTransaction() will attempt to abort a write lock being established by a commitTransaction() call on another thread.

Returns:

null if the transaction was committed successfully, a non-null ReturnVal if there was a commit failure.

See Also:

DBEditObject

isTransactionOpen

public boolean isTransactionOpen()

Returns true if this session has an transaction open

isInteractive

public boolean isInteractive()

This method returns true if this session is carrying out a transaction on behalf of an interactive client.

isTerminating

public boolean isTerminating()

This method returns true if this session is in the middle of committing or aborting this session's transaction.

setLastError

public void setLastError(java.lang.String error)

Deprecated. This method is obsoleted by the use of ReturnVal

internal method for setting error messages resulting from session activities.

this method may eventually be hooked up to a more general logging mechanism.

getKey

public java.lang.Object getKey()

getID

public java.lang.String getID()

This method is responsible for providing an identifier string for the user who this session belongs to, and is used for logging and what-not.

getGSession

public GanymedeSession getGSession()

This method returns a handle to the Ganymede Session that owns this DBSession.

getObjectHook

public DBEditObject getObjectHook(Invid invid)

This method returns a handle to the objectHook for a particular Invid.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object