org.exolab.core.foundation
Interface SessionIfc

All Known Implementing Classes:
PMDSession

public interface SessionIfc

A session defines a communication pipe for clients and servers to exchange information. A session is responsible for authorisation and authentication and for providing a mediating interface to the specific service. It is the first point of contact for clients to your service.

Because it is a mediating interface is supports functions from DatabaseIfc and TransactionIfc.

Sessions are transient objects that can only be created by the SessionManager.

Version:
$Revision: 1.3 $ $Date: 2000/05/19 00:39:54 $
Author:
Jim Alateras
See Also:
SessionManager

Field Summary
static long DEFAULT_LOCK_TIMEOUT
           
 
Method Summary
 void acquireLock(PersistentCapableIfc object, int timeout)
          Acquire an exclusive lock on the specified object.
 void bind(java.lang.String name, PersistentCapableIfc object)
          Bind the specified name to an object.
 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
 boolean isBound(java.lang.String name)
          Check if an object is already bound to the specified name
 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 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.
 

Field Detail

DEFAULT_LOCK_TIMEOUT

public static final long DEFAULT_LOCK_TIMEOUT
See Also:
Constant Field Values
Method Detail

getRootNames

public java.util.Enumeration getRootNames()
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.

Returns:
Enumeration collection of roots

bind

public void bind(java.lang.String name,
                 PersistentCapableIfc object)
          throws ObjectNameExistsException,
                 DatabaseIOException,
                 TransactionNotInProgressException
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.

Parameters:
name - binding name
object - object to bind
Throws:
ObjectNameExistsException
DatabaseIOException
TransactionNotInProgressException

unbind

public void unbind(java.lang.String name)
            throws ObjectNameNotFoundException,
                   DatabaseIOException,
                   TransactionNotInProgressException
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.

Parameters:
name - binding name
Throws:
ObjectNameNotFoundException
DatabaseIOException
TransactionNotInProgressException

lookup

public PersistentCapableIfc lookup(java.lang.String name)
Lookup the object specified by name. If the object does not exists then return null.

Parameters:
name - lookup name
Returns:
Object

isBound

public boolean isBound(java.lang.String name)
Check if an object is already bound to the specified name

Parameters:
name - lookup name
Returns:
boolean true if name is bound to object

getCurrentTransaction

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

Returns:
TransactionIfc

getDatabase

public DatabaseIfc getDatabase()
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

Returns:
DatabaseIfc

getSessionManager

public SessionManagerIfc getSessionManager()
Return the session manager responsible for allocating this session

Returns:
SessionManager

setSessionManager

public void setSessionManager(SessionManagerIfc manager)
Set the session manager that allocated this session. If a session already exists then overwrite it.

Parameters:
manager - session manager

createObject

public void createObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException
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.

Parameters:
object - object to create
Throws:
TransactionNotInProgressException
DatabaseIOException

updateObject

public void updateObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException
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.

Parameters:
object - object to update
Throws:
TransactionNotInProgressException
DatabaseIOException

deleteObject

public void deleteObject(PersistentCapableIfc object)
                  throws TransactionNotInProgressException,
                         DatabaseIOException
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.

Parameters:
object - object to delete
Throws:
TransactionNotInProgressException
DatabaseIOException

retrieveObject

public PersistentCapableIfc retrieveObject(long id)
                                    throws TransactionNotInProgressException,
                                           DatabaseIOException
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.

Parameters:
id - identity of object to retrieve
Returns:
PersistentCapableIfc
Throws:
TransactionNotInProgressException
DatabaseIOException

acquireLock

public void acquireLock(PersistentCapableIfc object,
                        int timeout)
                 throws FailedToAcquireLockException,
                        FailedToCreateLockException,
                        TransactionNotInProgressException
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

Parameters:
object - object to lock
Returns:
Object reference to locked object
Throws:
FailedToAcquireLockException
FailedToCreateLockException
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

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.

Returns:
CollectionManagerIfc

getSessionId

public long getSessionId()
Return the session id associated with this object

Returns:
long session identifier

isValid

public boolean isValid()
Check the validity of the session

Returns:
boolean true if the session is valid


Copyright © 1999-2005 The Exolab Group. All Rights Reserved.