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

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

Figure 75-6 Isolated Client Sessions

Description of "Figure 75-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 2.0, you also cannot define references from isolated EJB to shared EBJ.

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 "Acquiring 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 "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. Relying on the finalizer to release the connection when the session is garbage collected may cause errors when dealing with Java Transaction API (JTA) transactions.

Use isolated client sessions to do the following:

avoid caching highly volatile data in the shared session cache
achieve serializable transaction isolation (see "Isolated Client Session Cache")
use the Oracle Virtual Private Database (VPD) feature in your TopLink-enabled application (see "Isolated Client Sessions and Oracle Virtual Private Database (VPD)")

For more information, see the following:

Isolated Client Sessions and Oracle Virtual Private Database (VPD)

Oracle9i Database Server (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:

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

To use the 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 "Configuring Cache Isolation at the Descriptor Level").

When you use isolated client sessions with VPD, you typically use exclusive connections (see "Acquiring 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 "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 "VPD With Oracle Database Proxy Authentication" and "VPD Without Oracle Database Proxy Authentication").

For information, see "Configuring Isolated Client Sessions".

VPD With Oracle Database Proxy Authentication

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

noRowsModifiedSessionEvent (see "NoRowsModifiedSessionEvent Event Handler")

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 "PostAcquireExclusiveConnection Event Handler" and "PreReleaseExclusiveConnection Event Handler"), the database performs the required setup in an after login trigger using the proxy session_user.

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:

postAcquireExclusiveConnection (see "PostAcquireExclusiveConnection Event Handler"): used to perform VPD setup at the time TopLink allocates a dedicated connection to an isolated session and before the isolated session user uses the connection to interact with the database.
preReleaseExclusiveConnection (see "PreReleaseExclusiveConnection Event Handler"): used to perform VPD cleanup at the time the isolated session is released and after the user is finished interacting with the database.
noRowsModifiedSessionEvent (see "NoRowsModifiedSessionEvent Event Handler")

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

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:

Prepare VPD configuration in the database.

Configure your project and session:

Designate descriptors as isolated (see "Configuring Cache Isolation at the Descriptor Level").
Configure your server session to allocate exclusive connections (see "Configuring Connection Policy").

Implement session event listeners for the required connection events

If you are using Oracle Database proxy authentication (see "Oracle Database Proxy Authentication"), see "NoRowsModifiedSessionEvent Event Handler".
If you are not using Oracle Database proxy authentication, see "PostAcquireExclusiveConnection Event Handler", "PreReleaseExclusiveConnection Event Handler", and "NoRowsModifiedSessionEvent Event Handler"

Note:

You must add these session event listeners to the server session from which you acquire your isolated client session. You cannot add them to the isolated client session itself. For more information, see "Configuring Session Event Listeners"

Implement exception handlers for the appropriate exceptions (see "ValidationException Handler").

Acquire an isolated session:
- If you are using Oracle Database proxy authentication (see "Oracle Database Proxy Authentication"):
```
ClientSession 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 = Server.getDefaultConnectionPolicy();
myConnectionPolicy.setProperty("credentials", myUserCredentials);
ClientSession 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 "PostAcquireExclusiveConnection Event Handler").
Use myIsolatedClientSession to interact with the database.

If the TopLink runtime raises a SessionEvent.NoRowsModified event, it is handled by your SessionEventListener (see "NoRowsModifiedSessionEvent Event Handler").
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 "PreReleaseExclusiveConnection Event Handler").
Repeat steps 3 to 5 (as required) until the application exits.

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
Inheritance
Caching and Cache Coordination
Sequencing
CMP
Transactions and JTA

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 2.0, 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.

When using an isolated session with JTA, once a dedicated connection has been allocated, that connection continues to provide dedicated access until the transaction has been completed, and as such, your application must restrict access to that connection.Oracle recommends that you avoid using UnitOfWork method commitAndResume when using an isolated session. That is, avoid executing queries in the same transaction after committing changes to the database. Otherwise, uncommitted data may be read into the shared cache under some circumstances, such as a long-standing transaction with multiple units of work within it.

When accessing a JTA datasource outside a JTA transaction the returned connection is not in auto-commit mode. To trap the getConnetion event, use of the of the following methods:

Handle the postAcquireConnection event:

public void postAcquireConnection(SessionEvent event) {
  boolean isInGlobalTransaction = 
  ((oracle.toplink.transactions.AbstractTransactionController)
  event.getSession().getExternalTransactionController()).getTransactionStatus()
  ==
  Status.STATUS_ACTIVE;
  if(!isInGlobalTransaction) {
    DatasourceAccessor dsAccessor = (DatasourceAccessor)event.getResult();
    Login login = dsAccessor.getLogin();
    login.setProperty("setAutoCommit", "true");
  }
}

Extend the JNDIConnectior class:

public class MyJNDIConnector extends JNDIConnector {
  public Connection connect(Properties properties) {
    Connection = super.connect(properties);
    if(properties.getProperty("setAutoCommit") != null) {
      connection.setAutoCommit(true);
    }
    return connection;
  }
}