oracle.toplink.essentials.internal.sessions

Class DatabaseSessionImpl

java.lang.Object

oracle.toplink.essentials.internal.sessions.AbstractSession

oracle.toplink.essentials.internal.sessions.DatabaseSessionImpl

All Implemented Interfaces:

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

Direct Known Subclasses:

ServerSession

public class DatabaseSessionImpl
extends AbstractSession
implements DatabaseSession

Implementation of oracle.toplink.essentials.sessions.DatabaseSession The public interface should be used by public API, the implementation should be used internally.

See Also:

Purpose: Define the implementation for a single user/single connection TopLink session.

Description: The session is the primary interface into TopLink, the application should do all of its reading and writing of objects through the session. The session also manages transactions and units of work. The database session is intended for usage in two-tier client-server applications. Although it could be used in a server situation, it is limitted to only having a single database connection and only allows a single open database transaction.

Responsibilities:

• Connecting/disconnecting.
• Reading and writing objects.
• Transaction and unit of work support.
• Identity maps and caching.

, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	isLoggedIn INTERNAL Indicate if this session is logged in.

Fields inherited from class oracle.toplink.essentials.internal.sessions.AbstractSession

accessor, broker, commitManager, ejbqlPlaceHolderQueries, eventManager, exceptionHandler, externalTransactionController, identityMapAccessor, integrityChecker, isInProfile, lastDescriptorAccessed, logSessionString, name, numberOfActiveUnitsOfWork, platform, profiler, project, properties, queries, sessionLog, transactionMutex, wasJTSTransactionInternallyStarted

Constructor Summary

Constructors

Constructor and Description
DatabaseSessionImpl() INTERNAL: Create and return a new default database session.
DatabaseSessionImpl(Login login) PUBLIC: Create and return a new session.
DatabaseSessionImpl(Project project) PUBLIC: Create and return a new session.

Method Summary

Modifier and Type	Method and Description
void	addDescriptor(ClassDescriptor descriptor) PUBLIC: Add the descriptor to the session.
void	addDescriptors(Project project) PUBLIC: Add the descriptors to the session from the Project.
void	addDescriptors(java.util.Vector descriptors) PUBLIC: Add the descriptors to the session.
void	afterTransaction(boolean committed, boolean isExternalTransaction) INTERNAL: Called after transaction is completed (committed or rolled back)
void	connect() INTERNAL: Connect the session only.
void	connect(boolean updatePlatform) INTERNAL: Connect the session only.
void	disconnect() INTERNAL: Disconnect the accessor only.
protected void	finalize() INTERNAL: Logout in case still connected.
long	getConnectedTime() PUBLIC: Answer the time that this session got connected.
java.util.Map	getDescriptors() PUBLIC: Return all registered descriptors.
protected Login	getReadLogin() INTERNAL: Return the login for the read connection.
Sequencing	getSequencing() INTERNAL: Return the Sequencing object used by the session.
SequencingControl	getSequencingControl() PUBLIC: Return SequencingControl which used for sequencing setup and customization including management of sequencing preallocation.
protected SequencingHome	getSequencingHome() INTERNAL: Return SequencingHome which used to obtain all sequence-related interfaces for DatabaseSession
ServerPlatform	getServerPlatform() PUBLIC: Answer the server platform to handle server specific behaviour for WLS, Oc4j, etc.
void	initializeConnectedTime() PUBLIC: Initialize the time that this session got connected.
void	initializeDescriptorIfSessionAlive(ClassDescriptor descriptor) INTERNAL: A descriptor may have been added after the session is logged in.
void	initializeDescriptors() INTERNAL: Allow each descriptor to initialize any dependancies on this session.
void	initializeDescriptors(java.util.Map descriptors) INTERNAL: Allow each descriptor to initialize any dependancies on this session.
void	initializeDescriptors(java.util.Vector descriptors) INTERNAL: Allow each descriptor to initialize any dependancies on this session.
void	initializeSequencing() INTERNAL: Creates sequencing object
boolean	isDatabaseSession() INTERNAL: Return if this session is a database session.
void	login() PUBLIC: Connect to the database using the predefined login.
void	login(Login login) PUBLIC: Connect to the database using the given login.
void	login(java.lang.String userName, java.lang.String password) PUBLIC: Connect to the database using the given user name and password.
void	loginAndDetectDatasource() PUBLIC: Connect to the database using the predefined login.
void	logout() PUBLIC: Disconnect from the database.
protected void	postConnectDatasource() INTERNAL: This method includes all of the code that is issued after the datasource is connected to.
protected void	preConnectDatasource() INTERNAL: This method includes all of the code that is issued before the datasource is connected to.
protected void	setSequencingHome(SequencingHome sequencingHome) INTERNAL: Set the SequencingHome object used by the session.
void	setServerPlatform(ServerPlatform newServerPlatform) PUBLIC: Set the server platform to handle server specific behaviour for WLS, Oc4j, etc This is not permitted after the session is logged in.
void	writeAllObjects(java.util.Collection domainObjects) PUBLIC: Write all of the objects and all of their privately owned parts in the database.
void	writeAllObjects(java.util.Vector domainObjects) PUBLIC: Write all of the objects and all of their privately owned parts in the database.

Methods inherited from class oracle.toplink.essentials.internal.sessions.AbstractSession

acquireNonSynchronizedUnitOfWork, acquireUnitOfWork, addAlias, addEjbqlPlaceHolderQuery, addQuery, addQuery, basicBeginTransaction, basicCommitTransaction, basicRollbackTransaction, beginExternalTransaction, beginTransaction, clearIntegrityChecker, clearLastDescriptorAccessed, clearProfile, clone, commitExternalTransaction, commitTransaction, compareObjects, compareObjectsDontMatch, config, containsQuery, copyObject, copyObject, copyReadOnlyClasses, deleteAllObjects, deleteAllObjects, deleteObject, doesObjectExist, dontLogMessages, endOperationProfile, executeCall, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, fine, finer, finest, getAccessor, getAccessor, getAccessor, getActiveSession, getActiveUnitOfWork, getAliasDescriptors, getAllQueries, getBroker, getClassDescriptor, getClassDescriptor, getClassDescriptorForAlias, getCommitManager, getDatasourceLogin, getDatasourcePlatform, getDefaultReadOnlyClasses, getDescriptor, getDescriptor, getDescriptorForAlias, getEjbqlPlaceHolderQueries, getEventManager, getExceptionHandler, getExceptionHandlerClass, getExecutionSession, getExternalTransactionController, getIdentityMapAccessor, getIdentityMapAccessorInstance, getIntegrityChecker, getLog, getLogin, getLogLevel, getLogLevel, getLogSessionString, getName, getNextQueryId, getNextSequenceNumberValue, getNumberOfActiveUnitsOfWork, getParentIdentityMapSession, getParentIdentityMapSession, getPlatform, getPlatform, getProfiler, getProject, getProperties, getProperty, getQueries, getQuery, getQuery, getRootSession, getSessionForClass, getSessionLog, getSessionTypeString, getTransactionMutex, handleException, handleSevere, hasBroker, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, hasProperties, incrementProfile, info, initializeIdentityMapAccessor, insertObject, internalExecuteQuery, isBroker, isClassReadOnly, isClassReadOnly, isClientSession, isConnected, isDistributedSession, isInBroker, isInProfile, isInTransaction, isRemoteSession, isRemoteUnitOfWork, isServerSession, isSessionBroker, isUnitOfWork, keyFromObject, keyFromObject, log, log, log, log, log, log, log, log, log, log, logMessage, logThrowable, prepareDatabaseQuery, processEJBQLQueries, processEJBQLQueries, readAllObjects, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, readObject, refreshAndLockObject, refreshAndLockObject, refreshObject, release, releaseUnitOfWork, removeProperty, removeQuery, removeQuery, rollbackExternalTransaction, rollbackTransaction, setAccessor, setBroker, setCommitManager, setDatasourceLogin, setEventManager, setExceptionHandler, setExternalTransactionController, setIntegrityChecker, setIsInProfile, setLog, setLogin, setLogin, setLogLevel, setName, setNumberOfActiveUnitsOfWork, setProfiler, setProject, setProperties, setProperty, setQueries, setSessionLog, setTransactionMutex, setWasJTSTransactionInternallyStarted, severe, shouldLog, shouldLogMessages, startOperationProfile, toString, unwrapObject, updateObject, updateProfile, validateQuery, verifyDelete, warning, wasJTSTransactionInternallyStarted, wrapObject, writeAllObjects, writeAllObjectsWithChangeSet, writeObject, writesCompleted

Methods inherited from class java.lang.Object

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

Methods inherited from interface oracle.toplink.essentials.sessions.DatabaseSession

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

Methods inherited from interface oracle.toplink.essentials.sessions.Session

acquireUnitOfWork, addEjbqlPlaceHolderQuery, addQuery, clearIntegrityChecker, clearProfile, containsQuery, copyObject, copyObject, doesObjectExist, dontLogMessages, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, getActiveSession, getActiveUnitOfWork, getClassDescriptor, getClassDescriptor, getClassDescriptorForAlias, getDatasourceLogin, getDatasourcePlatform, getDescriptor, getDescriptor, getDescriptorForAlias, getEjbqlPlaceHolderQueries, getEventManager, getExceptionHandler, getExternalTransactionController, getIdentityMapAccessor, getIntegrityChecker, getLog, getLogin, getLogLevel, getLogLevel, getName, getNextSequenceNumberValue, getPlatform, getProfiler, getProject, getProperties, getProperty, getQueries, getQuery, getQuery, getSessionLog, handleException, handleSevere, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, isClientSession, isConnected, isDistributedSession, isInProfile, isRemoteSession, isRemoteUnitOfWork, isServerSession, isSessionBroker, isUnitOfWork, keyFromObject, log, log, logMessage, logThrowable, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, refreshObject, release, removeProperty, removeQuery, setExceptionHandler, setIntegrityChecker, setLog, setLogLevel, setName, setProfiler, setProperty, setSessionLog, shouldLog, shouldLogMessages

Field Detail

isLoggedIn

protected boolean isLoggedIn

INTERNAL Indicate if this session is logged in.

Constructor Detail

DatabaseSessionImpl

public DatabaseSessionImpl()

INTERNAL: Create and return a new default database session. Used for EJB SessionManager to instantiate a database session

DatabaseSessionImpl

public DatabaseSessionImpl(Login login)

PUBLIC: Create and return a new session. By giving the login information on creation this allows the session to initialize itself to the platform given in the login. This constructor does not return a connected session. To connect the session to the database login() must be sent to it. The login(userName, password) method may also be used to connect the session, this allows for the user name and password to be given at login but for the other database information to be provided when the session is created.

DatabaseSessionImpl

public DatabaseSessionImpl(Project project)

PUBLIC: Create and return a new session. This constructor does not return a connected session. To connect the session to the database login() must be sent to it. The login(userName, password) method may also be used to connect the session, this allows for the user name and password to be given at login but for the other database information to be provided when the session is created.

Method Detail

setSequencingHome

protected void setSequencingHome(SequencingHome sequencingHome)

INTERNAL: Set the SequencingHome object used by the session.

getSequencingHome

protected SequencingHome getSequencingHome()

INTERNAL: Return SequencingHome which used to obtain all sequence-related interfaces for DatabaseSession

getSequencingControl

public SequencingControl getSequencingControl()

PUBLIC: Return SequencingControl which used for sequencing setup and customization including management of sequencing preallocation.

Specified by:

getSequencingControl in interface DatabaseSession

getSequencing

public Sequencing getSequencing()

INTERNAL: Return the Sequencing object used by the session.

Overrides:

getSequencing in class AbstractSession

initializeSequencing

public void initializeSequencing()

INTERNAL: Creates sequencing object

afterTransaction

public void afterTransaction(boolean committed,
                             boolean isExternalTransaction)

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

Overrides:

afterTransaction in class AbstractSession

addDescriptor

public void addDescriptor(ClassDescriptor descriptor)

PUBLIC: Add the descriptor to the session. All persistent classes must have a descriptor registered for them with the session. It is best to add the descriptors before login, if added after login the order in which descriptors are added is dependant on inheritice and references unless the addDescriptors method is used.

Specified by:

addDescriptor in interface DatabaseSession

See Also:

addDescriptors(Vector), addDescriptors(oracle.toplink.essentials.sessions.Project)

addDescriptors

public void addDescriptors(java.util.Vector descriptors)

PUBLIC: Add the descriptors to the session. All persistent classes must have a descriptor registered for them with the session. This method allows for a batch of descriptors to be added at once so that TopLink can resolve the dependancies between the descriptors and perform initialization optimially.

Specified by:

addDescriptors in interface DatabaseSession

addDescriptors

public void addDescriptors(Project project)

PUBLIC: Add the descriptors to the session from the Project. This can be used to combine the descriptors from multiple projects into a single session. This can be called after the session has been connected as long as there are no external dependencies.

Specified by:

addDescriptors in interface DatabaseSession

connect

public void connect()
             throws DatabaseException

INTERNAL: Connect the session only.

Throws:

DatabaseException

connect

public void connect(boolean updatePlatform)
             throws DatabaseException

INTERNAL: Connect the session only.

Throws:

DatabaseException

disconnect

public void disconnect()
                throws DatabaseException

INTERNAL: Disconnect the accessor only.

Throws:

DatabaseException

getServerPlatform

public ServerPlatform getServerPlatform()

PUBLIC: Answer the server platform to handle server specific behaviour for WLS, Oc4j, etc. If the user wants a different external transaction controller class or to provide some different behaviour than the provided ServerPlatform(s), we recommend subclassing oracle.toplink.essentials.platform.server.ServerPlatformBase (or a subclass), and overriding: ServerPlatformBase.getExternalTransactionControllerClass() ServerPlatformBase.registerMBean() ServerPlatformBase.unregisterMBean() for the desired behaviour.

Specified by:

getServerPlatform in interface DatabaseSession

Overrides:

getServerPlatform in class AbstractSession

See Also:

ServerPlatformBase

setServerPlatform

public void setServerPlatform(ServerPlatform newServerPlatform)

PUBLIC: Set the server platform to handle server specific behaviour for WLS, Oc4j, etc This is not permitted after the session is logged in. If the user wants a different external transaction controller class or to provide some different behaviour than the provided ServerPlatform(s), we recommend subclassing oracle.toplink.essentials.platform.server.ServerPlatformBase (or a subclass), and overriding: ServerPlatformBase.getExternalTransactionControllerClass() ServerPlatformBase.registerMBean() ServerPlatformBase.unregisterMBean() for the desired behaviour.

Specified by:

setServerPlatform in interface DatabaseSession

See Also:

ServerPlatformBase

finalize

protected void finalize()
                 throws DatabaseException

INTERNAL: Logout in case still connected.

Overrides:

finalize in class java.lang.Object

Throws:

DatabaseException

getDescriptors

public java.util.Map getDescriptors()

PUBLIC: Return all registered descriptors.

Specified by:

getDescriptors in interface Session

Overrides:

getDescriptors in class AbstractSession

initializeDescriptorIfSessionAlive

public void initializeDescriptorIfSessionAlive(ClassDescriptor descriptor)

INTERNAL: A descriptor may have been added after the session is logged in. In this case the descriptor must be allowed to initialize any dependancies on this session. Normally the descriptors are added before login, then initialized on login.

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.

initializeDescriptors

public void initializeDescriptors(java.util.Map descriptors)

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. The descriptors session must be used, not the broker.

initializeDescriptors

public void initializeDescriptors(java.util.Vector descriptors)

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. The descriptors session must be used, not the broker.

isDatabaseSession

public boolean isDatabaseSession()

INTERNAL: Return if this session is a database session.

Specified by:

isDatabaseSession in interface Session

Overrides:

isDatabaseSession in class AbstractSession

getReadLogin

protected Login getReadLogin()

INTERNAL: Return the login for the read connection. Used by the platform autodetect feature

loginAndDetectDatasource

public void loginAndDetectDatasource()
                              throws DatabaseException

PUBLIC: Connect to the database using the predefined login. Durring connection attempt to auto detect the required database platform. This method can be used in systems where for ease of use developers have TopLink autodetect the platform. To be safe, however, the platform should be configured directly. The login must have been assigned when or after creating the session.

Throws:

DatabaseException

login

public void login()
           throws DatabaseException

PUBLIC: Connect to the database using the predefined login. The login must have been assigned when or after creating the session.

Specified by:

login in interface DatabaseSession

Throws:

DatabaseException

See Also:

login(Login)

login

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

PUBLIC: Connect to the database using the given user name and password. The additional login information must have been preset in the session's login attribute. This is the login that should be used if each user has their own id, but all users share the same database configuration.

Specified by:

login in interface DatabaseSession

Throws:

DatabaseException

login

public void login(Login login)
           throws DatabaseException

PUBLIC: Connect to the database using the given login. The login may also the preset and the login() protocol called. This is the login should only be used if each user has their own database configuration.

Specified by:

login in interface DatabaseSession

Throws:

DatabaseException

logout

public void logout()
            throws DatabaseException

PUBLIC: Disconnect from the database.

Specified by:

logout in interface 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.

initializeConnectedTime

public void initializeConnectedTime()

PUBLIC: Initialize the time that this session got connected. This can help determine how long a session has been connected.

getConnectedTime

public long getConnectedTime()

PUBLIC: Answer the time that this session got connected. This can help determine how long a session has been connected.

preConnectDatasource

protected void preConnectDatasource()

INTERNAL: This method includes all of the code that is issued before the datasource is connected to.

postConnectDatasource

protected void postConnectDatasource()

INTERNAL: This method includes all of the code that is issued after the datasource is connected to.

writeAllObjects

public void writeAllObjects(java.util.Collection domainObjects)
                     throws DatabaseException,
                            OptimisticLockException

PUBLIC: Write all of the objects and all of their privately owned parts in the database. The objects will be commited through a single transaction.

Specified by:

writeAllObjects in interface DatabaseSession

Throws:

DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database erros.

OptimisticLockException - if the object's descriptor is using optimistic locking and the object has been updated or deleted by another user since it was last read.

writeAllObjects

public void writeAllObjects(java.util.Vector domainObjects)
                     throws DatabaseException,
                            OptimisticLockException

PUBLIC: Write all of the objects and all of their privately owned parts in the database. The objects will be commited through a single transaction.

Specified by:

writeAllObjects in interface DatabaseSession

Throws:

DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database erros.

OptimisticLockException - if the object's descriptor is using optimistic locking and the object has been updated or deleted by another user since it was last read.