oracle.toplink.sessionbroker
Class SessionBroker

java.lang.Object
oracle.toplink.publicinterface.Session
oracle.toplink.publicinterface.DatabaseSession
oracle.toplink.sessionbroker.SessionBroker

All Implemented Interfaces:

java.lang.Cloneable, CommandProcessor, DatabaseSession, java.io.Serializable, Session

public class SessionBroker

extends oracle.toplink.publicinterface.DatabaseSession

Purpose: Provide a single view to a TopLink session that transparently accesses multple databases.

Responsibilities:

• Broker queries to the appropriate child sessions.
• Use a simplified two-stage commit policy on commit of transaction.
• Support brokered units of work.

See Also:

Serialized Form

Field Summary

Fields inherited from class oracle.toplink.publicinterface.DatabaseSession

deploymentLogin, projectClassName, projectPath

Fields inherited from class oracle.toplink.publicinterface.Session

isInBroker, Logging, usesOldCommit

Fields inherited from interface oracle.toplink.remotecommand.CommandProcessor

LOG_DEBUG, LOG_ERROR, LOG_INFO, LOG_WARNING

Constructor Summary

SessionBroker()
PUBLIC: Create and return a session broker.

Method Summary

SessionBroker	acquireClientSessionBroker() PUBLIC: Return a session broker that behaves as a client session broker.
oracle.toplink.publicinterface.UnitOfWork	acquireUnitOfWork() PUBLIC: Return a unit of work for this session broker.
void	addDescriptor(Descriptor descriptor) PUBLIC: You cannot add a descriptor to a session broker, you must add it to its session.
void	addDescriptors(Project project) PUBLIC: You cannot add a project to a session broker, you must add it to its session.
void	addDescriptors(java.util.Vector descriptors) PUBLIC: You cannot add descriptors to a session broker, you must add them to its session.
void	afterTransaction(boolean committed, boolean isExternalTransaction) INTERNAL: Called after transaction is completed (committed or rolled back)
boolean	containsQuery(java.lang.String queryName) PUBLIC: Return true if the pre-defined query is defined on the session.
oracle.toplink.internal.databaseaccess.Accessor	getAccessor(java.lang.Class domainClass) INTERNAL: Return the lowlevel database accessor.
oracle.toplink.internal.databaseaccess.Accessor	getAccessor(java.lang.String sessionName) INTERNAL: Return the lowlevel database accessor.
DatabasePlatform	getPlatform(java.lang.Class domainClass) INTERNAL: Return the platform for a particular class.
DatabaseQuery	getQuery(java.lang.String name) PUBLIC: Return the query from the session pre-defined queries with the given name.
DatabaseQuery	getQuery(java.lang.String name, java.util.Vector arguments) PUBLIC: Return the query from the session pre-defined queries with the given name and argument types.
oracle.toplink.internal.sequencing.Sequencing	getSequencing() PUBLIC: Return the Sequencing object used by the session.
oracle.toplink.publicinterface.Session	getSessionForClass(java.lang.Class domainClass) INTERNAL: Return the session to be used for the class.
oracle.toplink.publicinterface.Session	getSessionForName(java.lang.String name) INTERNAL: Return the session by name.
java.util.Vector	getSessionNames() Return the list of sessions associated with this SessionBroker
java.util.Hashtable	getSessionsByName() INTERNAL: Return sessions indexed by name.
void	initializeAllIdentityMaps() PUBLIC:: Reset the entire object cache.
void	initializeDescriptors() INTERNAL: Allow each descriptor to initialize any dependancies on this session.
void	initializeIdentityMaps() PUBLIC:: Reset the entire local object caches.
void	initializeSequencing() ADVANCED: Creates sequencing object for the session broker.
java.lang.Object	internalExecuteQuery(DatabaseQuery query, DatabaseRow row) INTERNAL: Return the results from exeucting the database query.
boolean	isBroker() INTERNAL: Returns true if the session is a session Broker.
boolean	isClientSessionBroker() PUBLIC: Return if this session is a client session broker.
boolean	isConnected() PUBLIC: Return if all sessions are still connected to the database.
boolean	isServerSessionBroker() PUBLIC: Return if this session is a server session broker.
boolean	isSessionBroker() INTERNAL: Return if this session is a session broker.
void	login() PUBLIC: Connect to the database using the predefined login.
void	login(java.lang.String userName, java.lang.String password) PUBLIC: Connect to the database using the predefined login.
void	logout() PUBLIC: Disconnect from all databases.
void	registerSession(java.lang.String name, oracle.toplink.publicinterface.Session session) PUBLIC: Register the session under its name.
void	registerSession(java.lang.String name, Session session) PUBLIC: Register the session under its name.
void	releaseClientSessionBroker() PUBLIC: Called on a client Session Broker.
void	setIntegrityChecker(IntegrityChecker integrityChecker) PUBLIC: set the integrityChecker.
void	setLog(java.io.Writer log) PUBLIC: Set the writer to which an accessor writes logged messages.
void	setProfiler(SessionProfiler profiler) PUBLIC: Set the profiler for the session.
void	setSessionNames(java.util.Vector sessionNames) Set the list of session names associated with this SessionBroker
void	setSessionsByName(java.util.Hashtable sessionsByName) INTERNAL: Set sessions indexed by name.
void	setShouldLogMessages(boolean shouldLog) PUBLIC: Log all messages including executed SQL commands to the default output.

Methods inherited from class oracle.toplink.publicinterface.DatabaseSession

connect, disconnect, getDeploymentLogin, getDescriptors, getProjectClassName, getProjectPath, getSequencingControl, initializeDescriptorIfSessionAlive, initializeDescriptors, initializeDescriptors, isDatabaseSession, login, login, setDeploymentLogin, setProjectClassName, setProjectPath, writeAllObjects, writeAllObjects

Methods inherited from class oracle.toplink.publicinterface.Session

acquireIdentityMapDeferredLock, acquireIdentityMapLock, acquireNonSynchronizedUnitOfWork, addAlias, addAliasesFromProject, addQuery, beginTransaction, clearIntegrityChecker, clearLastDescriptorAccessed, clearProfile, clone, commitTransaction, compareObjects, compareObjectsDontMatch, containsObjectInIdentityMap, containsObjectInIdentityMap, copyObject, copyObject, copyReadOnlyClasses, decrementMergesPending, deleteAllObjects, deleteAllObjects, deleteObject, doesObjectExist, dontLogMessages, dontLogSQL, endOperationProfile, executeCall, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, getAccessor, getActiveSession, getActiveUnitOfWork, getAliasDescriptors, getAllFromIdentityMap, getAllFromIdentityMap, getAllQueries, getBroker, getCacheSynchronizationManager, getCommandManager, getCommitManager, getDefaultReadOnlyClasses, getDescriptor, getDescriptor, getDescriptorForAlias, getEventManager, getExceptionHandler, getExceptionHandlerClass, getExternalTransactionController, getExternalTransactionControllerClass, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getFromIdentityMapWithDeferredLock, getIdentityMapManager, getIntegrityChecker, getLog, getLoggingStream, getLogin, getName, getNextQueryId, getNextSequenceNumberValue, getNumberOfActiveUnitsOfWork, getPlatform, getProfiler, getProject, getProperties, getProperty, getQueries, getSessionLog, getTransactionMutex, getWrapper, getWriteLockValue, getWriteLockValue, handleException, hasBroker, hasCacheSynchronizationManager, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, incrementMergesPending, initializeIdentityMap, insertObject, isClassReadOnly, isClientSession, isDistributedSession, isInBroker, isInProfile, isInTransaction, isProxySession, isRemoteSession, isRemoteUnitOfWork, isServerSession, isUnitOfWork, keyFromObject, log, logDebug, logDebug, logDebug, logDebug, logException, logMessage, logMessage, logMessage, logMessage, logMessage, logMessages, logSQL, mergesPending, printIdentityMap, printIdentityMaps, processCommand, putInIdentityMap, putInIdentityMap, putInIdentityMap, readAllObjects, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, readObject, refreshAndLockObject, refreshAndLockObject, refreshObject, release, releaseUnitOfWork, removeFromIdentityMap, removeFromIdentityMap, removeProperty, removeQuery, removeQuery, rollbackTransaction, setAccessor, setAliasDescriptors, setBroker, setCacheSynchronizationManager, setCommandManager, setCommitManager, setEventManager, setExceptionHandler, setExceptionHandlerClass, setExternalTransactionController, setExternalTransactionControllerClass, setLoggingStream, setLogin, setName, setProject, setProperties, setProperty, setSessionLog, setShouldLogSQL, setShouldPropagateChanges, setUseOldCommit, setWasJTSTransactionInternallyStarted, setWrapper, shouldLogMessages, shouldLogMessages, shouldLogSQL, shouldPropagateChanges, startOperationProfile, toString, unwrapObject, updatedCacheKeyInIdentityMap, updateObject, updateWriteLockValue, updateWriteLockValue, usesExternalTransactionController, usesOldCommit, validateCache, verifyDelete, wasJTSTransactionInternallyStarted, wrapObject, writeObject

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface oracle.toplink.sessions.DatabaseSession

beginTransaction, commitTransaction, deleteAllObjects, deleteAllObjects, deleteObject, insertObject, isInTransaction, refreshAndLockObject, refreshAndLockObject, rollbackTransaction, setExternalTransactionController, setLogin, updateObject, writeObject

Methods inherited from interface oracle.toplink.sessions.Session

addQuery, clearIntegrityChecker, clearProfile, containsObjectInIdentityMap, containsObjectInIdentityMap, copyObject, copyObject, doesObjectExist, dontLogMessages, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, getActiveSession, getActiveUnitOfWork, getAllFromIdentityMap, getAllFromIdentityMap, getCacheSynchronizationManager, getCommandManager, getDescriptor, getDescriptor, getEventManager, getExceptionHandler, getExternalTransactionController, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getIntegrityChecker, getLog, getLogin, getName, getNextSequenceNumberValue, getProfiler, getProject, getProperties, getProperty, getQueries, getSessionLog, getWriteLockValue, getWriteLockValue, handleException, hasCacheSynchronizationManager, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, initializeIdentityMap, isClientSession, isDistributedSession, isInProfile, isProxySession, isRemoteSession, isServerSession, isUnitOfWork, keyFromObject, log, logDebug, logDebug, logException, logMessage, logMessage, logMessages, printIdentityMap, printIdentityMaps, putInIdentityMap, putInIdentityMap, putInIdentityMap, readAllObjects, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, readObject, refreshObject, release, removeFromIdentityMap, removeFromIdentityMap, removeProperty, removeQuery, setCacheSynchronizationManager, setCommandManager, setExceptionHandler, setName, setProperty, setSessionLog, shouldLogMessages, updateWriteLockValue, updateWriteLockValue, usesExternalTransactionController, validateCache

Constructor Detail

SessionBroker

public SessionBroker()

PUBLIC: Create and return a session broker. Because a session broker has multiple sessions it does not used a login.

Method Detail

acquireClientSessionBroker

public SessionBroker acquireClientSessionBroker()

PUBLIC: Return a session broker that behaves as a client session broker. An aquire session broker is done under the covers on each session inside the session broker, and a new broker is returned. NOTE: when finished with the client broker, it should be releases. See releaseClientSessionBroker.

afterTransaction

public void afterTransaction(boolean committed,
                             boolean isExternalTransaction)

INTERNAL: Called after transaction is completed (committed or rolled back)

Overrides:

afterTransaction in class oracle.toplink.publicinterface.DatabaseSession

getSessionNames

public java.util.Vector getSessionNames()

Return the list of sessions associated with this SessionBroker

Returns:

java.util.Vector

setSessionNames

public void setSessionNames(java.util.Vector sessionNames)

Set the list of session names associated with this SessionBroker

acquireUnitOfWork

public oracle.toplink.publicinterface.UnitOfWork acquireUnitOfWork()

PUBLIC: Return a unit of work for this session broker. Acquire a client session broker if is a server session broker.

Specified by:

acquireUnitOfWork in interface Session

Overrides:

acquireUnitOfWork in class oracle.toplink.publicinterface.Session

See Also:

UnitOfWork

addDescriptor

public void addDescriptor(Descriptor descriptor)

PUBLIC: You cannot add a descriptor to a session broker, you must add it to its session.

Specified by:

addDescriptor in interface DatabaseSession

Overrides:

addDescriptor in class oracle.toplink.publicinterface.DatabaseSession

See Also:

DatabaseSession.addDescriptors(Vector), DatabaseSession.addDescriptors(Project)

addDescriptors

public void addDescriptors(java.util.Vector descriptors)
                    throws ValidationException

PUBLIC: You cannot add descriptors to a session broker, you must add them to its session.

Specified by:

addDescriptors in interface DatabaseSession

Overrides:

addDescriptors in class oracle.toplink.publicinterface.DatabaseSession

Throws:

ValidationException

addDescriptors

public void addDescriptors(Project project)
                    throws ValidationException

PUBLIC: You cannot add a project to a session broker, you must add it to its session.

Specified by:

addDescriptors in interface DatabaseSession

Overrides:

addDescriptors in class oracle.toplink.publicinterface.DatabaseSession

Throws:

ValidationException

containsQuery

public boolean containsQuery(java.lang.String queryName)

PUBLIC: Return true if the pre-defined query is defined on the session.

Specified by:

containsQuery in interface Session

Overrides:

containsQuery in class oracle.toplink.publicinterface.Session

getAccessor

public oracle.toplink.internal.databaseaccess.Accessor getAccessor(java.lang.Class domainClass)

INTERNAL: Return the lowlevel database accessor. The database accesor is used for direct database access. The right accessor for this broker will be returned.

Overrides:

getAccessor in class oracle.toplink.publicinterface.Session

getAccessor

public oracle.toplink.internal.databaseaccess.Accessor getAccessor(java.lang.String sessionName)

INTERNAL: Return the lowlevel database accessor. The database accesor is used for direct database access. The right accessor for this broker will be returned.

Overrides:

getAccessor in class oracle.toplink.publicinterface.Session

getPlatform

public DatabasePlatform getPlatform(java.lang.Class domainClass)

INTERNAL: Return the platform for a particular class.

Overrides:

getPlatform in class oracle.toplink.publicinterface.Session

getQuery

public DatabaseQuery getQuery(java.lang.String name)

PUBLIC: Return the query from the session pre-defined queries with the given name. This allows for common queries to be pre-defined, reused and executed by name.

Specified by:

getQuery in interface Session

Overrides:

getQuery in class oracle.toplink.publicinterface.Session

getQuery

public DatabaseQuery getQuery(java.lang.String name,
                              java.util.Vector arguments)

PUBLIC: Return the query from the session pre-defined queries with the given name and argument types. This allows for common queries to be pre-defined, reused and executed by name. This method should be used if the Session has multiple queries with the same name but different arguments.

Overrides:

getQuery in class oracle.toplink.publicinterface.Session

See Also:

Session.getQuery(String)

getSessionForClass

public oracle.toplink.publicinterface.Session getSessionForClass(java.lang.Class domainClass)
                                                          throws ValidationException

INTERNAL: Return the session to be used for the class.

Overrides:

getSessionForClass in class oracle.toplink.publicinterface.Session

Throws:

ValidationException

getSessionForName

public oracle.toplink.publicinterface.Session getSessionForName(java.lang.String name)
                                                         throws ValidationException

INTERNAL: Return the session by name.

Throws:

ValidationException

getSessionsByName

public java.util.Hashtable getSessionsByName()

INTERNAL: Return sessions indexed by name.

initializeAllIdentityMaps

public void initializeAllIdentityMaps()

PUBLIC:: Reset the entire object cache. This method blows away both this session's and its parents caches, including the server cache or any other cache. This throws away any objects that have been read in. Extream caution should be used before doing this because object identity will no longer be maintained for any objects currently read in. This should only be called if the application knows that it no longer has references to object held in the cache.

Specified by:

initializeAllIdentityMaps in interface Session

Overrides:

initializeAllIdentityMaps in class oracle.toplink.publicinterface.Session

initializeDescriptors

public void initializeDescriptors()

INTERNAL: Allow each descriptor to initialize any dependancies on this session. This is done in two passes to allow the inheritence to be resolved first. Normally the descriptors are added before login, then initialized on login.

Overrides:

initializeDescriptors in class oracle.toplink.publicinterface.DatabaseSession

initializeIdentityMaps

public void initializeIdentityMaps()

PUBLIC:: Reset the entire local object caches. This throws away any objects that have been read in. Extream caution should be used before doing this because object identity will no longer be maintained for any objects currently read in. This should only be called if the application knows that it no longer has references to object held in the cache.

Specified by:

initializeIdentityMaps in interface Session

Overrides:

initializeIdentityMaps in class oracle.toplink.publicinterface.Session

internalExecuteQuery

public java.lang.Object internalExecuteQuery(DatabaseQuery query,
DatabaseRow row)
                                      throws DatabaseException,
QueryException

INTERNAL: Return the results from exeucting the database query. the arguments should be a database row with raw data values. Find the correct child session to broker the query to, and return the result of the session executing the query.

Overrides:

internalExecuteQuery in class oracle.toplink.publicinterface.Session

Throws:

DatabaseException

QueryException

isBroker

public boolean isBroker()

INTERNAL: Returns true if the session is a session Broker.

Overrides:

isBroker in class oracle.toplink.publicinterface.Session

isClientSessionBroker

public boolean isClientSessionBroker()

PUBLIC: Return if this session is a client session broker.

isConnected

public boolean isConnected()

PUBLIC: Return if all sessions are still connected to the database.

Specified by:

isConnected in interface Session

Overrides:

isConnected in class oracle.toplink.publicinterface.Session

isServerSessionBroker

public boolean isServerSessionBroker()

PUBLIC: Return if this session is a server session broker.

isSessionBroker

public boolean isSessionBroker()

INTERNAL: Return if this session is a session broker.

Specified by:

isSessionBroker in interface Session

Overrides:

isSessionBroker in class oracle.toplink.publicinterface.Session

login

public void login()
           throws DatabaseException

PUBLIC: Connect to the database using the predefined login. This connects all of the child sessions and expects that they are in a valid state to be connected.

Specified by:

login in interface DatabaseSession

Overrides:

login in class oracle.toplink.publicinterface.DatabaseSession

Throws:

DatabaseException

See Also:

DatabaseSession.login(Login)

login

public void login(java.lang.String userName,
                  java.lang.String password)
           throws DatabaseException

PUBLIC: Connect to the database using the predefined login. This connects all of the child sessions and expects that they are in a valid state to be connected.

Specified by:

login in interface DatabaseSession

Overrides:

login in class oracle.toplink.publicinterface.DatabaseSession

Throws:

DatabaseException

logout

public void logout()
            throws DatabaseException

PUBLIC: Disconnect from all databases.

Specified by:

logout in interface DatabaseSession

Overrides:

logout in class oracle.toplink.publicinterface.DatabaseSession

Throws:

TopLinkException - if a transaction is active, you must rollback any active transaction before logout.

DatabaseException - the database will also raise an error if their is an active transaction, or a general error occurs.

registerSession

public void registerSession(java.lang.String name,
                            oracle.toplink.publicinterface.Session session)

PUBLIC: Register the session under its name. All of the session's descriptors must have already been registered. The session should not be connected and descriptors should not be initialized.

registerSession

public void registerSession(java.lang.String name,
Session session)

PUBLIC: Register the session under its name. All of the session's descriptors must have already been registered. The session should not be connected and descriptors should not be initialized.

releaseClientSessionBroker

public void releaseClientSessionBroker()

PUBLIC: Called on a client Session Broker. Releases all the client sessions held in this broker. Should be used in conjunction with acquireClientSessionBroker()

setIntegrityChecker

public void setIntegrityChecker(IntegrityChecker integrityChecker)

PUBLIC: set the integrityChecker. IntegrityChecker holds all the Descriptor Exceptions.

Specified by:

setIntegrityChecker in interface Session

Overrides:

setIntegrityChecker in class oracle.toplink.publicinterface.Session

setLog

public void setLog(java.io.Writer log)

PUBLIC: Set the writer to which an accessor writes logged messages. If not set, this reference defaults to System.out. To enable loging logMessages is used.

Specified by:

setLog in interface Session

Overrides:

setLog in class oracle.toplink.publicinterface.Session

See Also:

Session.logMessages()

setProfiler

public void setProfiler(SessionProfiler profiler)

PUBLIC: Set the profiler for the session. This allows for performance operations to be profiled.

Specified by:

setProfiler in interface Session

Overrides:

setProfiler in class oracle.toplink.publicinterface.Session

setSessionsByName

public void setSessionsByName(java.util.Hashtable sessionsByName)

INTERNAL: Set sessions indexed by name.

setShouldLogMessages

public void setShouldLogMessages(boolean shouldLog)

PUBLIC: Log all messages including executed SQL commands to the default output. Currently, default output is the system out stream. Output can be set to any writer. Dispatch to all sessions.

Specified by:

setShouldLogMessages in interface Session

Overrides:

setShouldLogMessages in class oracle.toplink.publicinterface.Session

See Also:

Session.setLog(Writer)

initializeSequencing

public void initializeSequencing()

ADVANCED: Creates sequencing object for the session broker. Typically there is no need for the user to call this method - it is called by login() and acquireClientSessionBroker.

Overrides:

initializeSequencing in class oracle.toplink.publicinterface.DatabaseSession

getSequencing

public oracle.toplink.internal.sequencing.Sequencing getSequencing()

PUBLIC: Return the Sequencing object used by the session.

Overrides:

getSequencing in class oracle.toplink.publicinterface.DatabaseSession