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 75-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 75-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 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 can be configured with connection properties for use with the Oracle Virtual Private Database (VPD) feature (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 Client Session That Uses Exclusive Connections

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

Example 75-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 allocated from a shared connection pool. The connection is dedicated to the client session that acquires it.

Note:

Typically, the life cycle of a client session is the duration of a server request. However, if you are using JTA, it is the life cycle of a JTA transaction.

You cannot hold the client session across the JTA transaction boundaries. If you are not using a unit of work in your transaction and you are configuring a client session to use an exclusive connection (see Chapter 77, "Configuring Exclusive Isolated Client Sessions for Virtual Private Database"), you must explicitly acquire and release the session when you are finished using it. Although client sessions have a finalizer that would release the session when it is garbage-collected, you must not rely on the finalizer and release the exclusive client session (or a non-lazy session) in the application to release the data source connection. Note that the requirement to release the session in not JTA-specific.

If you are using a unit of work (see Chapter 99, "Using Advanced Unit of Work API"), you do not have to worry about releasing its client session as the unit of work always automatically releases it at the end of the JTA transaction.

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 75-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 75-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 75-11 illustrates how to configure a ConnectionPolicy to specify a named connection pool named myConnectionPool.

Example 75-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 75-12 illustrates how to configure a ConnectionPolicy to specify that lazy connection allocation is not used.

Example 75-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".