oracle.toplink.sessions
Interface Session

All Known Subinterfaces:

DatabaseSession, Server, UnitOfWork

All Known Implementing Classes:

oracle.toplink.publicinterface.DatabaseSession, oracle.toplink.publicinterface.Session

public interface Session

Purpose: Define the TopLink session public interface.

Description: This interface is meant to clarify the public protocol into TopLink. It also allows for non-subclasses of Session to conform to the TopLink API. It should be used as the applications main interface into the TopLink API to ensure compatibility between all TopLink sessions.

Responsibilities:

• Define the API for all reading, units of work.

See Also:

UnitOfWork, DatabaseSession, Session, DatabaseSession, ServerSession, ClientSession

Method Summary

oracle.toplink.publicinterface.UnitOfWork	acquireUnitOfWork() PUBLIC: Return a unit of work for this session.
void	addQuery(java.lang.String name, DatabaseQuery query) PUBLIC: Add the query to the session queries with the given name.
void	clearIntegrityChecker() PUBLIC: clear the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.
void	clearProfile() PUBLIC: Clear the profiler, this will end the current profile opperation.
boolean	containsObjectInIdentityMap(java.lang.Object domainObject) ADVANCED: Return if their is an object for the primary key.
boolean	containsObjectInIdentityMap(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Return if their is an object for the primary key.
boolean	containsQuery(java.lang.String queryName) PUBLIC: Return true if the pre-defined query is defined on the session.
java.lang.Object	copyObject(java.lang.Object original) PUBLIC: Return a complete copy of the object.
java.lang.Object	copyObject(java.lang.Object original, ObjectCopyingPolicy policy) PUBLIC: Return a complete copy of the object.
boolean	doesObjectExist(java.lang.Object object) PUBLIC: Return if the object exists on the database or not.
void	dontLogMessages() PUBLIC: Turing message logging off.
int	executeNonSelectingCall(Call call) PUBLIC: Execute the call on the database.
void	executeNonSelectingSQL(java.lang.String sqlString) Deprecated. replaced by executeNonSelectingCall(new SQLCall("... SQL ...")
java.lang.Object	executeQuery(DatabaseQuery query) PUBLIC: Execute the database query.
java.lang.Object	executeQuery(DatabaseQuery query, java.util.Vector argumentValues) PUBLIC: Return the results from exeucting the database query.
java.lang.Object	executeQuery(java.lang.String queryName) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Class domainClass) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Class domainClass, java.lang.Object arg1) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Class domainClass, java.lang.Object arg1, java.lang.Object arg2) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Class domainClass, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Class domainClass, java.util.Vector argumentValues) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Object arg1) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Object arg1, java.lang.Object arg2) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3) PUBLIC: Execute the pre-defined query by name and return the result.
java.lang.Object	executeQuery(java.lang.String queryName, java.util.Vector argumentValues) PUBLIC: Execute the pre-defined query by name and return the result.
java.util.Vector	executeSelectingCall(Call call) PUBLIC: Execute the call on the database and return the result.
java.util.Vector	executeSQL(java.lang.String sqlString) Deprecated. replaced by executeSelectingCall(new SQLCall("... SQL ...")
Session	getActiveSession() PUBLIC: Return the active session for the current active external (JTS) transaction.
UnitOfWork	getActiveUnitOfWork() PUBLIC: Return the active unit of work for the current active external (JTS) transaction.
java.util.Vector	getAllFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, DatabaseRow translationRow) Deprecated.
java.util.Vector	getAllFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, DatabaseRow translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) ADVANCED: Query the cache in-memory.
CacheSynchronizationManager	getCacheSynchronizationManager() ADVANCED: Returns the Synchronization Policy for this session.
CommandManager	getCommandManager() PUBLIC: Return the manager that allows this processor to receive or propagate commands from/to TopLink cluster
Descriptor	getDescriptor(java.lang.Class theClass) ADVANCED: Return the descriptor specified for the class.
Descriptor	getDescriptor(java.lang.Object domainObject) ADVANCED: Return the descriptor specified for the object's class.
java.util.Hashtable	getDescriptors() ADVANCED: Return all registered descriptors.
SessionEventManager	getEventManager() PUBLIC: Return the event manager.
ExceptionHandler	getExceptionHandler() PUBLIC: Return the ExceptionHandler.Exception handler can catch errors that occur on queries or during database access.
ExternalTransactionController	getExternalTransactionController() PUBLIC: Used for JTS integration.
java.lang.Object	getFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, DatabaseRow translationRow) Deprecated. Since 3.6.3
java.lang.Object	getFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, DatabaseRow translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) ADVANCED: Query the cache in-memory.
java.lang.Object	getFromIdentityMap(java.lang.Object domainObject) ADVANCED: Return the object from the identity with primary and class of the given object.
java.lang.Object	getFromIdentityMap(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Return the object from the identity with the primary and class.
IntegrityChecker	getIntegrityChecker() PUBLIC: Returns the integrityChecker,the integrityChecker holds all the Descriptor Exceptions.
java.io.Writer	getLog() PUBLIC: Return the writer to which an accessor writes logged messages and SQL.
DatabaseLogin	getLogin() PUBLIC: Return the login, the login holds any database connection information given.
java.lang.String	getName() PUBLIC: Return the name of the session.
java.lang.Number	getNextSequenceNumberValue(java.lang.Class domainClass) ADVANCED: Return the sequnce number from the database
SessionProfiler	getProfiler() PUBLIC: Return the profiler.
Project	getProject() PUBLIC: Return the project.
java.util.Hashtable	getProperties() ADVANCED: Allow for user defined properties.
java.lang.Object	getProperty(java.lang.String name) ADVANCED: Returns the user defined property.
java.util.Hashtable	getQueries() ADVANCED: Return all pre-defined queries.
DatabaseQuery	getQuery(java.lang.String name) PUBLIC: Return the query from the session pre-defined queries with the given name.
SessionLog	getSessionLog() PUBLIC: Return the session log to which an accessor logs messages and SQL.
java.lang.Object	getWriteLockValue(java.lang.Object domainObject) ADVANCED: Extract the write lock value from the identity map.
java.lang.Object	getWriteLockValue(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Extract the write lock value from the identity map.
java.lang.Object	handleException(java.lang.RuntimeException exception) PUBLIC: Allow any exceptions that occur within TopLink to be logged and handled by the exception handler.
boolean	hasCacheSynchronizationManager() ADVANCED: Return true if a synchronisation policy exists
boolean	hasDescriptor(java.lang.Class theClass) ADVANCED: Return true if a descriptor exists for the given class.
boolean	hasExceptionHandler() PUBLIC: Return if an exception handler is present.
boolean	hasExternalTransactionController() PUBLIC: Used for JTS integration.
void	initializeAllIdentityMaps() PUBLIC: Reset the entire object cache.
void	initializeIdentityMap(java.lang.Class theClass) PUBLIC: Reset the identity map for only the instances of the class.
void	initializeIdentityMaps() PUBLIC: Reset the entire object cache.
boolean	isClientSession() PUBLIC: Return if this session is a client session.
boolean	isConnected() PUBLIC: Return if this session is connected to the database.
boolean	isDatabaseSession() PUBLIC: Return if this session is a database session.
boolean	isDistributedSession() PUBLIC: Return if this session is a distributed session.
boolean	isInProfile() PUBLIC: Return if a profiler is being used.
boolean	isProxySession() PUBLIC: Return if this session is a proxy session.
boolean	isRemoteSession() PUBLIC: Return if this session is a remote session.
boolean	isServerSession() PUBLIC: Return if this session is a server session.
boolean	isSessionBroker() PUBLIC: Return if this session is a session broker.
boolean	isUnitOfWork() PUBLIC: Return if this session is a unit of work.
java.util.Vector	keyFromObject(java.lang.Object domainObject) ADVANCED: Extract and return the primary key from the object.
void	log(SessionLogEntry entry) PUBLIC: Log the log entry.
void	logDebug(java.lang.String message) PUBLIC: Log the debug message.
void	logDebug(java.lang.String message, java.lang.Object[] arguments) PUBLIC: Log the debug message.
void	logException(java.lang.Exception exception) PUBLIC: Log an exception.
void	logMessage(java.lang.String message) PUBLIC: Log a message to the logging stream.
void	logMessage(java.lang.String message, java.lang.Object[] arguments) PUBLIC: Log a message to the logging stream.
void	logMessages() PUBLIC: Turn message logging on.
void	printIdentityMap(java.lang.Class businessClass) PUBLIC: Used to print all the objects in the identity map of the passed in class.
void	printIdentityMaps() PUBLIC: Used to print all the objects in every identity map in this session.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject) ADVANCED: Register the object with the identity map.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject, java.util.Vector key) ADVANCED: Register the object with the identity map.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject, java.util.Vector key, java.lang.Object writeLockValue) ADVANCED: Register the object with the identity map.
java.util.Vector	readAllObjects(java.lang.Class domainClass) PUBLIC: Read all of the instances of the class from the database.
java.util.Vector	readAllObjects(java.lang.Class domainClass, Call aCall) PUBLIC: Read all the instances of the class from the database returned through execution the Call string.
java.util.Vector	readAllObjects(java.lang.Class domainClass, Expression selectionCriteria) PUBLIC: Read all of the instances of the class from the database matching the given expression.
java.util.Vector	readAllObjects(java.lang.Class domainClass, java.lang.String sqlString) Deprecated.
java.lang.Object	readObject(java.lang.Class domainClass) PUBLIC: Read the first instance of the Class from the database.
java.lang.Object	readObject(java.lang.Class domainClass, Call aCall) PUBLIC: Read the first instance of the class from the database returned through execution the Call string.
java.lang.Object	readObject(java.lang.Class domainClass, Expression selectionCriteria) PUBLIC: Read the first instance of the class from the database matching the given expression.
java.lang.Object	readObject(java.lang.Class domainClass, java.lang.String sqlString) Deprecated. use readObject(Class domainClass, Call aCall)
java.lang.Object	readObject(java.lang.Object object) PUBLIC: Use the example object to consruct a read object query by the objects primary key.
java.lang.Object	refreshObject(java.lang.Object object) PUBLIC: Refresh the attributes of the object and of all of its private parts from the database.
void	release() PUBLIC: Release the session.
void	removeFromIdentityMap(java.lang.Object domainObject) ADVANCED: Remove the object from the object cache.
void	removeFromIdentityMap(java.util.Vector key, java.lang.Class theClass) ADVANCED: Remove the object from the object cache.
void	removeProperty(java.lang.String property) PUBLIC: Remove the user defined property.
void	removeQuery(java.lang.String queryName) PUBLIC: Remove the query name from the set of pre-defined queries
void	setCacheSynchronizationManager(CacheSynchronizationManager synchronizationManager) ADVANCED: Sets synchronization policy for this session
void	setCommandManager(CommandManager mgr) ADVANCED: Set the manager that allows this processor to receive or propagate commands from/to TopLink cluster
void	setExceptionHandler(ExceptionHandler exceptionHandler) PUBLIC: Set the exceptionHandler.
void	setExternalTransactionController(ExternalTransactionController externalTransactionController) PUBLIC: Used for JTS integration.
void	setIntegrityChecker(IntegrityChecker integrityChecker) PUBLIC: Set the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.
void	setLog(java.io.Writer log) PUBLIC: Set the writer to which an accessor writes logged messages and SQL.
void	setName(java.lang.String name) PUBLIC: Set the name of the session.
void	setProfiler(SessionProfiler profiler) PUBLIC: Set the profiler for the session.
void	setProperty(java.lang.String propertyName, java.lang.Object propertyValue) PUBLIC: Allow for user defined properties.
void	setSessionLog(SessionLog sessionLog) PUBLIC: Set the session log to which an accessor logs messages and SQL.
void	setShouldLogMessages(boolean shouldLogMessages) PUBLIC: Set debug and SQL message logging.
boolean	shouldLogMessages() PUBLIC: Return if all messages such as executed SQL commands should be logged.
void	updateWriteLockValue(java.lang.Object domainObject, java.lang.Object writeLockValue) ADVANCED: Update the write lock value in the identity map.
void	updateWriteLockValue(java.util.Vector primaryKey, java.lang.Class theClass, java.lang.Object writeLockValue) ADVANCED: Update the write lock value in the identity map.
boolean	usesExternalTransactionController() PUBLIC: indicates if the JDBCLogin is configured to use an external transaction controller
void	validateCache() ADVANCED: This can be used to help debugging an object identity problem.

Method Detail

acquireUnitOfWork

public oracle.toplink.publicinterface.UnitOfWork acquireUnitOfWork()

PUBLIC: Return a unit of work for this session. The unit of work is an object level transaction that allows a group of changes to be applied as a unit. The return value should be used as the oracle.toplink.sessions.UnitOfWork interface, but must currently be returned as oracle.toplink.publicinterface.UnitOfWork to maintain backward compatibility.

See Also:

UnitOfWork

addQuery

public void addQuery(java.lang.String name,
                     DatabaseQuery query)

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

clearIntegrityChecker

public void clearIntegrityChecker()

PUBLIC: clear the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.

clearProfile

public void clearProfile()

PUBLIC: Clear the profiler, this will end the current profile opperation.

containsObjectInIdentityMap

public boolean containsObjectInIdentityMap(java.lang.Object domainObject)

ADVANCED: Return if their is an object for the primary key.

containsObjectInIdentityMap

public boolean containsObjectInIdentityMap(java.util.Vector primaryKey,
                                           java.lang.Class theClass)

ADVANCED: Return if their is an object for the primary key.

containsQuery

public boolean containsQuery(java.lang.String queryName)

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

copyObject

public java.lang.Object copyObject(java.lang.Object original)

PUBLIC: Return a complete copy of the object. This can be used to obtain a scatch copy of an object, or for templatizing an existing object into another new object. The object and all of its privately owned parts will be copied, the object's primary key will be reset to null.

See Also:

copyObject(Object, ObjectCopyingPolicy)

copyObject

public java.lang.Object copyObject(java.lang.Object original,
                                   ObjectCopyingPolicy policy)

PUBLIC: Return a complete copy of the object. This can be used to obtain a scatch copy of an object, or for templatizing an existing object into another new object. The object copying policy allow for the depth, and reseting of the primary key to null, to be specified.

doesObjectExist

public boolean doesObjectExist(java.lang.Object object)
                        throws DatabaseException

PUBLIC: Return if the object exists on the database or not. This always checks existence on the database.

Throws:

DatabaseException

dontLogMessages

public void dontLogMessages()

PUBLIC: Turing message logging off. Message logging will dump all SQL executed through TopLink to the session's log. By default this is System.out, but can be set to any Writer.

See Also:

logMessages(), setLog(Writer)

executeNonSelectingCall

public int executeNonSelectingCall(Call call)

PUBLIC: Execute the call on the database. The row count is returned. The call can be a stored procedure call, SQL call or other type of call.

Example:

session.executeNonSelectingCall(new SQLCall("Delete from Employee");

See Also:

executeSelectingCall(Call)

executeNonSelectingSQL

public void executeNonSelectingSQL(java.lang.String sqlString)

Deprecated. replaced by executeNonSelectingCall(new SQLCall("... SQL ...")

OBSOLETE:

See Also:

executeNonSelectingCall(Call)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse.

See Also:

addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Class domainClass)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse. The class is the descriptor in which the query was pre-defined.

See Also:

DescriptorQueryManager.addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Class domainClass,
                                     java.lang.Object arg1)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse. The class is the descriptor in which the query was pre-defined.

See Also:

DescriptorQueryManager.addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Class domainClass,
                                     java.lang.Object arg1,
                                     java.lang.Object arg2)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse. The class is the descriptor in which the query was pre-defined.

See Also:

DescriptorQueryManager.addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Class domainClass,
                                     java.lang.Object arg1,
                                     java.lang.Object arg2,
                                     java.lang.Object arg3)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse. The class is the descriptor in which the query was pre-defined.

See Also:

DescriptorQueryManager.addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Class domainClass,
                                     java.util.Vector argumentValues)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse. The class is the descriptor in which the query was pre-defined.

See Also:

DescriptorQueryManager.addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Object arg1)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse.

See Also:

addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Object arg1,
                                     java.lang.Object arg2)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse.

See Also:

addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.lang.Object arg1,
                                     java.lang.Object arg2,
                                     java.lang.Object arg3)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse.

See Also:

addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(java.lang.String queryName,
                                     java.util.Vector argumentValues)

PUBLIC: Execute the pre-defined query by name and return the result. Queries can be pre-defined and named to allow for their reuse.

See Also:

addQuery(String, DatabaseQuery)

executeQuery

public java.lang.Object executeQuery(DatabaseQuery query)
                              throws TopLinkException

PUBLIC: Execute the database query. A query is a database operation such as reading or writting. The query allows for the operation to be customized for such things as, performance, depth, caching, etc.

Throws:

TopLinkException

See Also:

DatabaseQuery

executeQuery

public java.lang.Object executeQuery(DatabaseQuery query,
                                     java.util.Vector argumentValues)

PUBLIC: Return the results from exeucting the database query. the arguments are passed in as a vector

executeSelectingCall

public java.util.Vector executeSelectingCall(Call call)

PUBLIC: Execute the call on the database and return the result. The call must return a value, if no value is return executeNonSelectCall must be used. The call can be a stored procedure call, SQL call or other type of call. A vector of database rows is returned, database row implements Java 2 Map which should be used to access the data.

Example:

session.executeSelectingCall(new SQLCall("Select * from Employee");

See Also:

executeNonSelectingCall(Call)

executeSQL

public java.util.Vector executeSQL(java.lang.String sqlString)

Deprecated. replaced by executeSelectingCall(new SQLCall("... SQL ...")

OBSOLETE:

See Also:

executeSelectingCall(Call)

getActiveSession

public Session getActiveSession()

PUBLIC: Return the active session for the current active external (JTS) transaction. This should only be used with JTS and will return the session if no external transaction exists.

getActiveUnitOfWork

public UnitOfWork getActiveUnitOfWork()

PUBLIC: Return the active unit of work for the current active external (JTS) transaction. This should only be used with JTS and will return null if no external transaction exists.

getAllFromIdentityMap

public java.util.Vector getAllFromIdentityMap(Expression selectionCriteria,
                                              java.lang.Class theClass,
                                              DatabaseRow translationRow,
                                              InMemoryQueryIndirectionPolicy valueHolderPolicy)
                                       throws QueryException

ADVANCED: Query the cache in-memory. If the expression is too complex an exception will be thrown.

Throws:

QueryException

getAllFromIdentityMap

public java.util.Vector getAllFromIdentityMap(Expression selectionCriteria,
                                              java.lang.Class theClass,
                                              DatabaseRow translationRow)
                                       throws QueryException

Deprecated.

ADVANCED: Query the cache in-memory. If the expression is too complex an exception will be thrown.

Throws:

QueryException

getCacheSynchronizationManager

public CacheSynchronizationManager getCacheSynchronizationManager()

ADVANCED: Returns the Synchronization Policy for this session.

getDescriptor

public Descriptor getDescriptor(java.lang.Class theClass)

ADVANCED: Return the descriptor specified for the class. If the class does not have a descriptor but implements an interface that is also implemented by one of the classes stored in the hashtable, that descriptor will be stored under the new class.

getDescriptor

public Descriptor getDescriptor(java.lang.Object domainObject)

ADVANCED: Return the descriptor specified for the object's class.

getDescriptors

public java.util.Hashtable getDescriptors()

ADVANCED: Return all registered descriptors.

getEventManager

public SessionEventManager getEventManager()

PUBLIC: Return the event manager. The event manager can be used to register for various session events.

getExceptionHandler

public ExceptionHandler getExceptionHandler()

PUBLIC: Return the ExceptionHandler.Exception handler can catch errors that occur on queries or during database access.

getExternalTransactionController

public ExternalTransactionController getExternalTransactionController()

PUBLIC: Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.

See Also:

JTSExternalTransactionController

getFromIdentityMap

public java.lang.Object getFromIdentityMap(java.lang.Object domainObject)

ADVANCED: Return the object from the identity with primary and class of the given object.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(java.util.Vector primaryKey,
                                           java.lang.Class theClass)

ADVANCED: Return the object from the identity with the primary and class.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Expression selectionCriteria,
                                           java.lang.Class theClass,
                                           DatabaseRow translationRow)
                                    throws QueryException

Deprecated. Since 3.6.3

ADVANCED: Query the cache in-memory. If the object is not found null is returned. If the expression is too complex an exception will be thrown.

Throws:

QueryException

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Expression selectionCriteria,
                                           java.lang.Class theClass,
                                           DatabaseRow translationRow,
                                           InMemoryQueryIndirectionPolicy valueHolderPolicy)
                                    throws QueryException

ADVANCED: Query the cache in-memory. If the object is not found null is returned. If the expression is too complex an exception will be thrown.

Throws:

QueryException

getIntegrityChecker

public IntegrityChecker getIntegrityChecker()

PUBLIC: Returns the integrityChecker,the integrityChecker holds all the Descriptor Exceptions.

getLog

public java.io.Writer getLog()

PUBLIC: Return the writer to which an accessor writes logged messages and SQL. If not set, this reference defaults to a writer on System.out. To enable logging logMessages must be turned on.

See Also:

logMessages()

getLogin

public DatabaseLogin getLogin()

PUBLIC: Return the login, the login holds any database connection information given.

getName

public java.lang.String getName()

PUBLIC: Return the name of the session. This is used with the session broker, or to give the session a more meaningful name.

getNextSequenceNumberValue

public java.lang.Number getNextSequenceNumberValue(java.lang.Class domainClass)

ADVANCED: Return the sequnce number from the database

getProfiler

public SessionProfiler getProfiler()

PUBLIC: Return the profiler. The profiler is a tool that can be used to determine performance bottlenecks. The profiler can be queries to print summaries and configure for logging purposes.

getProject

public Project getProject()

PUBLIC: Return the project. The project includes the login and descriptor and other configuration information.

getProperties

public java.util.Hashtable getProperties()

ADVANCED: Allow for user defined properties.

getProperty

public java.lang.Object getProperty(java.lang.String name)

ADVANCED: Returns the user defined property.

getQueries

public java.util.Hashtable getQueries()

ADVANCED: Return all pre-defined queries.

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.

getSessionLog

public SessionLog getSessionLog()

PUBLIC: Return the session log to which an accessor logs messages and SQL. If not set, this will default to a session log on a writer on System.out. To enable logging, logMessages must be turned on.

See Also:

logMessages()

getWriteLockValue

public java.lang.Object getWriteLockValue(java.lang.Object domainObject)

ADVANCED: Extract the write lock value from the identity map.

getWriteLockValue

public java.lang.Object getWriteLockValue(java.util.Vector primaryKey,
                                          java.lang.Class theClass)

ADVANCED: Extract the write lock value from the identity map.

handleException

public java.lang.Object handleException(java.lang.RuntimeException exception)
                                 throws java.lang.RuntimeException

PUBLIC: Allow any exceptions that occur within TopLink to be logged and handled by the exception handler.

Throws:

java.lang.RuntimeException

hasCacheSynchronizationManager

public boolean hasCacheSynchronizationManager()

ADVANCED: Return true if a synchronisation policy exists

hasDescriptor

public boolean hasDescriptor(java.lang.Class theClass)

ADVANCED: Return true if a descriptor exists for the given class.

hasExceptionHandler

public boolean hasExceptionHandler()

PUBLIC: Return if an exception handler is present.

hasExternalTransactionController

public boolean hasExternalTransactionController()

PUBLIC: Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.

See Also:

JTSExternalTransactionController

initializeAllIdentityMaps

public void initializeAllIdentityMaps()

PUBLIC: Reset the entire object cache.

NOTE: be careful using this method. This method blows away both this session's and its parents caches, this includes 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.

initializeIdentityMap

public void initializeIdentityMap(java.lang.Class theClass)

PUBLIC: Reset the identity map for only the instances of the class. For inheritence the user must make sure that they only use the root class. Caution must be used in doing this to ensure that the objects within the identity map are not referenced from other objects of other classes or from the application.

initializeIdentityMaps

public void initializeIdentityMaps()

PUBLIC: Reset the entire object 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.

isClientSession

public boolean isClientSession()

PUBLIC: Return if this session is a client session.

isConnected

public boolean isConnected()

PUBLIC: Return if this session is connected to the database.

isDatabaseSession

public boolean isDatabaseSession()

PUBLIC: Return if this session is a database session.

isDistributedSession

public boolean isDistributedSession()

PUBLIC: Return if this session is a distributed session.

isInProfile

public boolean isInProfile()

PUBLIC: Return if a profiler is being used.

isProxySession

public boolean isProxySession()

PUBLIC: Return if this session is a proxy session.

isRemoteSession

public boolean isRemoteSession()

PUBLIC: Return if this session is a remote session.

isServerSession

public boolean isServerSession()

PUBLIC: Return if this session is a server session.

isSessionBroker

public boolean isSessionBroker()

PUBLIC: Return if this session is a session broker.

isUnitOfWork

public boolean isUnitOfWork()

PUBLIC: Return if this session is a unit of work.

keyFromObject

public java.util.Vector keyFromObject(java.lang.Object domainObject)
                               throws ValidationException

ADVANCED: Extract and return the primary key from the object.

Throws:

ValidationException

log

public void log(SessionLogEntry entry)

PUBLIC: Log the log entry.

logDebug

public void logDebug(java.lang.String message,
                     java.lang.Object[] arguments)

PUBLIC: Log the debug message. The parameter 'message' is a string that needs to be translated.

logDebug

public void logDebug(java.lang.String message)

PUBLIC: Log the debug message. The parameter 'message' is a translated string or a string that does not need to be translated.

logException

public void logException(java.lang.Exception exception)

PUBLIC: Log an exception.

logMessage

public void logMessage(java.lang.String message,
                       java.lang.Object[] arguments)

PUBLIC: Log a message to the logging stream. The parameter 'message' is a string that needs to be translated.

logMessage

public void logMessage(java.lang.String message)

PUBLIC: Log a message to the logging stream. The parameter 'message' is a translated string or a string that does not need to be translated.

logMessages

public void logMessages()

PUBLIC: Turn message logging on. Message logging will dump all SQL executed through TopLink to the session's log. By default this is System.out, but can be set to any Writer.

See Also:

dontLogMessages(), setLog(Writer)

printIdentityMap

public void printIdentityMap(java.lang.Class businessClass)

PUBLIC: Used to print all the objects in the identity map of the passed in class. The output of this method will go the the Session's log.

printIdentityMaps

public void printIdentityMaps()

PUBLIC: Used to print all the objects in every identity map in this session. The output of this method will go to the Session's log.

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject)

ADVANCED: Register the object with the identity map. The object must always be registered with its version number if optimistic locking is used.

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject,
                                         java.util.Vector key)

ADVANCED: Register the object with the identity map. The object must always be registered with its version number if optimistic locking is used.

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject,
                                         java.util.Vector key,
                                         java.lang.Object writeLockValue)

ADVANCED: Register the object with the identity map. The object must always be registered with its version number if optimistic locking is used.

readAllObjects

public java.util.Vector readAllObjects(java.lang.Class domainClass)
                                throws DatabaseException

PUBLIC: Read all of the instances of the class from the database. This operation can be customized through using a ReadAllQuery, or through also passing in a selection criteria.

Throws:

DatabaseException

See Also:

ReadAllQuery, readAllObjects(Class, Expression)

readAllObjects

public java.util.Vector readAllObjects(java.lang.Class domainClass,
                                       java.lang.String sqlString)
                                throws DatabaseException

Deprecated.

OBSOLETE: Read all of the instances of the class from the database returned through execution the SQL string. The SQL string must be a valid SQL select statement or selecting stored procedure call. This operation can be customized through using a ReadAllQuery.

Throws:

DatabaseException

readAllObjects

public java.util.Vector readAllObjects(java.lang.Class domainClass,
                                       Call aCall)
                                throws DatabaseException

PUBLIC: Read all the instances of the class from the database returned through execution the Call string. The Call can be an SQLCall or EJBQLCall. example: session.readAllObjects(Employee.class, new SQLCall("SELECT * FROM EMPLOYEE"));

Throws:

DatabaseException

See Also:

SQLCall, EJBQLCall

readAllObjects

public java.util.Vector readAllObjects(java.lang.Class domainClass,
                                       Expression selectionCriteria)
                                throws DatabaseException

PUBLIC: Read all of the instances of the class from the database matching the given expression. This operation can be customized through using a ReadAllQuery.

Throws:

DatabaseException

See Also:

ReadAllQuery

readObject

public java.lang.Object readObject(java.lang.Class domainClass)
                            throws DatabaseException

PUBLIC: Read the first instance of the Class from the database. This operation can be customized through using a ReadObjectQuery, or through also passing in a selection criteria. By default, this method executes a query without selection criteria and consequently it will always result in a database access even if an instance of the specified Class exists in the cache. Executing a query with selection criteria allows you to avoid a database access if the selected instance is in the cache. Because of this, you may whish to consider a readObject method that takes selection criteria, such as: readObject(Class, Call), readObject(Class, Expression), or readObject(Object).

Throws:

DatabaseException

See Also:

ReadObjectQuery, readAllObjects(Class, Expression)

readObject

public java.lang.Object readObject(java.lang.Class domainClass,
                                   java.lang.String sqlString)
                            throws DatabaseException

Deprecated. use readObject(Class domainClass, Call aCall)

OBSOLETE: Read the first instance of the class from the database returned through execution the SQL string. The SQL string must be a valid SQL select statement or selecting stored procedure call. This operation can be customized through using a ReadObjectQuery.

Throws:

DatabaseException

See Also:

ReadObjectQuery

readObject

public java.lang.Object readObject(java.lang.Class domainClass,
                                   Call aCall)
                            throws DatabaseException

PUBLIC: Read the first instance of the class from the database returned through execution the Call string. The Call can be an SQLCall or EJBQLCall. example: session.readObject(Employee.class, new SQLCall("SELECT * FROM EMPLOYEE"));

Throws:

DatabaseException

See Also:

SQLCall, EJBQLCall

readObject

public java.lang.Object readObject(java.lang.Class domainClass,
                                   Expression selectionCriteria)
                            throws DatabaseException

PUBLIC: Read the first instance of the class from the database matching the given expression. This operation can be customized through using a ReadObjectQuery.

Throws:

DatabaseException

See Also:

ReadObjectQuery

readObject

public java.lang.Object readObject(java.lang.Object object)
                            throws DatabaseException

PUBLIC: Use the example object to consruct a read object query by the objects primary key. This will read the object from the database with the same primary key as the object or null if no object is found.

Throws:

DatabaseException

refreshObject

public java.lang.Object refreshObject(java.lang.Object object)

PUBLIC: Refresh the attributes of the object and of all of its private parts from the database. This can be used to ensure the object is up to date with the database. Caution should be used when using this to make sure the application has no un commited changes to the object.

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.

removeFromIdentityMap

public void removeFromIdentityMap(java.lang.Object domainObject)

ADVANCED: Remove the object from the object cache. Caution should be used when calling to avoid violating object identity. The application should only call this is it knows that no references to the object exist.

removeFromIdentityMap

public void removeFromIdentityMap(java.util.Vector key,
                                  java.lang.Class theClass)

ADVANCED: Remove the object from the object cache.

removeProperty

public void removeProperty(java.lang.String property)

PUBLIC: Remove the user defined property.

removeQuery

public void removeQuery(java.lang.String queryName)

PUBLIC: Remove the query name from the set of pre-defined queries

setCacheSynchronizationManager

public void setCacheSynchronizationManager(CacheSynchronizationManager synchronizationManager)

ADVANCED: Sets synchronization policy for this session

setExceptionHandler

public void setExceptionHandler(ExceptionHandler exceptionHandler)

PUBLIC: Set the exceptionHandler. Exception handler can catch errors that occur on queries or during database access.

setExternalTransactionController

public void setExternalTransactionController(ExternalTransactionController externalTransactionController)

PUBLIC: Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.

See Also:

JTSExternalTransactionController

setIntegrityChecker

public void setIntegrityChecker(IntegrityChecker integrityChecker)

PUBLIC: Set the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.

setLog

public void setLog(java.io.Writer log)

PUBLIC: Set the writer to which an accessor writes logged messages and SQL. If not set, this reference defaults to a writer on System.out. To enable logging logMessages() is used.

See Also:

logMessages()

setName

public void setName(java.lang.String name)

PUBLIC: Set the name of the session. This is used with the session broker, or to give the session a more meaningful name.

setProfiler

public void setProfiler(SessionProfiler profiler)

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

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.Object propertyValue)

PUBLIC: Allow for user defined properties.

setSessionLog

public void setSessionLog(SessionLog sessionLog)

PUBLIC: Set the session log to which an accessor logs messages and SQL. If not set, this will default to a session log on a writer on System.out. To enable logging, logMessages must be turned on.

See Also:

logMessages()

setShouldLogMessages

public void setShouldLogMessages(boolean shouldLogMessages)

PUBLIC: Set debug and SQL message logging.

shouldLogMessages

public boolean shouldLogMessages()

PUBLIC: Return if all messages such as executed SQL commands should be logged.

updateWriteLockValue

public void updateWriteLockValue(java.lang.Object domainObject,
                                 java.lang.Object writeLockValue)

ADVANCED: Update the write lock value in the identity map.

updateWriteLockValue

public void updateWriteLockValue(java.util.Vector primaryKey,
                                 java.lang.Class theClass,
                                 java.lang.Object writeLockValue)

ADVANCED: Update the write lock value in the identity map.

usesExternalTransactionController

public boolean usesExternalTransactionController()

PUBLIC: indicates if the JDBCLogin is configured to use an external transaction controller

validateCache

public void validateCache()

ADVANCED: This can be used to help debugging an object identity problem. An object identity problem is when an object in the cache references an object not in the cache. This method will validate that all cached objects are in a correct state.

getCommandManager

public CommandManager getCommandManager()

PUBLIC: Return the manager that allows this processor to receive or propagate commands from/to TopLink cluster

setCommandManager

public void setCommandManager(CommandManager mgr)

ADVANCED: Set the manager that allows this processor to receive or propagate commands from/to TopLink cluster