EclipseLink 1.0_1.0M2 API Reference - Incubation

org.eclipse.persistence.sessions.broker
Class SessionBroker

java.lang.Object
  extended by DatabaseSessionImpl
      extended by org.eclipse.persistence.sessions.broker.SessionBroker

public class SessionBroker
extends DatabaseSessionImpl

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

Responsibilities:


Field Summary
protected  Sequencing sequencing
           
protected  java.util.Map sessionNamesByClass
           
protected  java.util.Map sessionsByName
           
 
Constructor Summary
  SessionBroker()
          PUBLIC: Create and return a session broker.
protected SessionBroker(java.util.Map sessionNames)
          INTERNAL: Create and return a session broker.
 
Method Summary
 SessionBroker acquireClientSessionBroker()
          PUBLIC: Return a session broker that behaves as a client session broker.
 Session acquireHistoricalSession(AsOfClause clause)
          INTERNAL: Acquires a special historical session for reading objects as of a past time.
 UnitOfWorkImpl acquireUnitOfWork()
          PUBLIC: Return a unit of work for this session broker.
 void addDescriptor(ClassDescriptor 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)
protected  void basicBeginTransaction()
          INTERNAL: Begin the transaction on all child sessions.
protected  void basicCommitTransaction(AbstractSession callingSession)
          INTERNAL: Allow calling session to be passed.
protected  void basicRollbackTransaction(AbstractSession callingSession)
          INTERNAL: Allow calling session to be passed.
 boolean containsQuery(java.lang.String queryName)
          PUBLIC: Return true if the pre-defined query is defined on the session.
protected  SessionBroker copySessionBroker()
          INTERNAL: Return a copy (not using clone) of a session broker.
 Accessor getAccessor(java.lang.Class domainClass)
          INTERNAL: Return the lowlevel database accessor.
 Accessor getAccessor(java.lang.String sessionName)
          INTERNAL: Return the lowlevel database accessor.
 AsOfClause getAsOfClause()
          ADVANCED: Answers the past time this session is as of.
 AbstractSession getExecutionSession(DatabaseQuery query)
          INTERNAL: Gets the session which this query will be executed on.
 AbstractSession getParentIdentityMapSession(DatabaseQuery query, boolean canReturnSelf, boolean terminalOnly)
          INTERNAL: Gets the next link in the chain of sessions followed by a query's check early return, the chain of sessions with identity maps all the way up to the root session.
 Platform 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.
 Sequencing getSequencing()
          PUBLIC: Return the Sequencing object used by the session.
protected  SequencingHome getSequencingHome()
          PROTECTED: Session broker doesn't have SequencingHome.
 AbstractSession getSessionForClass(java.lang.Class domainClass)
          INTERNAL: Return the session to be used for the class.
 AbstractSession getSessionForName(java.lang.String name)
          INTERNAL: Return the session by name.
protected  AbstractSession getSessionForQuery(DatabaseQuery query)
          INTERNAL: Answers the session to be used for the given query.
protected  java.util.Map getSessionNamesByClass()
          INTERNAL: Return sessions indexed by class, each class can only have one default session.
 java.util.Map getSessionsByName()
          INTERNAL: Return sessions indexed by name.
 void initializeDescriptors()
          INTERNAL: Allow each descriptor to initialize any dependancies on this session.
 void initializeIdentityMapAccessor()
          INTERNAL: Set up the IdentityMapManager.
 void initializeSequencing()
          ADVANCED: Creates sequencing object for the session broker.
 java.lang.Object internalExecuteQuery(DatabaseQuery query, AbstractRecord row)
          INTERNAL: Return the results from exeucting the database query.
 void internalRegisterSession(java.lang.String name, AbstractSession session)
          INTERNAL: Register the session under its name.
 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, AbstractSession session)
          PUBLIC: Register the session under its name.
 void release()
          PUBLIC: Release the session.
 void releaseClientSessionBroker()
          Deprecated. Since OracleAS TopLink 10g (10.0.3). Use release().
 void setIntegrityChecker(IntegrityChecker integrityChecker)
          PUBLIC: set the integrityChecker.
 void setLog(java.io.Writer log)
          PUBLIC: Set the message log.
 void setProfiler(SessionProfiler profiler)
          PUBLIC: Set the profiler for the session.
 void setSessionLog(SessionLog log)
          PUBLIC: Set the session log.
protected  void setSessionNameByClass(java.util.HashMap sessionNameByClass)
          INTERNAL: Set sessions indexed by class, each class can only have one default session.
 void setSessionsByName(java.util.Map sessionsByName)
          INTERNAL: Set sessions indexed by name.
 void writesCompleted()
          INTERNAL: This method notifies the accessor that a particular sets of writes has completed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sessionNamesByClass

protected java.util.Map sessionNamesByClass

sessionsByName

protected java.util.Map sessionsByName

sequencing

protected Sequencing sequencing
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.


SessionBroker

protected SessionBroker(java.util.Map sessionNames)
INTERNAL: Create and return a session broker. Used internally to set the Names by Class from the parent. Reduces garbage.

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.


acquireHistoricalSession

public Session acquireHistoricalSession(AsOfClause clause)
                                 throws ValidationException
INTERNAL: Acquires a special historical session for reading objects as of a past time.

Throws:
ValidationException

afterTransaction

public void afterTransaction(boolean committed,
                             boolean isExternalTransaction)
INTERNAL: Called after transaction is completed (committed or rolled back)


acquireUnitOfWork

public UnitOfWorkImpl acquireUnitOfWork()
PUBLIC: Return a unit of work for this session broker. Acquire a client session broker if is a server session broker.

See Also:
UnitOfWorkImpl

addDescriptor

public void addDescriptor(ClassDescriptor descriptor)
PUBLIC: You cannot add a descriptor to a session broker, you must add it to its session.


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.

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.

Throws:
ValidationException

basicBeginTransaction

protected void basicBeginTransaction()
                              throws DatabaseException
INTERNAL: Begin the transaction on all child sessions.

Throws:
DatabaseException

basicCommitTransaction

protected void basicCommitTransaction(AbstractSession callingSession)
                               throws DatabaseException
INTERNAL: Allow calling session to be passed. The calling session is the session who actually invokes commit or rollback transaction, it is used to determine whether the connection needs to be closed when using external connection pool. The connection with a externalConnectionPool used by synchronized UOW should leave open until afterCompletion call back; the connection with a externalConnectionPool used by other type of session should be closed after transaction was finised. Commit the transaction on all child sessions. This assumes that the commit of the transaction will not fail because all of the modification has already taken place and no errors would have occured.

Throws:
DatabaseException

basicRollbackTransaction

protected void basicRollbackTransaction(AbstractSession callingSession)
                                 throws DatabaseException
INTERNAL: Allow calling session to be passed. The calling session is the session who actually invokes commit or rollback transaction, it is used to determine whether the connection needs to be closed when using external connection pool. The connection with a externalConnectionPool used by synchronized UOW should leave open until afterCompletion call back; the connection with a externalConnectionPool used by other type of session should be closed after transaction was finised. Rollback the transaction on all child sessions.

Throws:
DatabaseException

containsQuery

public boolean containsQuery(java.lang.String queryName)
PUBLIC: Return true if the pre-defined query is defined on the session.


copySessionBroker

protected SessionBroker copySessionBroker()
INTERNAL: Return a copy (not using clone) of a session broker.


getAccessor

public 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.


getAccessor

public 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.


getAsOfClause

public AsOfClause getAsOfClause()
ADVANCED: Answers the past time this session is as of. Only meaningfull for special historical sessions.

Returns:
An immutable object representation of the past time. null if no clause set, or this a regular session.
See Also:
org.eclipse.persistence.expressions.AsOfClause, #acquireSessionAsOf(java.lang.Number), #acquireSessionAsOf(java.util.Date), #hasAsOfClause

getParentIdentityMapSession

public AbstractSession getParentIdentityMapSession(DatabaseQuery query,
                                                   boolean canReturnSelf,
                                                   boolean terminalOnly)
INTERNAL: Gets the next link in the chain of sessions followed by a query's check early return, the chain of sessions with identity maps all the way up to the root session.

Used for session broker which delegates to registered sessions, or UnitOfWork which checks parent identity map also.

Parameters:
canReturnSelf - true when method calls itself. If the path starting at this is acceptable. Sometimes true if want to move to the first valid session, i.e. executing on ClientSession when really should be on ServerSession.
terminalOnly - return the session we will execute the call on, not the next step towards it.
Returns:
this if there is no next link in the chain

getExecutionSession

public AbstractSession getExecutionSession(DatabaseQuery query)
INTERNAL: Gets the session which this query will be executed on. Generally will be called immediately before the call is translated, which is immediately before session.executeCall.

Since the execution session also knows the correct datasource platform to execute on, it is often used in the mappings where the platform is needed for type conversion, or where calls are translated.

Is also the session with the accessor. Will return a ClientSession if it is in transaction and has a write connection.

Parameters:
query - may store session name or reference class for brokers case
Returns:
a session with a live accessor

getPlatform

public Platform getPlatform(java.lang.Class domainClass)
INTERNAL: Return the platform for a particular class.


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.


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.


getSessionForClass

public AbstractSession getSessionForClass(java.lang.Class domainClass)
                                   throws ValidationException
INTERNAL: Return the session to be used for the class.

Throws:
ValidationException

getSessionForName

public AbstractSession getSessionForName(java.lang.String name)
                                  throws ValidationException
INTERNAL: Return the session by name.

Throws:
ValidationException

getSessionForQuery

protected AbstractSession getSessionForQuery(DatabaseQuery query)
INTERNAL: Answers the session to be used for the given query.


getSessionNamesByClass

protected java.util.Map getSessionNamesByClass()
INTERNAL: Return sessions indexed by class, each class can only have one default session.


getSessionsByName

public java.util.Map getSessionsByName()
INTERNAL: Return sessions indexed by name.


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.


initializeIdentityMapAccessor

public void initializeIdentityMapAccessor()
INTERNAL: Set up the IdentityMapManager. This method allows subclasses of Session to override the default IdentityMapManager functionality.


internalExecuteQuery

public java.lang.Object internalExecuteQuery(DatabaseQuery query,
                                             AbstractRecord 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.

Throws:
DatabaseException
QueryException

isBroker

public boolean isBroker()
INTERNAL: Returns true if the session is a session Broker.


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.


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.


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.

Throws:
DatabaseException

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.

Throws:
DatabaseException

logout

public void logout()
            throws DatabaseException
PUBLIC: Disconnect from all databases.

Throws:
EclipseLinkException - 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,
                            AbstractSession 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.


internalRegisterSession

public void internalRegisterSession(java.lang.String name,
                                    AbstractSession session)
INTERNAL: 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. Used for client session broker


release

public void release()
PUBLIC: Release the session. This does nothing by default, but allows for other sessions such as the ClientSession to do something.


releaseClientSessionBroker

public void releaseClientSessionBroker()
Deprecated. Since OracleAS TopLink 10g (10.0.3). Use release().

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 ClassDescriptor Exceptions.


setSessionLog

public void setSessionLog(SessionLog log)
PUBLIC: Set the session log.

See Also:
#logMessages()

setLog

public void setLog(java.io.Writer log)
PUBLIC: Set the message log.

See Also:
#logMessages()

setProfiler

public void setProfiler(SessionProfiler profiler)
PUBLIC: Set the profiler for the session. This allows for performance operations to be profiled.


setSessionNameByClass

protected void setSessionNameByClass(java.util.HashMap sessionNameByClass)
INTERNAL: Set sessions indexed by class, each class can only have one default session.


setSessionsByName

public void setSessionsByName(java.util.Map sessionsByName)
INTERNAL: Set sessions indexed by name.


writesCompleted

public void writesCompleted()
INTERNAL: This method notifies the accessor that a particular sets of writes has completed. This notification can be used for such thing as flushing the batch mechanism


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.


getSequencingHome

protected SequencingHome getSequencingHome()
PROTECTED: Session broker doesn't have SequencingHome.


getSequencing

public Sequencing getSequencing()
PUBLIC: Return the Sequencing object used by the session.


EclipseLink 1.0_1.0M2 API Reference - Incubation