Configuring Connection Policy

Using a connection policy, you can control how a TopLink session acquires and uses read and write connections, including the following:

• Exclusive Write Connections

• Lazy Connection Acquisition

Table 77-15 summarizes which sessions support connection policy configuration.

Table 77-16 Session Support for Connection Policy

Session	Using TopLink Workbench	Using Java
Server and Client Sessions
Session Broker and Client Sessions
Database Sessions

Exclusive Write Connections

An exclusive connection is one that TopLink allocates specifically to a given session and one that is never used by any other session.

By default, TopLink acquires write connections for a client session from a shared write connection pools. In this case, different sessions may reuse connections.

If you are using isolated client sessions (see "Isolated Client Sessions"), Oracle recommends that you use exclusive write connections. In this case, if you are using internal connection pools (see "Internal Connection Pools"), you can configure TopLink to acquire an exclusive connection from the write connection pool and use it for both writing and reading isolated data. However, TopLink still acquires a shared connection from the read connection pool for reading nonisolated data, unless you configure the read connection pool to allocate exclusive connections (see "Configuring Exclusive Read Connections").

You can also configure exclusive connections on a client-session-by-client-session basis (see "Acquiring a Client Session That Uses Exclusive Connections") and for named queries (see "Configuring Named Query Advanced Options").

Note: If any client session contains an exclusive connection, you must release the session (see "Logging Out of a 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.

Lazy Connection Acquisition

By default, TopLink acquires write and read connections lazily, when you perform the first read or write operation with your client session.

Alternatively, you can configure TopLink to acquire connections at the time you acquire a client session.

You can also configure lazy connection acquisition on a client-session-by-client-session basis (see "Acquiring a Client Session that Does Not Use Lazy Connection Allocation").

Using TopLink Workbench

To specify the connection policy in a session, use this procedure:

1. Select a session in the Navigator. Its properties appear in the Editor.

2. Click the Connection Policy tab. The Connection Policy tab appears.

   Figure 77-9 Connection Policy Tab

   
   Description of "Figure 77-9 Connection Policy Tab"
   
   

Unselect Acquire Exclusive Connection (default), if you want TopLink to acquire connections for a client session from shared write and read connection pools. In this case, different sessions may reuse connections and may use read connections concurrently.

Select Acquire Exclusive Connection if you are using internal connection pools (see "Internal Connection Pools"), and you want TopLink to acquire an exclusive connection from the write connection pool and use it for both writing and reading isolated data. However, TopLink still acquires a shared connection from the read connection pool for reading nonisolated data unless you configure the read connection pool to allocate exclusive connections (see "Configuring Exclusive Read Connections"). If you are using isolated client sessions (see "Isolated Client Sessions"), Oracle recommends that you configure the parent server session to use exclusive write connections.

Select Acquire Connections Lazily (default) to configure TopLink to acquire write and read connections when you perform the first read or write operation with your client session.

Unselect Acquire Connections Lazily to configure TopLink to acquire write and read connections at the time you acquire a client session.

Using Java

To configure whether or not an exclusive connection is allocated to a particular isolated session, use ConnectionPolicy method setShouldUseExclusiveConnection.

To define a map of properties used to support an isolated session, use the following ConnectionPolicy methods:

• setProperty(Object key, Object value): Adds the property value to the Map under key, overwriting the existing value if key already exists in the Map.

• Object getProperty(Object key): Returns the value associated with key as an Object.

• boolean hasProperties: Returns true if one or more properties exist in the Map; otherwise returns false.

The TopLink runtime passes this Map into SessionEvent events PostAcquireExclusiveConnection and PreReleaseExclusiveConnection so that your implementation can make the appropriate PL/SQL calls to the underlying database platform (see "PostAcquireExclusiveConnection Event Handler" and "PreReleaseExclusiveConnection Event Handler").

To configure the session to use a named connection pool, use the ConnectionPool constructor that takes a String connection pool name as an argument:

Session clientSession = server.acquireClientSession(
    new ConnectionPolicy("myConnectionPool")
);