Acquiring a Client Session

Before you can acquire a client session, you must first use the session manager to acquire a server session or a session broker that contains server sessions (see "Acquiring a Session from the Session Manager").

Table 78-1 summarizes the methods used to acquire various types of client sessions from a server session and a session broker session that contains server sessions.

Table 78-1 Method Used to Acquire a Client Session

Client Session	Server Session Method	Session Broker Session Method
Regular or Isolated	acquireClientSession()	acquireClientSessionBroker()
Regular or Isolated	acquireClientSession(ConnectionPolicy)	not applicable
Historical	acquireHistoricalSession(AsOfClause)	not applicable

The acquireClientSession method returns a session of type ClientSession.

The acquireClientSessionBroker method returns a session of type SessionBroker.

In both cases, you should cast the returned object to type Session and use it as you would any other session.

For more information, see the following:

• "Acquiring an Isolated Client Session"

• "Acquiring a Historical Client Session"

• "Acquiring a Client Session That Uses Exclusive Connections"

• "Acquiring a Client Session that Uses Connection Properties"

• "Acquiring a Client Session that Uses a Named Connection Pool"

• "Acquiring a Client Session that Does Not Use Lazy Connection Allocation"

Acquiring an Isolated Client Session

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

Using a ConnectionPolicy, you can acquire an isolated client session that uses exclusive connections (see "Acquiring a Client Session That Uses Exclusive Connections"). This isolated client session is configured with connection properties for use with the Oracle Virtual Private Database (VPD) feature, or both (see "Acquiring a Client Session that Uses Connection Properties").

For more information about VPD, see "Isolated Client Sessions and Oracle Virtual Private Database (VPD)".

Acquiring a Historical Client Session

After you configure TopLink to access historical data (see "Historical Client Session Configuration Overview"), you can query historical data using any session type.

When you query historical data using a regular client session or database session, you must always set ObjectLevelReadQuery method maintainCache to false in order to prevent old (historical) data from corrupting the session cache. However, you can query both current and historical object versions.

As a convenience, TopLink provides a historical session to simplify this process. When you query historical data using a historical session, you do not need to set ObjectLevelReadQuery method maintainCache to false. However, you can query objects only as of the specified time.

Before you can acquire a historical client session, you must first use the session manager to acquire a server session.

To acquire a historical client session, use Server method acquireHistoricalSession passing in an AsOfClause.

The AsOfClause specifies a point in time that applies to all queries and expressions subsequently executed on the historical session. The historical session's cache is a read-only snapshot of object versions as of the specified time. Its cache is isolated from its parent server session's shared object cache.

Acquiring a Client Session That Uses Exclusive Connections

Example 78-9 illustrates how to configure a ConnectionPolicy and use it to acquire a client session that uses exclusive connections.

Example 78-9 Acquiring a Client Session that Uses Connection Properties

ConnectionPolicy connectionPolicy = new ConnectionPolicy();
// Use an exclusive connection for the session
connectionPolicy.setShouldUseExclusiveConnection(true);

Session clientSession = server.acquireClientSession(connectionPolicy);
// By default, an exclusive connection will be acquired lazily

An exclusive connection is not allocated from a shared connection pool. The connection is dedicated to the client session that acquires it.

Note: If you configure a client session to use an exclusive connection, you must release the session when you are finished using it. Relying on the finalizer to release the connection when the session is garbage collected may cause errors when dealing with JTA transactions.

A named query can also use an exclusive connection (see "Configuring Named Query Advanced Options").

For more information, see the following:

• "Acquiring a Client Session that Does Not Use Lazy Connection Allocation"

• "Configuring Connection Policy".

Acquiring a Client Session that Uses Connection Properties

Example 78-10 illustrates how to configure a ConnectionPolicy and use it to acquire a client session that uses connection properties. In this example, the properties are used by the Oracle VPD feature (see "Isolated Client Sessions and Oracle Virtual Private Database (VPD)"). You can use connection properties for other application purposes.

Example 78-10 Acquiring an Isolated Session Using Connection Properties

ConnectionPolicy connectionPolicy = new ConnectionPolicy();
// Set VPD specific properties to be used in the events
connectionPolicy.setProperty("userLevel", new Integer(5));

Session clientSession = server.acquireClientSession(connectionPolicy);

For more information, see "Configuring Connection Policy".

Acquiring a Client Session that Uses a Named Connection Pool

Before you can acquire a client session that uses a named connection pool, you must configure your session with a named connection pool. For more information on named connection pools, see "Application-Specific Connection Pools". For more information on creating a named connection pool, see "Internal Connection Pool Creation Overview".

To acquire a client session that uses a named connection pool, use Server method acquireClientSession, passing in a ConnectionPolicy configured with the desired connection pool. The acquired ClientSession uses connections from the specified pool for writes (reads still go through the Server read connection pool).

Example 78-11 illustrates how to configure a ConnectionPolicy to specify a named connection pool named myConnectionPool.

Example 78-11 Acquiring a Client Session that Uses a Named Connection Pool

// Assuming you created a connection pool named "myConnectionPool"
Session clientSession = server.acquireClientSession(
    new ConnectionPolicy("myConnectionPool")
);

For more information, see "Configuring Connection Policy".

Acquiring a Client Session that Does Not Use Lazy Connection Allocation

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.

Example 78-12 illustrates how to configure a ConnectionPolicy to specify that lazy connection allocation is not used.

Example 78-12 Acquiring a Client Session that Does Not Use Lazy Connections

ConnectionPolicy connectionPolicy = new ConnectionPolicy();
connectionPolicy.setIsLazy(false);
Session clientSession = server.acquireClientSession(connectionPolicy);

For more information, see "Configuring Connection Policy".