87 Introduction to TopLink Sessions

A TopLink session provides the primary access to the TopLink runtime. It is the means by which your application performs all persistence operations with the data source that contains persistent objects.

A session associates data source platform information, data source login information, and mapping metadata for a particular application. You can reuse mapping metadata in different applications by defining different sessions.

TopLink provides different session types, each optimized for different design requirements and data access strategies. You can combine different session types in the same application.

This chapter includes the following sections:

87.1 Session Types

Table 87-1 lists the session types that you can use in a POJO TopLink application and classifies them as basic or advanced. See Section 87.2.11, "Sessions and CMP" for information on using Oracle TopLink with CMP.

Table 87-1 TopLink Session Types

Session Type Description Oracle JDeveloper
TopLink Workbench
Java

Server and client sessions (see Section 87.3, "Server and Client Sessions")

Server sessions provide session management to a single data source (including shared object cache and connection pools) for multiple clients in a three-tier architecture using database or EIS platforms. This is the most flexible, scalable, and commonly used session.

You acquire a client session from a server session at run time to provide access to a single data source for each client.

Supported Supported Supported

Unit of work sessions (see Section 87.4, "Unit of Work Sessions")

Acquired from any session type (directly, or by way of an external transaction controller) to transactionally modify objects.

Unsupported

Unsupported

Supported

Isolation client sessions (see Section 87.5, "Isolated Client Sessions")

A special type of client session that uses a session cache isolated from the shared object cache of its parent server session.

Unsupported

Unsupported

Supported

Historical sessions (see Section 87.6, "Historical Sessions")

A special type of client session that provides a read-only snapshot of object versions as of a specified time and uses a session cache isolated from the shared object cache of its parent server session.

Unsupported

Unsupported

Supported

Session broker and client sessions (see Section 87.7, "Session Broker and Client Sessions")

Provides session management to multiple data sources for multiple clients by aggregating two or more server sessions (can also be used with database sessions).

You acquire a client session from a session broker at run-time to provide access to all the data sources managed by the session broker for each client.

Supported Supported Supported

Database sessions (see Section 87.8, "Database Sessions")

Provides session management to a single database for a single client suitable for simple or two-tiered applications. Oracle does not recommend this session type in three-tiered applications because it does not offer the same flexibility and scalability as the server session.

Supported Supported Supported

Remote sessions (see Section 87.9, "Remote Sessions")

A client-side session that communicates over RMI with a corresponding dedicated client session and shared server session. Remote sessions handle object identity and marshalling and unmarshalling between client-side and server-side.

Unsupported

Unsupported

Supported

For more information, see the following:

87.2 Session Concepts

This section describes concepts unique to TopLink sessions, including the following:

87.2.1 Session Architecture

As Figure 87-1 illustrates, a session instance is composed of the following components:

Figure 87-1 Simple TopLink Session Architecture

Description of Figure 87-1 follows
Description of "Figure 87-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.

87.2.1.1 Object Cache

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 Section 87.5, "Isolated Client Sessions" and Section 87.6, "Historical 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 Section 87.4, "Unit of Work Sessions".

For more information, see Section 87.10, "Sessions and the Cache".

87.2.1.2 Connection Pools

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 Section 87.7, "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 Java EE 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 Section 96.1.6.1, "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 Section 96.1.6.2, "External Connection Pools".

For more information about data access configuration in general, see Chapter 96, "Introduction to Data Access".

87.2.1.3 Query Mechanism

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 Chapter 108, "Introduction to TopLink Queries".

87.2.1.4 Java Object Builder

When you use object-level read queries, TopLink automatically builds Java objects from the data retrieved. When you use object-level write queries, TopLink automatically converts the affected Java objects into the appropriate data native to your data source.

87.2.2 Session Configuration and the sessions.xml File

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 provides the following advantages:

  • 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 Section 88.1, "Introduction to the Session Creation".

87.2.3 Session Customization

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.

Since the sessions.xml file is not used for CMP projects, use oracle.toplink.ejb.cmp.DeploymentCustomization interface as a customizer when creating a CMP project to specify your database login information.

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 Section 16.2.7, "Amendment and After-Load Methods").

For more information, see Section 89.8, "Configuring a Session Customizer Class".

87.2.4 Acquiring a Session at Run Time with the Session Manager

The TopLink session manager lets you 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 Section 87.2.2, "Session Configuration and the sessions.xml File"), caches the sessions by name in memory, and provides a single access point for TopLink sessions.

At run time, TopLink will attempt to load the sessions.xml file from the two following default resource names: sessions.xml and META-INF/sessions.xml. Refer to Chapter 10, "Packaging a TopLink Application" for additional information.

The session manager supports the following session types:

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:

  1. The client application requests a session by name.

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

  3. 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 Chapter 90, "Acquiring and Using Sessions at Run Time".

87.2.5 Managing Session Events with the Session Event Manager

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 Chapter 92, "Configuring Exclusive Isolated Client Sessions for Virtual Private Database"). In an isolated session, if the TopLink runtime raises a SessionEvent.NoRowsModified event, it is handled by your SessionEventListener (see Section 92.4, "Using 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). See Section 87.2.6, "Logging" for information on adding logging to your event listeners.

Another example is the use of session event listeners to configure proxy authentication in Oracle Database. (see Section 98.8, "Configuring Oracle Database Proxy Authentication").

87.2.5.1 Session Event Manager Events

The session event manager supports the session events listed in the following tables:

Table 87-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 ReadObjectQuery detects more than one row returned from the database. This event can indicate a possible error condition in your application.

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 87-3 Unit of Work Events

Event Description

PostAcquireUnitOfWork

Raised after a UnitOfWork is acquired

PostCalculateUnitOfWorkChangeSet

Raised after the commit has begun on the UnitOfWork and after the changes are calculated. The UnitOfWorkChangeSet, at this point, will contain change sets without the version fields updated and without identity field type primary keys. These will be updated after the insert, or update, of the object.

PostCommitUnitOfWork

Raised after a UnitOfWork commits

PostDistributedMergeUnitOfWorkChangeSet

Raised after a UnitOfWork change set has been merged when that change set has been received from a distributed session.

PostMergeUnitOfWorkChangeSet

Raised after a UnitOfWork change set has been merged.

PostReleaseUnitOfWork

Raised on a UnitOfWork after it is released.

PostResumeUnitOfWork

Raised on a UnitOfWork after it resumes.

PreCalculateUnitOfWorkChangeSet

Raised after the commit has begun on the UnitOfWork but before the changes are calculated.

PreCommitUnitOfWork

Raised before a UnitOfWork commits.

PreDistributedMergeUnitOfWorkChangeSet

Raised before a UnitOfWork change set has been merged when that change set has been received from a distributed session.

PreMergeUnitOfWorkChangeSet

Raised before a UnitOfWork change set has been merged.

PrepareUnitOfWork

Raised after the a UnitOfWork flushes its SQL, but before it commits its transaction.

PreReleaseUnitOfWork

Raised on a UnitOfWork before it is released.


87.2.5.2 Session Event Listeners

You can create session event listeners in 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 Section 89.10, "Configuring Session Event Listeners".

87.2.6 Logging

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 Section 12.3, "Measuring TopLink Performance with the TopLink Profiler" or Section 12.4, "Measuring TopLink Performance with the Oracle Dynamic Monitoring System (DMS)").

Logging options are configurable at the session level (see Section 89.4, "Configuring Logging").

Note:

To facilitate debugging, you can add logging to your listeners to only log the events that are of the interest to your application. Within the session context, use the following logging utility:
Session.getSessionLog().log(int level, String message) 

Without the session context, use the following logging utility:

AbstractSessionLog.getLog().log(int level, String message)

Both the getSessionLog and getLog methods return a session log (an instance of a SessionLog interface) loaded with an accessor's log messages and SQL. Then the session log performs logging at the level that you specify.

For more information on session event listeners, see Section 87.2.5.2, "Session Event Listeners".

87.2.6.1 Log Types

TopLink supports the following types of logging:

87.2.6.1.1 TopLink Native Logging

TopLink native logging is the default session log type. It is provided by oracle.toplink.logging.DefaultSessionLog. Example 87-1 shows a typical TopLink native log message.

You can configure TopLink native logging options using TopLink Workbench (see Section 89.4.1, "How to Configure Logging Using TopLink Workbench").

Example 87-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
87.2.6.1.2 java.util Logging

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 87-2 shows a typical java.util.logging log message.

For more information on using java.util.logging package, see Section 89.4.5, "How to Configure a Session to use the java.util.logging Package".

Example 87-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
87.2.6.1.3 Server Logging

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 (Section 116.1, "Introduction to the Project Creation").

For example, if your project uses the WebLogic platform, TopLink uses the oracle.toplink.platform.server.wls.WlsLog; if your project uses the OC4J platform, TopLink uses the oracle.toplink.platform.server.oc4j.OjdlLog.

For more information, see the following:

87.2.6.2 Log Output

If you are using TopLink native logging, you can configure TopLink to write log messages to a file or to the console (see Section 89.4, "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 Section 89.4.5, "How to Configure a Session to use the 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).

87.2.6.3 Log Level

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

87.2.6.4 Logging SQL

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.

Example 87-3 shows how to configure the log destination using the setLog method on the session.

Example 87-3 Configuring the Log Destination

private static SessionEventListener buildListener() {
    return new SessionEventAdapter() {
        public void preLogin(SessionEvent event) {
            File file = new
            File("C:\\oracle\\904\\toplink\\examples\\jdev\\2-TierEmployee\\toplink.log");
        try {
            System.out.println("FILE: " + file.getAbsolutePath());
            FileWriter writer = new FileWriter(file);
            event.getSession().setLog(writer);
            } catch (IOException ioe) {
            ioe.printStackTrace();
            throw new RuntimeException("Failed to setup logging to: " + file.getAbsolutePath());            }
        }
    };
}

87.2.6.5 Logging Chained Exceptions

The logging chained exception facility enables you to log causality when one exception causes another as part of the standard stack back-trace. Causal chains appear automatically in your logs.

87.2.6.6 Logging Inside a Java EE Container

When you deploy a TopLink- enabled application to an application server or EJB container, TopLink CMP and EclipseLink JPA default to ServerLog with no log level so that TopLink uses the configuration in j2ee-logging.xml.

For more information, see Section 89.4, "Configuring Logging".

87.2.6.7 Logging Outside of a Java EE Container

When you deploy a TopLink-enabled application outside of an EJB container, the logging defaults revert to DefaultSessionLog and INFO log level.

If you are using TopLink native logging (to a file) or the java.util.logging package outside of a Java EE container, you control logging using the <JRE_HOME>/lib/logging.properties file.

For more information, see the following:

87.2.7 Profiler

The TopLink session provides profiling API that lets you identify performance bottlenecks in your application (see Section 89.6, "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 TopLink Profiler or Oracle Dynamic Monitoring System (DMS).

87.2.7.1 TopLink Profiler

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 Section 12.3.2, "How to Access the TopLink Profiler Results".

For more information, see Section 12.3, "Measuring TopLink Performance with the TopLink Profiler".

87.2.7.2 Oracle Dynamic Monitoring System (DMS)

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 Java EE and non-Java EE 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 Section 12.4.2, "How to Access Oracle DMS Profiler Data Using JMX"), or using any Web browser and the DMS Spy servlet (see Section 12.4.3, "How to Access Oracle DMS Profiler Data Using the DMS Spy Servlet").

For more information, see Section 12.4, "Measuring TopLink Performance with the Oracle Dynamic Monitoring System (DMS)".

87.2.8 Integrity Checker

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 Section 89.11, "Configuring the Integrity Checker".

87.2.9 Exception Handlers

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 Section 89.7, "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 Appendix A, "Troubleshooting a TopLink Application".

87.2.10 Registering Descriptors

You use a session to perform persistence operations on the objects described by TopLink mapping metadata represented as a TopLink project (see Chapter 15, "Introduction to 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 Oracle JDeveloper TopLink Editor or TopLink Workbench to configure the session with a mapping project (see Section 89.2, "Configuring a Primary Mapping Project" and Section 89.5, "Configuring Multiple Mapping Projects").

87.2.11 Sessions and CMP

Although TopLink is an integral part of a Java EE 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 Section 2.9.3, "Creating Session Metadata". Similarly, in a CMP TopLink project, how metadata is deployed depends on the EJB container and application server you use (see Section 2.9.4, "Deploying Metadata").

87.2.12 Sessions and Sequencing

An essential part of maintaining object identity is managing the assignment of unique values to distinguish one instance from another. For more information, see Section 15.2.6, "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 Section 20.3, "Configuring Sequencing at the Project Level").

In a POJO project, you can use session-level sequence configuration to override project-level sequence configuration, on a session-by-session basis, if required (see Section 98.4, "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 Section 16.2.10, "Descriptors and Sequencing").

87.3 Server and Client Sessions

A server session manages the server side of client/server communications, providing shared resources, including a shared object cache and connection pools to a single data source.

A client session is a server-side communications mechanism that works together with the server session to provide the client/server connection. You acquire client sessions from a server session at run time as required. By default, a client session shares the session cache of its parent server session. Each client session serves one client. A client session communicates with the server session on behalf of the client application.

Each client session can have only one associated server session, but a server session can support any number of client sessions.

As Figure 87-2 illustrates, together, the client session and server session provide a three-tier architecture that you can scale easily, by adding more client sessions. A server session is the most common TopLink session type because it supports this three-tier architecture that is common in enterprise applications. Because of this scalability, Oracle recommends that you use the threeEtier architecture to build your TopLink applications.

Figure 87-2 Typical TopLink Server Session with Client Session Architecture

This section explains the advantages of using server sessions and client sessions in your TopLink application, including the following:

For more information, see the following:

87.3.1 Three-Tier Architecture Overview

In a TopLink three-tier architecture, client sessions and server sessions both reside on the server. Client applications access the TopLink application through a client session, and the client session communicates with the database using the server session.

Figure 87-3 Server Session and Client Session Usage

Description of Figure 87-3 follows
Description of "Figure 87-3 Server Session and Client Session Usage"

87.3.2 Advantages of the TopLink Three-Tier Architecture

Although the server session and the client session are two different session types, you can treat them as a single unit in most cases, because they are both required to provide three-tier functionality to the application. The server session provides the client session to client applications, and also supplies the majority of the session functionality.

This section discusses some of the advantages and general concepts associated with the TopLink threeEtier design, including the following:

87.3.2.1 Shared Resources

The three-tier design enables multiple clients to share persistent resources. The server session provides its client sessions with a shared live object cache, read and write connection pooling, and parameterized named queries. Client sessions also share descriptor metadata.

You can use client sessions and server sessions in any application server architecture that allows for shared memory and supports multiple clients. These architectures can include HyperText Markup Language (HTML), Servlet, JavaServer Pages (JSP), Remote Method Invocation (RMI), Common Object Request Broker Architecture (CORBA), Web services, and EJB.

To support a shared object cache, client sessions must do the following:

  • Implement any changes to the database with the TopLink unit of work.

  • Share a common database login for reading (you can implement separate logins for writing).

87.3.2.2 Providing Read Access

To read objects from the database, the client must first acquire a client session from the server session. Acquiring a client session gives the client access to the session cache and the database through the server session. The server session behaves as follows:

  • If the object or data is in the session cache, then the server session returns the information back to the client.

  • If the object or data is not in the cache, then the server session reads the information from the database and stores the object in the session cache. The objects are then available for retrieval from the cache.

Because a server session processes each client request in a separate thread, this enables multiple clients to access the database connection pool concurrently.

Figure 87-4 illustrates how multiple clients read from the database using the server session.

Figure 87-4 Multiple Client Sessions Reading the Database Using the Server Session

Description of Figure 87-4 follows
Description of "Figure 87-4 Multiple Client Sessions Reading the Database Using the Server Session"

To read objects from the database using a client session, do the following:

  1. Acquire a Session from the Server:

    Server server = 
        (Server) SessionManager.getManager().getSession(
            sessionName, MyServerSession.class.getClassLoader()
        );
    Session clientSession = (Session) server.acquireClientSession();
    

    For more information, see Chapter 90, "Acquiring and Using Sessions at Run Time".

  2. Use the Session object to perform read operations (for more information, see Chapter 108, "Introduction to TopLink Queries" and Chapter 110, "Introduction to TopLink Expressions").

    Note:

    Oracle recommends that you do not use the Server session object directly to read objects from the database.

87.3.2.3 Providing Write Access

Because the client session disables all database modification methods, a client session cannot create, change, or delete objects directly. Instead, the client must obtain a unit of work from the client session to perform database modification methods.

To write to the database, the client acquires a client session from the server session and then acquires a unit of work within that client session. The unit of work acts as an exclusive transactional object space, and also ensures that any changes that are committed to the database also occur in the session cache.

Note:

Although client sessions are thread-safe, do not use them to write across multiple threads. Multithread write operations from the same client session can result in errors and a loss of data. For more information, see Section 87.3.2.5, "Concurrency".

Figure 87-5 illustrates how to write to the database using a client session acquired from a server session.

Figure 87-5 Writing with Client Sessions and Server Sessions

Description of Figure 87-5 follows
Description of "Figure 87-5 Writing with Client Sessions and Server Sessions"

To write to the database using a unit of work, use this procedure:

  1. Acquire a session from the server session:

    Server server = 
        (Server) SessionManager.getManager().getSession(
            sessionName, MyServerSession.class.getClassLoader()
        );
    Session clientSession = (Session) server.acquireClientSession();
    

    For more information, see Chapter 90, "Acquiring and Using Sessions at Run Time".

  2. Acquire a UnitOfWork object from the Session object.

    UnitOfWork uow = clientSession.acquireUnitOfWork();
    

    For more information, see Section 87.4, "Unit of Work Sessions".

  3. Use the unit of work to perform the required updates and then commit the UnitOfWork.

    For more information, see the following:

87.3.2.4 Security and User Privileges

You can define several different server sessions in your application to support users with different data access rights. For example, your application may serve a group called "Managers," who has access rights to salary information, and a group called "Employees," who do not. Because each session you define in the sessions.xml file has its own login information, you can create multiple sessions, each with its own login credentials, to meet the needs of both of these groups.

When you use internal TopLink connection pools (see Section 96.1.6, "Connection Pools"), each server session provides a read connection pool and a write connection pool. All read queries use connections from the read connection pool and all queries that write changes to the data store use connections from the write connection pool. This ensures that connections for one session are kept separate from the connections used in another.

To further isolate users from one another, you can use an isolated session: a special type of client session that provides its own session cache isolated from the shared object cache of its parent server session to provide improved user-based security, or to avoid caching highly volatile data. For more information, see Section 87.5, "Isolated Client Sessions".

87.3.2.5 Concurrency

The server session supports concurrent clients by providing each client with a dedicated thread of execution. Dedicated threads enable clients to operate asynchronously–that is, client processes execute as they are called and do not wait for other client processes to complete.

TopLink safeguards thread safety with a concurrency manager. The concurrency manager ensures that no two threads interfere with each other when performing operations such as creating new objects, executing a transaction on the database, or accessing value holders.

For more information about handling concurrency issues, see Section 102.2.3, "Handling Stale Data".

87.3.2.6 Connection Allocation

When you instantiate the server session, it creates a pool of data source connections. The session then manages the connection pool based on your session configuration, and shares the connections among its client sessions. When the client session releases the connection, the server session recovers the connection and makes it available to other client processes. Reusing connections reduces the number of connections required by the application and allows a server session to support a larger number of clients.

The server session provides connections to client sessions as needed. By default, the server session does not allocate a data source connection for a client session until a transaction starts (a lazy data source connection). Alternatively, you can acquire a client session that allocates a connection immediately (see Section 90.4.5, "How to Acquire a Client Session that Does Not Use Lazy Connection Allocation").

The server session allocates read connections from its read connection pool to all client sessions. If your application requires multiple read security levels then you must use multiple server sessions or TopLink isolated sessions (see Section 87.5, "Isolated Client Sessions").

The server session also supports multiple write connection pools and nonpooled connections. Be default, all client sessions use the default write connection pool. However, if your application requires multiple security levels or user logins for write access, then you can use multiple write connection pools. You can configure a client session to use a specific write connection pool or nonpooled connection when it is acquired (see Section 90.4.4, "How to Acquire a Client Session that Uses a Named Connection Pool"). This connection is only used for writes, not reads (reads still go through the server session read connection pool).

For more information, see the following:

87.4 Unit of Work Sessions

The unit of work ensures that the client edits objects in a separate object transaction space. This feature lets clients perform object transactions in parallel. When transactions are committed, the unit of work makes any required changes in the database, and then merges the changes into the shared TopLink session cache. The modified objects are then available to all other users.

For information on creating, configuring, and using a unit of work, see Chapter 113, "Introduction to TopLink Transactions".

87.5 Isolated Client Sessions

An isolated client session is a special type of client session that provides its own session cache. This session cache is isolated from the shared session cache of its parent server session.

If in your TopLink project you configure all classes as isolated (see Section 117.11, "Configuring Cache Isolation at the Project Level"), or one or more classes as isolated (see Section 119.13, "Configuring Cache Isolation at the Descriptor Level"), then all client sessions that you acquire from a parent server session will be isolated client sessions.

Figure 87-6 illustrates the relationship between a parent server session's shared session cache and its child isolated client sessions.

Figure 87-6 Isolated Client Sessions

Description of Figure 87-6 follows
Description of "Figure 87-6 Isolated Client Sessions"

Each isolated client session owns an initially empty cache and identity maps used exclusively for isolated objects that the isolated client session accesses while it is active. The isolated client session's isolated session cache is discarded when the isolated client session is released.

When you use an isolated client session to read an isolated class, the client session reads the isolated object directly from the database and stores it in that client session's isolated session cache. When you use the client session to read a shared class, the client session reads the shared object from the parent server session's shared session cache. If the shared object is not in the parent server session's shared session cache, it will read it from the database and store it in the parent server session's shared session cache.

Isolated objects in an isolated client session's isolated session cache may reference shared objects in the parent server session's shared session cache, but shared objects in the parent server session's shared session cache cannot reference isolated objects in an isolated client session's isolated session cache.

Note:

You cannot define mappings from shared classes to isolated classes. If using CMP, you also cannot define references from isolated enterprise beans to shared EJB.

Client sessions can access the data source using a connection pool, or an exclusive connection. To use an exclusive connection, acquire the isolated client session using a ConnectionPolicy (see Section 90.4.2, "How to Acquire a Client Session that Uses Exclusive Connections"). Using an exclusive connection provides improved user-based security for reads and writes. Named queries can also use an exclusive connection (see Section 119.7.1.10, "Configuring Named Query Advanced Options").

Note:

If an isolated session contains an exclusive connection, you must release the session when you are finished using it. Oracle does not recommend relying on the finalizer to release the connection when the session is garbage -collected. If you are using an active unit of work in a JTA transaction, you do not need to release the client session–the unit of work will release it after the JTA transaction completes.

Use isolated client sessions to do the following:

For more information, see the following:

87.5.1 Isolated Client Sessions and Oracle Virtual Private Database (VPD)

Oracle9i Database (and later) provides a server-enforced, fine-grained access control mechanism called Virtual Private Database (VPD). VPD ties a security policy to a table by dynamically appending SQL statements with a predicate to limit data access at the row level. You can create your own security policies, or use Oracle's custom implementation of VPD called Oracle Label Security (OLS). For more information on VPD and OLS, see the following:

http://www.oracle.com/technology/deploy/security/index.html.

To use Oracle Database VPD feature in your TopLink-enabled application, use isolated client sessions.

Any class that maps to a table that uses VPD must have the descriptor configured as isolated (see Section 119.13, "Configuring Cache Isolation at the Descriptor Level").

When you use isolated client sessions with VPD, you typically use exclusive connections (see Section 90.4.2, "How to Acquire a Client Session that Uses Exclusive Connections").

To support VPD, you are responsible for implementing session event handlers that the TopLink runtime invokes during the isolated client session life cycle (see Section 87.5.1.3, "Isolated Client Session Life Cycle"). The session event handler you must implement depends on whether or not you are using Oracle Database proxy authentication (see Section 87.5.1.1, "VPD with Oracle Database Proxy Authentication" and Section 87.5.1.2, "VPD Without Oracle Database Proxy Authentication").

For information, see Chapter 92, "Configuring Exclusive Isolated Client Sessions for Virtual Private Database".

87.5.1.1 VPD with Oracle Database Proxy Authentication

If you are using Oracle Database proxy authentication (Section 96.1.4.2, "Oracle Database Proxy Authentication"), you must implement a session event handler for the following session events:

By using Oracle Database proxy authentication, you can set up VPD support entirely in the database. That is, rather than making the isolated client session execute SQL (see Section 92.2, "Using PostAcquireExclusiveConnection Event Handler" and Section 92.3, "Using PreReleaseExclusiveConnection Event Handler"), the database performs the required setup in an after login trigger using the proxy session_user.

87.5.1.2 VPD Without Oracle Database Proxy Authentication

If you are not using Oracle Database proxy authentication, you must implement session event handlers for the following session events:

In your implementation of these handlers, you obtain the required user credentials from the ConnectionPolicy associated with the session (see Section 90.4.3, "How to Acquire a Client Session that Uses Connection Properties").

87.5.1.3 Isolated Client Session Life Cycle

This section provides an overview of the key phases in the life cycle of an isolated session, including the following:

  • Setup required before using an isolated session

  • Interaction among isolated session objects

  • Clean-up required after using an isolated session

To enable the life cycle of an isolated session, use this procedure:

  1. Prepare VPD configuration in the database.

  2. Configure your project and session:

  3. Acquire an isolated session:

    • If you are using Oracle Database proxy authentication (see Section 96.1.4.2, "Oracle Database Proxy Authentication"):

      Session myIsolatedClientSession = server.acquireClientSession();
      

      Because you configured one or more descriptors as isolated, myIsolatedClientSession is an isolated session with an exclusive connection.

    • If you are not using Oracle Database proxy authentication:

      ConnectionPolicy myConnPolicy = 
          (ConnectionPolicy)server.getDefaultConnectionPolicy().clone();
      myConnectionPolicy.setProperty("credentials", myUserCredentials);
      Session myIsolatedClientSession =
          server.acquireClientSession(myConnectionPolicy);
      

      Set the user's credentials as appropriate properties on myConnectionPolicy. Because you configured one or more descriptors as isolated, myIsolatedClientSession is an isolated session with an exclusive connection.

    The TopLink runtime raises a SessionEvent.PostAcquireExclusiveConnection event handled by your SessionEventListener (see Section 92.2, "Using PostAcquireExclusiveConnection Event Handler").

  4. Use myIsolatedClientSession to interact with the database.

    If the TopLink runtime raises a SessionEvent.NoRowsModified event, it is handled by your SessionEventListener (see Section 92.4, "Using NoRowsModifiedSessionEvent Event Handler").

  5. When you are finished using myIsolatedClientSession, release the isolated session:

    myIsolatedClientSession.release();
    

    The TopLink runtime prepares to destroy the isolated cache and to close the exclusive connection associated with this isolated session.

    The TopLink runtime raises a SessionEvent.PreReleaseExclusiveConnection event handled by your SessionEventListener (see Section 92.3, "Using PreReleaseExclusiveConnection Event Handler").

  6. Repeat steps 3 to 5 (as required) until the application exits.

87.5.2 Isolated Client Session Limitations

For the purposes of security as well as efficiency, observe the limitations described in the following section, when you use isolated client sessions in your TopLink three-tier application:

Mapping

Consider the following mapping and relationship restrictions when using isolated sessions with your relational model:

  • Isolated objects may be related to shared objects, but shared objects cannot have any relationships with isolated objects.

  • If a table has a VPD security policy associated with it, then the class mapped to that table must be isolated.

  • If one of the tables in a multiple table mapping is isolated, then the main class must also be isolated.

The TopLink runtime enforces these restrictions during descriptor initialization.

Inheritance

Aggregates and aggregate mappings inherit the isolated configuration of their parents.

If a class is isolated, then all inheriting classes should be isolated. Otherwise, if you relate a shared class to a shared superclass with isolated subclasses, it is possible that some of the isolated subclasses will lose object identity when the isolated session is released.

To give you the flexibility to mix shared and isolated classes, the TopLink runtime does not enforce these restrictions during descriptor initialization. If you wish to mix shared and isolated classes in your inheritance hierarchy, then you must be prepared to deal with this possible loss of object identity.

Caching and Cache Coordination

Isolated classes are never loaded into the shared cache of a parent server session. Isolated classes cannot be used with cache coordination.

Sequencing

Oracle recommends that you do not configure a sequencing object as isolated. TopLink does not access sequencing objects using the isolated session's dedicated connection, and so the sequence values are not available to the isolated session.

CMP

For CMP, relationships between isolated and shared data is not allowed. This is because of the relationship maintenance requirements of having bidirectional references for all relationships.

Transactions and JTA

Oracle recommends that you explicitly release an isolated session when you are finished using it, rather than wait for the Java garbage collector to invoke the finalizer. The finalizer is provided as a last resort: waiting for the garbage collector may cause errors when dealing with a JTA transaction.

87.6 Historical Sessions

By default, a session represents a view of the most current version of objects, and when you execute a query in that session, it returns the most current version of selected objects.

If your data source maintains past versions of objects, you can configure TopLink to access this historical data so that you can express read queries conditional on how your objects are changing over time. You can also do the following:

  • Make series of queries relative to any point in time–not just the time of the first query.

  • Provide read consistency so that a series of read operations or report queries all execute as if at the same time.

  • Use the mergeClone method to provide deep recovery of an object by passing in a past version of it.

In addition, you can express query selection criteria as either of the following:

  • A condition at a past time: for example, "employees who used to...".

  • A change over time: for example, "employees who recently...".

For more information, see the following:

87.6.1 Historical Session Limitations

The HistoryPolicy provides a very flexible means of accommodating a wide variety of historical schemas. However, be aware of the following restrictions:

  • You cannot use the HistoryPolicy, if your design combines both current and historical data in a single schema.

  • You cannot use historical sessions, nor historical queries, with EJB entity beans.

  • TopLink assumes that the current version of an object corresponds to the row in the historical table whose row end field is NULL.

  • You cannot directly map the start and end fields of a history table because they do not exist in the regular schema.

  • You cannot query on ranges of historical objects, only as of a specific point in time.

87.7 Session Broker and Client Sessions

The TopLink session broker is a mechanism that enables client applications to transparently access multiple databases through a single TopLink session.

The TopLink session broker enables client applications to access two or more databases through a single session. If your application stores objects in multiple databases, the session broker, which provides seamless communication for client applications, enables the client to view multiple databases as if they were a single database.

When a three-tier session broker application uses server sessions to communicate with the database, clients require a client session to access the database. Similarly, when you implement a session broker, the client requires a client session broker to access the database.

A client session broker is a collection of client sessions, one from each server session associated with the session broker. When a client acquires a client session broker, the session broker collects one client session from each associated server session, and wraps the client sessions so that they appear to be a single client session to the client application.

As Figure 87-7 illustrates, a session broker connects to the databases through two or more server sessions or database sessions.

Figure 87-7 TopLink Session Broker with Server Session Architecture

Description of Figure 87-7 follows
Description of "Figure 87-7 TopLink Session Broker with Server Session Architecture"

This section explains the following:

For information, see the following:

87.7.1 Session Broker Architecture

As Figure 87-7 illustrates, a session broker contains a broker object that acts as an intermediary between the application and the multiple sessions added to the session broker.

To construct a session broker, use TopLink Workbench to modify your sessions.xml file as follows:

  1. Define two or more sessions (of the same type, either server sessions or database sessions).

  2. Define a session broker.

  3. Add the sessions to the session broker.

When you use SessionManager method getSession(sessionBrokerName) where sessionBrokerName is the name of the session broker you defined, the session manager returns the corresponding session broker session (call it mySessionBroker) that contains an instance of each of the sessions you added to it. When you use mySessionBroker method login, it logs into each defined session. Thereafter, you use mySessionBroker as you would any other session: TopLink transparently handles access to the multiple databases.

In the case of a three-tier architecture where the session broker contains two or more server sessions, you use session broker method acquireClientSessionBroker to acquire a single client session that lets you query across all the data sources managed by the various server sessions. You use this client session as you would any other client session.

87.7.2 Committing a Transaction with a Session Broker

By default, when you commit a transaction with a session broker session, a two-stage commit is performed.

Ideally, you should incorporate a JTA external transaction controller in order to benefit from its two-phase commit.

87.7.2.1 Committing a Session with a JTA Driver: Two-Phase Commits

If you use a session broker, incorporate a JTA external transaction controller wherever possible. The external transaction controller provides a two-phase commit, which passes the SQL statements that are required to commit the transaction to the JTA driver. The JTA driver handles the entire commit process.

JTA guarantees that the transaction commits or rolls back completely, even if the transaction involves more than one database. If the commit operation to any one database fails, then all database transactions roll back. The two-phase commit operation is the safest method available to commit a transaction to the database.

Two-phase commit support requires integration with a compliant JTA driver.

87.7.2.2 Committing a Session Without a JTA Driver: Two-Stage Commits

If there is no JTA driver available, then the session broker provides a twoEstage commit algorithm. A two-stage commit differs from a two-phase commit in that it guarantees data integrity only up to the point of the final commit of the transaction. If the SQL script executes successfully on all databases, but the commit operation then fails on one database, only the database that experiences the commit failure rolls back.

Although unlikely, this scenario is possible. As a result, if your system does not include a JTA driver and you use a two-stage commit, build a mechanism into your application to deal with this type of potential problem.

87.7.3 Session Broker Session Limitations

Although the session broker is a powerful tool that lets you use data that is distributed across multiple databases from a single application, it has some limitations including the following:

87.7.3.1 Many-to-Many Join Tables and Direct Collection Tables

By default, TopLink assumes that many-to-many and direct collection tables are on the same database as the source object. If they are on a different database, then you must configure the mapping's session name using ManyToManyMapping or DirectCollectionMapping method setSessionName, as Example 87-4 illustrates.Note that a many-to-many join table must still reside on the same database as the target object.

Example 87-4 Using Mapping setSessionName in a Descriptor Amendment Method

          public void addToDescriptor(ClassDescriptor descriptor) {
    descriptor.getMappingForAttributeName("projects").setSessionName("branch-database");
}

To work around this problem for data-level queries, use the DatabaseQuery method setSessionName.

87.7.4 Session Broker Alternatives

When evaluating whether or not to use a session broker in your application, consider the following alternatives:

87.7.4.1 Database Linking

Most enterprise databases, such as the Oracle Database, support linking other databases on the database server. This allows querying and two-phase commit across linked databases. Using the session broker is not the same as linking databases. If your database allows linking, Oracle recommends that you use that functionality to provide multiple database access instead of using a session broker.

87.7.4.2 Multiple Sessions

An alternative to the session broker is to use multiple sessions to work with multiple databases, as follows:

  • If the data on each database is unrelated to data on the other databases, and relationships do not cross database boundaries, then you can create a separate session for each database. For example, you might have individual databases and associated sessions dedicated to each department.

    This arrangement requires that you to manage each session manually and ensure that the class descriptors for your project reside in the correct session.

  • You can use additional sessions to house a standard batch job. In this case, you can create two or more sessions on the same database. In addition to the main session that supports client queries, you create other sessions that support batch inserts at low-traffic times in your system. This lets you maintain the client cache.

87.8 Database Sessions

A database session provides a client application with a single data source connection, for simple, standalone applications in which a single connection services all data source requests for one user.

Figure 87-8 TopLink Database Session Architecture

A database session is the simplest session TopLink offers. It provides both client and server communications and supports only a single client and a single database connection. It is suitable for simple applications or 2-tier applications.

Note:

Oracle does not recommend using this session type in a 3-tier application because it is not as flexible or scalable as a server and client session. Oracle recommends that you use server sessions and client sessions (see Section 87.3, "Server and Client Sessions"). Applications that are built using database sessions may be difficult to migrate to a scalable architecture in the future.

A database session contains and manages the following information:

  • An instance of Project and DatabaseLogin, which store database login and configuration information

  • The JDBC connection and the database access

  • The descriptors for each of the application persistent classes

  • Identity maps that maintain object identity and act as a cache

For more information, see the following:

87.9 Remote Sessions

A remote session is a client-side session that communicates over RMI with a corresponding client session and server session on the server-side. Remote sessions handle object identity and marshalling and unmarshalling between client-side and server-side.

A remote session resides on the client rather than the TopLink server. The remote session does not replace the client session; rather, a remote session requires a client session to communicate with the server session.

Figure 87-9 Typical TopLink Server Session with Remote Session Architecture

The remote session provides a full TopLink session, complete with a session cache, on the client system. TopLink manages the remote session cache and enables client applications to execute operations on the server.

A remote session offers database access to clients that do not reside on the server. The remote session resides on the client and connects by way of RMI to a corresponding client session, which, in turn, connects to its server session on the server.

This section describes the following:

For more information, see Section 88.7, "Creating Remote Sessions".

87.9.1 Architectural Overview

As Figure 87-10 illustrates, the remote session model consists of the following layers:

  • The application layer–a client-side application talking to a remote session

  • The transport layer–a communication layer, RMI or RMI-IIOP

  • The server layer–a TopLink session communicating with a database

The request from the client application to the server travels down through the layers of a distributed system. A client that makes a request to the server session uses the remote session as a conduit to the server session. The client references the remote session, and the remote session forwards a request to the server session through the transport layer.

At run time, the remote session builds its knowledge base by reading descriptors and mappings from the server side as they are needed. These descriptors and mappings are lightweight, because not all information is passed on to the remote session. The information needed to traverse an object tree and to extract primary keys from the given object is passed with the mappings and descriptors.

Figure 87-10 An Architectural Overview of the Remote Session

Description of Figure 87-10 follows
Description of "Figure 87-10 An Architectural Overview of the Remote Session"

87.9.1.1 Application Layer

The application layer includes the application client and the remote session. The remote session is a subclass of Session and maintains all the public protocols of the session, giving the appearance of working with the corresponding client session.

The remote session maintains its own identity map and a project of all the descriptors read from the server. If the remote session can handle a request by itself, the request is not passed to the server. For example, a request for an object that is in the remote session cache is processed by the remote session. However, if the object is not in the remote session cache, the request passes to the server session.

87.9.1.2 Transport Layer

The transport layer is responsible for carrying the semantics of the invocation. It is a layer that hides all the protocol dependencies from the application and server layers.

The transport layer includes a remote connection that is an abstract entity, through which all requests to the server are forwarded. Each remote session maintains a single remote connection that marshals and unmarshals all requests and responses on the client side.

The remote session supports communications over RMI.

87.9.1.3 Server Layer

The server layer includes a remote session controller dispatcher and a TopLink sessions: Figure 87-10 illustrates a three-tier server and its client sessions. The remote session controller dispatcher is an interface between the session and transport layers: it marshals and unmarshals all responses and requests between the sessions on the server and their corresponding remote sessions on the client.

87.9.2 Remote Session Concepts

When using remote sessions, consider the following:

87.9.2.1 Securing Remote Session Access

The remote session represents a potential security risk because it requires you to register a remote session controller dispatcher as a service that anyone can access. This can expose the entire database to nonprivileged access.

To reduce this threat, run a server manager as a service to hold the remote session controller dispatcher. All the clients must then communicate through the server manager, which implements the security model for accessing the remote session controller dispatcher.

On the client side, the user requests the remote session controller dispatcher. The manager returns a remote session controller dispatcher only if the user has access rights according to the security model built into the server manager.

To access the system, the remote session controller dispatcher on the client side creates a remote connection, and acquires a remote session from the remote connection. The API for the remote session is the same as for the session, and there is no user-visible difference between working on a session or a remote session.

87.9.2.2 Queries

Read queries are publicly available on the client side, but queries that modify objects must be performed using the unit of work.

87.9.2.3 Refreshing

Calling refresh methods on the remote session causes database read operations, and may also cause cache updates if the data being refreshed is modified in the database. This can lead to poor performance.

To improve performance, configure refresh methods to run against the server session cache, by configuring the descriptor to always remotely refresh the objects in the cache on all queries. This technique ensures that all queries against the remote session refresh the objects from the server session cache, without the database access.

Cache hits on remote sessions still occur on read object queries based on the primary keys. To avoid this, disable the remote session cache hits on read object queries based on the primary key.

For more information, see Section 119.9, "Configuring Cache Refreshing".

87.9.2.4 Indirection

The remote session supports indirection (lazily loaded) objects. An indirection object is a value holder that can be invoked remotely on the client side. When invoked, the value holder first checks to see if the requested object exists on the remote session. If not, then the associated value holder on the server is instantiated to get the value that is then passed back to the client. Remote value holders are used automatically; the application's code does not change.

87.9.2.5 Cursored Streams

A remote session supports both cursored streams and scrollable cursors.

For more information, see Section 108.5.3, "Stream and Cursor Query Results".

87.9.2.6 Unit of Work

Use a unit of work acquired from the remote session to modify objects on the database. A unit of work acquired from the remote session offers the user the same functionality as a unit of work acquired from the client session or the database session.

87.10 Sessions and the Cache

Server, database, isolated, and historical sessions include an identity map that maintains object identity, and acts as a cache.

This section explains how the cache differs between the following sessions:

For more information, see Chapter 102, "Introduction to Cache".

87.10.1 Server and Database Session Cache

When a server or database session reads objects from the database, it instantiates them and stores them in its identity map (cache). When the application subsequently queries for the same object, TopLink returns the object in the cache, rather than read the object from the database again.

This cache plays an important role in the performance of your application.

In the case of a server session, all client sessions acquired from it share the server session's cache.

To define how the cache manages objects, specify a strategy for cache management in TopLink Workbench.

87.10.2 Isolated Session Cache

When an isolated session reads an object, whose descriptor is configured as isolated, that object is instantiated and stored in the isolated session's cache only–it is not stored in the parent server session's shared object cache. Objects in the isolated session's cache may reference objects in the parent server session's shared object cache, but objects in the parent server session's shared object cache can never reference objects in the isolated session's cache.

87.10.3 Historical Session Cache

When a historical session reads objects, it does so only from its static, read-only cache, which is populated with all objects as of a specified time.

87.11 Session API

The session API is defined by the following interfaces:

  • oracle.toplink.sessions.Session

  • oracle.toplink.sessions.DatabaseSession

  • oracle.toplink.sessions.UnitOfWork

  • oracle.toplink.threetier.Server

These APIs are used at run time to access objects and the data source. Always use the session public interfaces, not the corresponding implementation classes.

You should use the Session interface when reading and querying with any of client sessions, session brokers, isolated client sessions, historical sessions, remote sessions, and database sessions.

You should use the UnitOfWork interface for all units of work acquired from any type of session.

You should use the Server interface to configure and acquire a client session from a Server session.

The DatabaseSession interface can be used for a database session.Typically, you define server sessions, database sessions, and session broker sessions in a sessions.xml file and acquire them at run time using the SessionManager. You can also acquire a server session or database session from a Project. The only session that should ever be instantiated directly is the SessionBroker, and only when not using the SessionManager.

You acquire a client session from a server session.

You can also acquire a client session broker from a session broker composed of server sessions.

You acquire a unit of work from any session instance, client session broker, or session broker which contains DatabaseSession instances.

Example 87-5 illustrates the session interfaces that derive from oracle.toplink.sessions.Session interface.

Example 87-5 Session Interface Inheritance Hierarchy

oracle.toplink.sessions.Session
    oracle.toplink.sessions.DatabaseSession
        oracle.toplink.threetier.Server
    oracle.toplink.sessions.UnitOfWork