org.exolab.core.database.recman
Class PMDSession

java.lang.Object
  org.exolab.core.database.recman.PMDSession

All Implemented Interfaces:

SessionIfc, TransactionIfc

public class PMDSession

extends java.lang.Object

implements SessionIfc, TransactionIfc

This is an implementation of the SessionIfc interface for the page managed database. A session is a single-threaded entity that is only accessible through the PMDSessionManager (this is where the constraint is enforced).

A Session is a mediating class to the pagem managed database and delegates the request to the appropriate component.

There is a lack of synchronization in this class and hence lacks thread safety since it is expected that only one thread will be accessing an instance of this class at any one time.

Version:

$Revision: 1.4 $ $Date: 2003/06/09 06:28:39 $

Author:

Jim Alateras

See Also:

PMDSessionManager

Field Summary

Fields inherited from interface org.exolab.core.foundation.SessionIfc

DEFAULT_LOCK_TIMEOUT

Method Summary

void	abort() Abort the current transaction.
void	acquireLock(PersistentCapableIfc object, int timeout) Acquire an exclusive lock on the specified object.
void	begin() Put the transaction in the open state.
void	bind(java.lang.String name, PersistentCapableIfc object) Bind the specified name to an object.
void	commit() Close the current transaction.
HandleIfc	createHandle(PersistentCapableIfc object) Create a handle for the specified PersistentCapableIfc object.
void	createObject(PersistentCapableIfc object) Create the specified persistent object in the database for this session.
void	deleteObject(PersistentCapableIfc object) Delete the specified persistent object in the database for this session.
CollectionManagerIfc	getCollectionManager() Return a reference to the collection manager, which is used to allocate different collection types includinng queues and vectors.
TransactionIfc	getCurrentTransaction() Return the current transaction for this session.
DatabaseIfc	getDatabase() Return the database that this session is associated with.
java.util.Enumeration	getRootNames() Return an enumeration of all the database root names.
long	getSessionId() Return the session id associated with this object
SessionManagerIfc	getSessionManager() Return the session manager responsible for allocating this session
TransactionContext	getTransactionContext() Return the transaction context assoicated with this transaction
boolean	isBound(java.lang.String name) Check if an object is already bound to the specified name
boolean	isOpened() Test if the transaction is opened.
boolean	isValid() Check the validity of the session
PersistentCapableIfc	lookup(java.lang.String name) Lookup the object specified by name.
PersistentCapableIfc	retrieveObject(long id) Retrieve the persistent object associated with the id.
void	rollback() Rollback the current transaction.
void	setRollbackOnly(boolean status) Set the transaction so that the only outcome is rollback.
void	setSessionManager(SessionManagerIfc manager) Set the session manager that allocated this session.
void	unbind(java.lang.String name) Unbind the object associated with the specified name.
void	updateObject(PersistentCapableIfc object) Update the specified persistent object in the database for this session.

Methods inherited from class java.lang.Object

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

Method Detail

getRootNames

public java.util.Enumeration getRootNames()

Description copied from interface: SessionIfc

Return an enumeration of all the database root names. A database root is one that is bound by name and represents an entry point in the database.

Specified by:

getRootNames in interface SessionIfc

Returns:

Enumeration collection of roots

bind

public void bind(java.lang.String name,
                 PersistentCapableIfc object)
          throws ObjectNameExistsException,
                 DatabaseIOException,
                 TransactionNotInProgressException

Description copied from interface: SessionIfc

Bind the specified name to an object. All bound objects are actually database roots. If an object is already bound to this name the method throws the ObjectNameExistsException. If there is a problem binding the object to the specified name then the DataIOException is raised.

The TransactionNotInProgressException is thrown when bind is called outside a transaction.

Specified by:

bind in interface SessionIfc

Parameters:

name - binding name

object - object to bind

Throws:

DatabaseIOException

ObjectNameExistsException

TransactionNotInProgressException

unbind

public void unbind(java.lang.String name)
            throws ObjectNameNotFoundException,
                   DatabaseIOException,
                   TransactionNotInProgressException

Description copied from interface: SessionIfc

Unbind the object associated with the specified name. IF the name does not exist then throw the ObjectNameNotFoundException. If there are database related problems to the unbind then throw DatabaseIOException

The TransactionNotInProgressException is thrown when unbind is called outside a transaction.

Specified by:

unbind in interface SessionIfc

Parameters:

name - binding name

Throws:

ObjectNameNotFoundException

TransactionNotInProgressException

DatabaseIOException

lookup

public PersistentCapableIfc lookup(java.lang.String name)

Description copied from interface: SessionIfc

Lookup the object specified by name. If the object does not exists then return null.

Specified by:

lookup in interface SessionIfc

Parameters:

name - lookup name

Returns:

Object

isBound

public boolean isBound(java.lang.String name)

Description copied from interface: SessionIfc

Check if an object is already bound to the specified name

Specified by:

isBound in interface SessionIfc

Parameters:

name - lookup name

Returns:

boolean true if name is bound to object

acquireLock

public void acquireLock(PersistentCapableIfc object,
                        int timeout)
                 throws FailedToAcquireLockException,
                        FailedToCreateLockException,
                        TransactionNotInProgressException

Description copied from interface: SessionIfc

Acquire an exclusive lock on the specified object. This will lock out all other transactions trying to access the specified object. If the session cannot acquire a lock then FailedToAcquireLockException is raised. The TransactionNotInProgressException is thrown when an attempt is made to acquire a lock outside a transaction

The timeout determines how long to wait for the lock. A value of DEFAULT_LOCK_TIMEOUT is used to wait the default time.

All locks granted to a session will be automatically released in an abort, commit or rollback

Specified by:

acquireLock in interface SessionIfc

Parameters:

object - object to lock

Returns:

Object reference to locked object

Throws:

TransactionNotInProgressException

FailedToAcquireLockException

FailedToCreateLockException

begin

public void begin()
           throws TransactionInProgressException

Description copied from interface: TransactionIfc

Put the transaction in the open state. If the transaction is already opened then throw TransactionInProgressException

Specified by:

begin in interface TransactionIfc

Throws:

TransactionInProgressException

commit

public void commit()
            throws TransactionNotInProgressException,
                   TransactionException,
                   DatabaseIOException

Description copied from interface: TransactionIfc

Close the current transaction. If the setRollbackOnly has been called while the transaction was open then a rollback is forced and the TransactionException exception is thrown.

If the transaction is not currently opened then TransactionNotInProg- ressException is raised.

Specified by:

commit in interface TransactionIfc

Throws:

DatabaseIOException

TransactionNotInProgressException

TransactionException

abort

public void abort()
           throws TransactionNotInProgressException,
                  DatabaseIOException

Description copied from interface: TransactionIfc

Abort the current transaction. If there is no transaction currently in progress then throw TransactionNotInProgressException

Specified by:

abort in interface TransactionIfc

Throws:

TransactionNotInProgressException

DatabaseIOException

rollback

public void rollback()
              throws TransactionNotInProgressException,
                     DatabaseIOException

Description copied from interface: TransactionIfc

Rollback the current transaction. If there is no transaction currently in progress then throw TransactionNotInProgressException

Specified by:

rollback in interface TransactionIfc

Throws:

TransactionNotInProgressException

DatabaseIOException

setRollbackOnly

public void setRollbackOnly(boolean status)
                     throws TransactionNotInProgressException

Description copied from interface: TransactionIfc

Set the transaction so that the only outcome is rollback. If there is no transaction in progress raise TransactionNotInProgressException.

Specified by:

setRollbackOnly in interface TransactionIfc

Parameters:

status - true to set rollback only; false to clear the rollback only flag

Throws:

TransactionNotInProgressException

isOpened

public boolean isOpened()

Description copied from interface: TransactionIfc

Test if the transaction is opened.

Specified by:

isOpened in interface TransactionIfc

Returns:

boolean true if opened; false otherwise

getTransactionContext

public TransactionContext getTransactionContext()

Description copied from interface: TransactionIfc

Return the transaction context assoicated with this transaction

Specified by:

getTransactionContext in interface TransactionIfc

Returns:

TransactionContext

getCurrentTransaction

public TransactionIfc getCurrentTransaction()

Description copied from interface: SessionIfc

Return the current transaction for this session. This will always be a non-null object but the transaction may not be currently opened.

Specified by:

getCurrentTransaction in interface SessionIfc

Returns:

TransactionIfc

getDatabase

public DatabaseIfc getDatabase()

Description copied from interface: SessionIfc

Return the database that this session is associated with. This should not return a non-null object but could return a DatabaseIfc instance that is invalid or closed

Specified by:

getDatabase in interface SessionIfc

Returns:

DatabaseIfc

getSessionManager

public SessionManagerIfc getSessionManager()

Description copied from interface: SessionIfc

Return the session manager responsible for allocating this session

Specified by:

getSessionManager in interface SessionIfc

Returns:

SessionManager

setSessionManager

public void setSessionManager(SessionManagerIfc manager)

Description copied from interface: SessionIfc

Set the session manager that allocated this session. If a session already exists then overwrite it.

Specified by:

setSessionManager in interface SessionIfc

Parameters:

manager - session manager

createObject

public void createObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException

Description copied from interface: SessionIfc

Create the specified persistent object in the database for this session. The object must be created within a transaction and is only made permanent when a commit is issued. If there is not transaction in progress the TransactionNotInProgressException is raised. If there is a general database problem then the DatabaseIOException is raised.

Specified by:

createObject in interface SessionIfc

Parameters:

object - object to create

Throws:

TransactionNotInProgressException

DatabaseIOException

updateObject

public void updateObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException

Description copied from interface: SessionIfc

Update the specified persistent object in the database for this session. The object must be updated within a transaction and is only made permanent when a commit is issued. If there is not transaction in progress the TransactionNotInProgressException is raised. If there is a general database problem then the DatabaseIOException is raised.

Specified by:

updateObject in interface SessionIfc

Parameters:

object - object to update

Throws:

TransactionNotInProgressException

DatabaseIOException

deleteObject

public void deleteObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException

Description copied from interface: SessionIfc

Delete the specified persistent object in the database for this session. The object must be deleted within a transaction and is only made deleted from thedatabase when the transaction commits. If there is no transaction in progress the TransactionNotInProgress- Exception is raised. If there is a general database problem then the DatabaseIOException is raised.

Specified by:

deleteObject in interface SessionIfc

Parameters:

object - object to delete

Throws:

DatabaseIOException

TransactionNotInProgressException

retrieveObject

public PersistentCapableIfc retrieveObject(long id)
                                    throws TransactionNotInProgressException,
                                           DatabaseIOException

Description copied from interface: SessionIfc

Retrieve the persistent object associated with the id. If the object does not exist then throw a DatabaseIOException, If there is no transaction in progress then throw a TransactionNotInProgressException.

Specified by:

retrieveObject in interface SessionIfc

Parameters:

id - identity of object to retrieve

Returns:

PersistentCapableIfc

Throws:

DatabaseIOException

TransactionNotInProgressException

createHandle

public HandleIfc createHandle(PersistentCapableIfc object)
                       throws FailedToCreateHandleException,
                              TransactionNotInProgressException

Create a handle for the specified PersistentCapableIfc object. If it cannot create the handle then throw the FailedToCreateHandleException. If transaction is not in progress then TransactionNotInProgressException is raised.

A handle can be used to reference a persistent entity and can be carried across transactions...although there is some more code that needs to be done in order to make this a reality. (i.e clear the cached object between transactions).

Specified by:

createHandle in interface SessionIfc

Parameters:

object - PersistentCapableIfc

Throws:

FailedToCreateHandleException

TransactionNotInProgressException

getCollectionManager

public CollectionManagerIfc getCollectionManager()

Return a reference to the collection manager, which is used to allocate different collection types includinng queues and vectors.

Specified by:

getCollectionManager in interface SessionIfc

Returns:

CollectionManagerIfc

getSessionId

public long getSessionId()

Description copied from interface: SessionIfc

Return the session id associated with this object

Specified by:

getSessionId in interface SessionIfc

Returns:

long session identifier

isValid

public boolean isValid()

Description copied from interface: SessionIfc

Check the validity of the session

Specified by:

isValid in interface SessionIfc

Returns:

boolean true if the session is valid