|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
This section describes concepts unique to TopLink sessions, including the following:
As Figure 75-1 illustrates, a session instance is composed of the following components:
Figure 75-1 Simple TopLink Session Architecture
How these session components are implemented and how they interact depends on the type of session. For example, for server and client sessions, the server session provides a connection pool and shared object cache on behalf of all client sessions acquired from it.
TopLink sessions provide an object cache. This cache, known as the session cache, retains information about objects that are read from or written to the database, and is a key element for improving the performance of a TopLink application.
Typically, a server session's object cache is shared by all client sessions acquired from it. That is, for a Server session myServerSession, each client session acquired by calling server session method acquireClientSession shares the same object cache as myServerSession.
Isolated and historical sessions provide their own session cache isolated from the shared object cache of their parent server session. For more information, see "Isolated Client Sessions" and "Historical Client Sessions".
You can easily manage concurrent access to this shared cache by using a unit of work session acquired from any session. For more information, see "Unit of Work Sessions".
For more information, see "Sessions and the Cache".
A connection pool is a collection of reusable connections to a single data source.
|
Note: To simultaneously access multiple databases from within a single session, use a session broker. For more information, see "Session Broker and Client Sessions". |
Because creating a data source connection is usually expensive, a properly configured connection pool significantly improves performance.
You can configure your session to use internal connection pools provided by TopLink or external connection pools provided by a JDBC driver or J2EE container. By default, TopLink uses internal connection pools.
Internal connection pools are usually used in non-EJB applications, or when an external transaction controller (JTA) is not used. If you configure your session to use internal connection pools, you can configure its default read and write connection pools. You can create special purpose connection pools for application-specific purposes (named connection pools) or exclusively for sequencing (sequence connection pool). For more information, see "Internal Connection Pools".
External connection pools are usually used in EJB applications and when an external transaction controller (JTA) is used. For more information, see "External Connection Pools".
For more information about data access configuration in general, see "Understanding Data Access".
At run time, your application uses a session to perform all persistence operations: creating, reading, updating, and deleting objects. You perform these operations using TopLink queries and expressions with the session query API.
For more information, see "Understanding TopLink Queries".
TopLink provides two ways to configure your sessions: through Java code using the Session API, or using TopLink Workbench to build a session configuration file, the sessions.xml file.
In most cases, you configure sessions for the application using the sessions.xml file. This file is an eXtensible Markup Language (XML) file that contains all sessions that are associated with the application. The sessions.xml file can contain any number of sessions and session types.
Oracle recommends that you use the sessions.xml file to deploy a TopLink application, because:
It is easy to create and maintain in TopLink Workbench.
It is easy to troubleshoot.
It provides access to most session configuration options.
It offers excellent flexibility, including the ability to modify deployed applications without recompiling.
For more information on creating a session in the sessions.xml file, see "Session Creation Overview".
You can customize a session at run time by specifying a session customizer–a Java class that implements the oracle.toplink.tools.sessionconfiguration.SessionCustomizer interface and provides a default (zero-argument) constructor. Use this customization method when creating a CMP project to specify your database login information, since the sessions.xml file is not used.
You use a session customizer to customize a session at run time through code API similar to how you use an amendment method to customize a descriptor (see "Amendment and After-Load Methods").
For more information, see "Configuring Customizer Class".
The TopLink session manager enables developers to build a series of sessions that are maintained under a singleton object called the session manager.
The session manager is a static utility class that loads TopLink sessions from the sessions.xml file (see "Session Configuration and the sessions.xml File"), caches the sessions by name in memory, and provides a single access point for TopLink sessions.
At runtime, TopLink will attempt to load the sessiosn.xml file from the two following default resource names: sessions.xml and META-INF/sessions.xml. Refer to Chapter 9, "Packaging a TopLink Application" for additional information.
The session manager supports the following session types:
ServerSession (see "Server and Client Sessions")
SessionBroker (see "Session Broker and Client Sessions")
DatabaseSession (see "Database Sessions")
The session manager has two main functions: it creates instances of these sessions and it ensures that only a single instance of each named session exists for any instance of a session manager.
The session manager instantiates sessions as follows:
The client application requests a session by name.
The session manager looks up the session name in the sessions.xml file. If the session name exists, the session manager instantiates the specified session; otherwise, it raises an exception.
After instantiation, the session remains viable until you shut down the application.
Once you have a session instance, you can use it to acquire additional types of sessions for special tasks. For example, you can acquire a unit of work from any session to perform transactional operations. You can acquire a client session from a server session to perform client operations in a three-tier architecture.
For more information, see "Acquiring and Using Sessions at Run Time".
Sessions raise session events for most session operations. Session events help you debug or coordinate the actions of multiple sessions.
The session event manager handles information about session events. Applications register session event listeners with the session event manager to receive session events.
For example, session event listeners play an important role in the configuration of isolated sessions (see "Configuring Isolated Client Sessions"). In an isolated session, if the TopLink runtime raises a SessionEvent.NoRowsModified event, it is handled by your SessionEventListener (see "NoRowsModifiedSessionEvent Event Handler"). This event listener is your opportunity to determine whether the update failure was due to a security violation (in which case you should not retry the operation) or due to an optimistic lock issue (in which case a retry may be appropriate).
Another example is the use of session event listeners to configure proxy authentication in an Oracle Database. (see "Configuring Oracle Database Proxy Authentication").
This section explains how to use session events, including the following:
The session event manager supports the session events listed in the following tables:
Table 75-2 Session Events
| Event | Description |
|---|---|
|
MissingDescriptor |
Raised if a descriptor is missing for a class being persisted. You can use this event to lazy register the descriptor or set of descriptors. |
|
MoreRowsDetected |
Raised when a |
|
NoRowsModified |
Raised after update or delete SQL has been sent to the database and a row count of zero is returned. |
|
OutputParametersDetected |
Raised after a stored procedure call with output parameters executes. This event enables you to retrieve a result set and output parameters from a single stored procedure. |
|
PostAcquireClientSession |
Raised after a client Session is acquired |
|
PostAcquireConnection |
Raised after acquiring a connection |
|
PostAcquireExclusiveConnection |
Raised when a client Session, with isolated data, acquires an exclusive connection. |
|
PostBeginTransaction |
Raised after a database transaction starts |
|
PostCommitTransaction |
Raised after a database transaction commits |
|
PostConnect |
Raised after connecting to the database |
|
PostExecuteQuery |
Raised after the execution of every query on the session |
|
PostLogin |
Raised after the Session initializes and acquires connections |
|
PostReleaseClientSession |
Raised after releasing a client Session |
|
PostRollbackTransaction |
Raised after a database transaction rolls back |
|
PreBeginTransaction |
Raised before a database transaction starts |
|
PreCommitTransaction |
Raised before a database transaction commits |
|
PreExecuteQuery |
Raised before the execution of every query on the session |
|
PreLogin |
Raised before the Session initializes and acquires connections |
|
PreReleaseClientSession |
Raised before releasing a client Session |
|
PreReleaseConnection |
Raised before releasing a connection |
|
PreReleaseExclusiveConnection |
Raised before a client Session, with isolated data, releases its exclusive connection. |
|
PreRollbackTransaction |
Raised before a database transaction rolls back |
Table 75-3 Unit of Work Events
| Event | Description |
|---|---|
|
PostAcquireUnitOfWork |
Raised after a |
|
PostCalculateUnitOfWorkChangeSet |
Raised after the commit has begun on the |
|
PostCommitUnitOfWork |
Raised after a |
|
PostDistributedMergeUnitOfWorkChangeSet |
Raised after a |
|
PostMergeUnitOfWorkChangeSet |
Raised after a |
|
PostReleaseUnitOfWork |
Raised on a |
|
PostResumeUnitOfWork |
Raised on a |
|
PreCalculateUnitOfWorkChangeSet |
Raised after the commit has begun on the |
|
PreCommitUnitOfWork |
Raised before a |
|
PreDistributedMergeUnitOfWorkChangeSet |
Raised before a |
|
PreMergeUnitOfWorkChangeSet |
Raised before a |
|
PrepareUnitOfWork |
Raised after the a |
|
PreReleaseUnitOfWork |
Raised on a |
Session event listeners can be created two ways: either by implementing the SessionEventListener interface, or by extending the SessionEventAdapter class.
To register a SessionEventListener for session events, register it with a session using the SessionEventManager method addListener.
For more information, see "Configuring Session Event Listeners".
You can configure a session to write run-time information to a TopLink log. This information includes status, diagnostic, SQL, and, when profiling is enabled, performance data (see "Measuring Performance With the TopLink Profiler" or "Measuring Performance With the Oracle Dynamic Monitoring System (DMS)").
Logging options are configurable at the session level (see "Configuring Logging").
This section describes session log options including the following:
TopLink supports the following types of logging:
For a non-CMP application, you can configure the log type using TopLink Workbench (see "Using TopLink Workbench"). For a CMP application, see "Configuring Logging in a CMP Application".
TopLink native logging is the default session log type. It is provided by oracle.toplink.logging.DefaultSessionLog. Example 75-1 shows a typical TopLink native log message.
You can configure TopLink native logging options using TopLink Workbench (see "Using TopLink Workbench").
Example 75-1 Sample TopLink Log Message
[TopLink Info]: DATE TIME-DatabaseSession(12345)-Thread(12345)-TopLink, version: Oracle TopLink - 10g (Build 031203) [TopLink Config]: DATE TIME-DatabaseSession(12345)-Thread(12345)-Connection(12345)- connecting(DatabaseLogin( platform=>Oracle9Platform user name=> "username" datasource URL=> "jdbc:oracle:thin:@144.23.214.115:1521:toplink" )) [TopLink Config]: DATE TIME-DatabaseSession(12345)-Thread(12345)-Connection(12345)- Connected: jdbc:oracle:thin:@144.23.214.115:1521:toplink User: USERNAME Database: Oracle Version: Oracle9i Enterprise Edition - Production With the Partitioning, OLAP and Oracle Data Mining options JServer Release 9.2.0.3.0 - Production Driver: Oracle JDBC driver Version: 9.2.0.3.0 [TopLink Info]: DATE TIME-DatabaseSession(12345)-Thread(12345)-loggingTestSession login successful
This type of logging makes TopLink conform to the java.util.logging package. It is provided by oracle.toplink.logging.JavaLog. Logging options are configured in the <JRE_HOME>/lib/logging.properties file. Messages are written to any number of destinations based on this configuration. Example 75-2 shows a typical java.util.logging log message.
For more information on using java.util.logging package, see "Configuring a Session to use java.util.logging Package".
Example 75-2 Sample java.util.logging Log Messages
Dec 9, 2003 2:05:05 PM oracle.toplink.loggingTestSession DatabaseSession(32603767) Thread(10) INFO: TopLink, version: Oracle TopLink - 10g (10.0.3) Developer Preview (Build 031203) Dec 9, 2003 2:05:07 PM oracle.toplink.loggingTestSession.connection DatabaseSession(32603767) Connection(927929) Thread(10) CONFIG: connecting(DatabaseLogin( platform=>Oracle9Platform user name=> "coredev8" datasource URL=> "jdbc:oracle:thin:@144.23.214.115:1521:toplink" ))Dec 9, 2003 2:05:08 PM oracle.toplink.loggingTestSession.connection DatabaseSession(32603767) Connection(927929) Thread(10) CONFIG: Connected: jdbc:oracle:thin:@144.23.214.115:1521:toplink User: COREDEV8 Database: Oracle Version: Oracle9i Enterprise Edition Release 9.2.0.3.0 - Production With the Partitioning, OLAP and Oracle Data Mining options JServer Release 9.2.0.3.0 - Production Driver: Oracle JDBC driver Version: 9.2.0.3.0 Dec 9, 2003 2:05:08 PM oracle.toplink.loggingTestSession DatabaseSession(32603767) Thread(10) INFO: loggingTestSession login successful
Server logging is used to integrate TopLink logging with an application server log.
The TopLink runtime determines the server log type to use given the server platform you configure when you create your project ("Project Creation Overview").
For example, if your project uses the OC4J platform, TopLink uses the oracle.toplink.platform.server.oc4j.OjdlLog; if your project uses the BEA WebLogic platform, TopLink uses the oracle.toplink.platform.server.wls.WlsLog.
If you are using TopLink native logging, you can configure TopLink to write log messages to a file or to the console (see "Configuring Logging").
If you are using java.util.logging, TopLink writes log messages to the destinations you configure in the <JRE_HOME>/lib/logging.properties file (see "Configuring a Session to use java.util.logging Package").
If you are using server logging, TopLink writes log messages to the application server's log file (there is no separate TopLink log file in this case).
You can control the amount and detail of log output by configuring the log level (in ascending order of information) in the following way:
SEVERE–Logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.
WARNING–Logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.
INFO (default)–Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.
CONFIG–Logs only login, JDBC connection, and database information.
FINE–Logs SQL (including thread information).
FINER–Similar to warning. Includes stack trace.
FINEST–Includes additional low level information
ALL–Logs everything.
By default, TopLink logs at the oracle.toplink.logging.SessionLog.INFO level so that some information is logged by default.
At run time, set the log level using Session method setLogLevel, passing in one of the log level constants provided by oracle.toplink.logging.SessionLog.
In a relational project, TopLink accesses the database using SQL strings that it generates internally. This feature enables applications to use the session methods or query objects without having to perform their own SQL translation.
If, for debugging purposes, you want to review a record of the SQL that is sent to the database, set the session log level to oracle.toplink.logging.SessionLog.FINE–the session will log all executed SQL to the session log.
The logging chained exception facility enables you to log causality when one exception causes another as part of the standard stack back-trace. If you build your applications with JDK 1.4, causal chains appear automatically in your logs.
You can view TopLink log messages using Oracle Enterprise Manager 10g.
If you are using TopLink native logging (to a file) or java.util.logging package, edit the <OC4J_HOME>\toplink\config\TOPLINK.xml file log element attribute path to match the log output file you specified in your session (see "Configuring Logging"), or in the <JRE_HOME>/lib/logging.properties file (see "Configuring a Session to use java.util.logging Package"). Example 75-3 shows the default TOPLINK.xml file:
Example 75-3 Default TOPLINK.xml File
<?xml version="1.0" encoding="UTF-8" ?> <logs xmlns="http://www.oracle.com/iAS/EMComponent/ojdl"> <log path="toplink/config/toplink.log" componentId="TOPLINK"> <logviewer LogType="ERROR" /> </log> </logs>
If you are using server logging, you do not need to configure the <OC4J_HOME>\toplink\config\TOPLINK.xml file: in this case, it is not used. Instead, all TopLink log messages are written to the OC4J log file (which you can also view from the application server control console).
For more information, see the Oracle Application Server Administrator's Guide.
The TopLink session provides profiling API that lets you identify performance bottlenecks in your application (see "Configuring a Performance Profiler"). When enabled, the profiler logs a summary of the performance statistics for every query that the application executes.
TopLink allows you to measure application performance using the following tools:
The TopLink profiler is a high-level logging service. Instead of logging SQL statements, the profiler logs a summary of each query you execute. The summary includes a performance breakdown of the query that lets you identify performance bottlenecks. The profiler also provides a report summarizing the query performance for an entire session.
Access profiler reports and profiles through the Profile tab in the TopLink Web client, or create your own application or applet to view the profiler logs. For more information, see "Accessing the TopLink Profiler Results".
For more information, see "Measuring Performance With the TopLink Profiler".
Oracle DMS is a library that enables application and system developers to use a variety of DMS sensors to measure and export customized performance metrics for specific software components (called nouns).
TopLink includes DMS instrumentation in essential objects to provide efficient monitoring of runtime data in TopLink enabled applications, including both J2EE and non-J2EE applications.
By enabling DMS profiling in a TopLink application, you can collect and easily access run-time data that can help you with application administration tasks and performance tuning.
You can easily access DMS data at run time using a management application that supports the Java Management Extensions (JMX) API (see "Accessing Oracle DMS Profiler Data Using JMX"), or using any Web browser and the DMS Spy servlet (see "Accessing Oracle DMS Profiler Data Using the DMS Spy Servlet").
For more information, see "Measuring Performance With the Oracle Dynamic Monitoring System (DMS)".
When you log into a session, TopLink initializes and validates the descriptors you registered with it. By configuring the integrity checker, you can customize this validation process.
For more information, see "Configuring the Integrity Checker".
Exception handlers allow any exception that occurs in a session to be caught and processed. Exception handlers can be used for debugging purposes, or to resolve database timeouts or failures.
To use exception handlers, register an implementor of the oracle.toplink.exceptions.ExceptionHandler interface with the session (see "Configuring an Exception Handler").
If an exception occurs during a session operation, such as executing a query, the exception is passed to the exception handler. The exception handler can either rethrow the exception, or handle the exception and retry the operation. When handling exceptions, ensure that the following conditions are met:
If you are performing a write query and you are within a transaction, you should not retry the operation.
If you are performing a read query, you may retry the operation, and, if successful, return the query result.
If your exception handler cannot proceed, you should throw an appropriate application-specific exception.
For more information on the types of exceptions that TopLink can throw, see Part V, "Troubleshooting a TopLink Application".
You use a session to perform persistence operations on the objects described by TopLink mapping metadata represented as a TopLink project (see "Understanding Projects"). Each session must therefor be associated with the descriptors of at least one TopLink project. You associate descriptors with a session by registering them with the session.
The preferred way to register descriptors with a session is to use TopLink Workbench to configure the session with a mapping project (see "Configuring a Primary Mapping Project" and "Configuring Multiple Mapping Projects").
Although TopLink is an integral part of a J2EE application, in most cases the client does not interact with TopLink directly. Instead, TopLink features are invoked indirectly by way of EJB container callbacks.
In a CMP TopLink project, you do not explicitly create, configure, or acquire a session. The TopLink runtime creates, configures, acquires and uses a session itself internally. For more information, see "Creating Session Metadata". Similarly, in a CMP TopLink project, how metadata is deployed depends on the CMP container and application server you use (see "Deploying Metadata").
An essential part of maintaining object identity is managing the assignment of unique values to distinguish one instance from another. For more information, see "Projects and Sequencing".
Sequencing options you configure in a sessions.xml (or project.xml) file determine the type of sequencing that TopLink uses.
In a CMP project, you do not configure a sessions.xml file directly: in this case you must configure the sequence type in the project.xml file (see "Configuring Sequencing at the Project Level").
In a non-CMP project, you can use session-level sequence configuration to override project-level sequence configuration, on a session-by-session basis, if required (see "Configuring Sequencing at the Session Level").
After configuring the sequence type at the session (or project) level, for each descriptor you must also configure sequencing options for that descriptor to use sequencing (see "Descriptors and Sequencing").
