FileDocCategorySizeDatePackage
Session.javaAPI DocGlassfish v2 API27708Tue May 22 16:54:52 BST 2007oracle.toplink.essentials.sessions

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
UnitOfWork
see
DatabaseSession
see
oracle.toplink.essentials.publicinterface.Session
see
oracle.toplink.essentials.publicinterface.DatabaseSession
see
oracle.toplink.essentials.threetier.ServerSession
see
oracle.toplink.essentials.threetier.ClientSession

Fields Summary
Constructors Summary
Methods Summary
public UnitOfWorkacquireUnitOfWork()
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.essentials.sessions.UnitOfWork interface, but must currently be returned as oracle.toplink.essentials.publicinterface.UnitOfWork to maintain backward compatibility.

see
UnitOfWork

public voidaddEjbqlPlaceHolderQuery(DatabaseQuery query)
ADVANCED: Add a pre-defined not yet parsed EJBQL String/query to the session to be parsed after descriptors are initialized.

see
#getAllQueries()

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

public voidclearIntegrityChecker()
PUBLIC: clear the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.

public voidclearProfile()
PUBLIC: Clear the profiler, this will end the current profile opperation.

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

public java.lang.ObjectcopyObject(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
#copyObject(Object, ObjectCopyingPolicy)

public java.lang.ObjectcopyObject(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.

public booleandoesObjectExist(java.lang.Object object)
PUBLIC: Return if the object exists on the database or not. This always checks existence on the database.

public voiddontLogMessages()
PUBLIC: Turn off logging

public intexecuteNonSelectingCall(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
#executeSelectingCall(Call)

public voidexecuteNonSelectingSQL(java.lang.String sqlString)
PUBLIC: Execute the non-selecting (update/DML) SQL string.

public java.lang.ObjectexecuteQuery(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
#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(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
#addQuery(String, DatabaseQuery)

public java.lang.ObjectexecuteQuery(DatabaseQuery query)
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.

see
DatabaseQuery

public java.lang.ObjectexecuteQuery(DatabaseQuery query, java.util.Vector argumentValues)
PUBLIC: Return the results from exeucting the database query. the arguments are passed in as a vector

public java.util.VectorexecuteSQL(java.lang.String sqlString)
PUBLIC: Execute the selecting SQL string. A Vector of DatabaseRecords are returned.

public java.util.VectorexecuteSelectingCall(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
#executeNonSelectingCall(Call)

public oracle.toplink.essentials.sessions.SessiongetActiveSession()
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.

public UnitOfWorkgetActiveUnitOfWork()
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.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetClassDescriptor(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.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetClassDescriptor(java.lang.Object domainObject)
ADVANCED: Return the descriptor specified for the object's class.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetClassDescriptorForAlias(java.lang.String alias)
PUBLIC: Return the descriptor for the alias.

public LogingetDatasourceLogin()
PUBLIC: Return the login, the login holds any database connection information given. This return the Login interface and may need to be cast to the datasource specific implementation.

public oracle.toplink.essentials.internal.databaseaccess.PlatformgetDatasourcePlatform()
PUBLIC: Return the database platform currently connected to. The platform is used for database specific behavoir.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetDescriptor(java.lang.Class theClass)
ADVANCED: Return the descriptor specified for the object's class.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetDescriptor(java.lang.Object domainObject)
ADVANCED: Return the descriptor specified for the object's class.

public oracle.toplink.essentials.descriptors.ClassDescriptorgetDescriptorForAlias(java.lang.String alias)
PUBLIC: Return the descriptor for the alias.

public java.util.MapgetDescriptors()
ADVANCED: Return all registered descriptors.

public java.util.ListgetEjbqlPlaceHolderQueries()
ADVANCED: Return all pre-defined not yet parsed EJBQL queries.

see
#getAllQueries()

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

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

public ExternalTransactionControllergetExternalTransactionController()
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
oracle.toplink.essentials.transaction.JTATransactionController

public IdentityMapAccessorgetIdentityMapAccessor()
PUBLIC: The IdentityMapAccessor is the preferred way of accessing IdentityMap funcitons This will return an object which implements an interface which exposes all public IdentityMap functions.

public IntegrityCheckergetIntegrityChecker()
PUBLIC: Returns the integrityChecker,the integrityChecker holds all the Descriptor Exceptions.

public java.io.WritergetLog()
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.

public intgetLogLevel(java.lang.String category)
PUBLIC: Return the log level

public intgetLogLevel()
PUBLIC: Return the log level

public DatabaseLogingetLogin()
PUBLIC: Return the login, the login holds any database connection information given. This has been replaced by getDatasourceLogin to make use of the Login interface to support non-relational datasources, if DatabaseLogin API is required it will need to be cast.

public java.lang.StringgetName()
PUBLIC: Return the name of the session. This is used with the session broker, or to give the session a more meaningful name.

public java.lang.NumbergetNextSequenceNumberValue(java.lang.Class domainClass)
ADVANCED: Return the sequnce number from the database

public oracle.toplink.essentials.internal.databaseaccess.DatabasePlatformgetPlatform()
PUBLIC: Return the database platform currently connected to. The platform is used for database specific behavoir. NOTE: this must only be used for relational specific usage, it will fail for non-relational datasources.

public SessionProfilergetProfiler()
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.

public oracle.toplink.essentials.sessions.ProjectgetProject()
PUBLIC: Return the project. The project includes the login and descriptor and other configuration information.

public java.util.MapgetProperties()
ADVANCED: Allow for user defined properties.

public java.lang.ObjectgetProperty(java.lang.String name)
ADVANCED: Returns the user defined property.

public java.util.MapgetQueries()
ADVANCED: Return all pre-defined queries.

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

public DatabaseQuerygetQuery(java.lang.String name, java.util.Vector arguments)
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.

public oracle.toplink.essentials.logging.SessionLoggetSessionLog()
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.

public java.lang.ObjecthandleException(java.lang.RuntimeException exception)
PUBLIC: Allow any WARNING level exceptions that occur within TopLink to be logged and handled by the exception handler.

public java.lang.ObjecthandleSevere(java.lang.RuntimeException exception)
PUBLIC: Allow any SEVERE level exceptions that occur within TopLink to be logged and handled by the exception handler.

public booleanhasDescriptor(java.lang.Class theClass)
ADVANCED: Return true if a descriptor exists for the given class.

public booleanhasExceptionHandler()
PUBLIC: Return if an exception handler is present.

public booleanhasExternalTransactionController()
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
oracle.toplink.essentials.transaction.JTATransactionController

public booleanisClientSession()
PUBLIC: Return if this session is a client session.

public booleanisConnected()
PUBLIC: Return if this session is connected to the database.

public booleanisDatabaseSession()
PUBLIC: Return if this session is a database session.

public booleanisDistributedSession()
PUBLIC: Return if this session is a distributed session.

public booleanisInProfile()
PUBLIC: Return if a profiler is being used.

public booleanisRemoteSession()
PUBLIC: Return if this session is a remote session.

public booleanisRemoteUnitOfWork()
PUBLIC: Return if this session is a remote unit of work.

public booleanisServerSession()
PUBLIC: Return if this session is a server session.

public booleanisSessionBroker()
PUBLIC: Return if this session is a session broker.

public booleanisUnitOfWork()
PUBLIC: Return if this session is a unit of work.

public java.util.VectorkeyFromObject(java.lang.Object domainObject)
ADVANCED: Extract and return the primary key from the object.

public voidlog(oracle.toplink.essentials.logging.SessionLogEntry entry)
PUBLIC: Log the log entry.

public voidlog(int level, java.lang.String category, java.lang.String message)
PUBLIC:

Log a message with level and category.

param
level, the log request level value

param
message, the string message

param
category, the string representation of a TopLink category.

public voidlogMessage(java.lang.String message)
Log a untranslated message to the TopLink log at FINER level.

public voidlogThrowable(int level, java.lang.String category, java.lang.Throwable throwable)
PUBLIC:

Log a throwable with level and category.

param
level, the log request level value

param
category, the string representation of a TopLink category.

param
throwable, a Throwable

public java.util.VectorreadAllObjects(java.lang.Class domainClass)
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.

see
ReadAllQuery
see
#readAllObjects(Class, Expression)

public java.util.VectorreadAllObjects(java.lang.Class domainClass, Call aCall)
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"));

see
SQLCall
see
EJBQLCall

public java.util.VectorreadAllObjects(java.lang.Class domainClass, Expression selectionCriteria)
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.

see
ReadAllQuery

public java.lang.ObjectreadObject(java.lang.Class domainClass)
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: {@link #readObject(Class, Call)}, {@link #readObject(Class, Expression)}, or {@link #readObject(Object)}.

see
ReadObjectQuery
see
#readAllObjects(Class, Expression)

public java.lang.ObjectreadObject(java.lang.Class domainClass, Call aCall)
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"));

see
SQLCall
see
EJBQLCall

public java.lang.ObjectreadObject(java.lang.Class domainClass, Expression selectionCriteria)
PUBLIC: Read the first instance of the class from the database matching the given expression. This operation can be customized through using a ReadObjectQuery.

see
ReadObjectQuery

public java.lang.ObjectreadObject(java.lang.Object object)
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.

public java.lang.ObjectrefreshObject(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.

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

public voidremoveProperty(java.lang.String property)
PUBLIC: Remove the user defined property.

public voidremoveQuery(java.lang.String queryName)
PUBLIC: Remove the query name from the set of pre-defined queries

public voidsetExceptionHandler(ExceptionHandler exceptionHandler)
PUBLIC: Set the exceptionHandler. Exception handler can catch errors that occur on queries or during database access.

public voidsetExternalTransactionController(ExternalTransactionController externalTransactionController)
Set the transaction controller, allow integration with JTA.

public voidsetIntegrityChecker(IntegrityChecker integrityChecker)
PUBLIC: Set the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.

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

public voidsetLogLevel(int level)
PUBLIC: Set the log level

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

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

public voidsetProperty(java.lang.String propertyName, java.lang.Object propertyValue)
PUBLIC: Allow for user defined properties.

public voidsetSessionLog(oracle.toplink.essentials.logging.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.

public booleanshouldLog(int Level, java.lang.String category)
PUBLIC: Check if a message of the given level would actually be logged.

public booleanshouldLogMessages()
PUBLIC: Return if logging is enabled (false if log level is OFF)