Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated"

m
m
Line 23: Line 23:
 
* use the Oracle Virtual Private Database (VPD) feature in your EclipseLink-enabled application (see [[#Isolated Client Sessions and Oracle Virtual Private Database (VPD)|Isolated Client Sessions and Oracle Virtual Private Database (VPD)]]).
 
* use the Oracle Virtual Private Database (VPD) feature in your EclipseLink-enabled application (see [[#Isolated Client Sessions and Oracle Virtual Private Database (VPD)|Isolated Client Sessions and Oracle Virtual Private Database (VPD)]]).
  
If in your EclipseLink project you configure all classes as isolated (see [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Isolation at the Project Level|Configuring Cache Isolation at the Project Level]]), or one or more classes as isolated (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Isolation at the Descriptor Level|Configuring Cache Isolation at the Descriptor Level]]), then all client sessions that you acquire from a parent server session will be isolated client sessions.
+
If in your EclipseLink project you configure all classes as isolated, or one or more classes as isolated, then all client sessions that you acquire from a parent server session will be isolated client sessions.
  
 
This figure illustrates the relationship between a parent server session's shared session cache and its child isolated client sessions.
 
This figure illustrates the relationship between a parent server session's shared session cache and its child isolated client sessions.
Line 46: Line 46:
 
|note=If an isolated session contains an exclusive connection, you must release the session when you are finished using it. We do 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.
 
|note=If an isolated session contains an exclusive connection, you must release the session when you are finished using it. We do 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.
 
}}
 
}}
 
 
For more information, see the following:
 
* [[#Isolated Client Session Limitations|Isolated Client Session Limitations]]
 
* [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How to Acquire an Isolated Client Session|How to Acquire an Isolated Client Session]]
 
* [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Configuring Exclusive Isolated Client Sessions for Virtual Private Database]]
 
  
  
Line 62: Line 56:
 
To use the Oracle Database VPD feature in your EclipseLink-enabled application, use isolated client sessions.
 
To use the Oracle Database VPD feature in your EclipseLink-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%20a%20Descriptor%20(ELUG)#Configuring Cache Isolation at the Descriptor Level|Configuring Cache Isolation at the Descriptor Level]]).
+
Any class that maps to a table that uses VPD must have the descriptor configured as isolated.
  
When you use isolated client sessions with VPD, you typically use exclusive connections (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How to Acquire a Client Session that Uses Exclusive Connections|How to Acquire a Client Session that Uses Exclusive Connections]]).
+
When you use isolated client sessions with VPD, you typically use exclusive connections.
  
 
To support VPD, you are responsible for implementing session event handlers that the EclipseLink runtime invokes during the isolated client session life cycle (see [[#Isolated Client Session Life Cycle|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|VPD with Oracle Database Proxy Authentication]] and [[#VPD Without Oracle Database Proxy Authentication|VPD Without Oracle Database Proxy Authentication]]).
 
To support VPD, you are responsible for implementing session event handlers that the EclipseLink runtime invokes during the isolated client session life cycle (see [[#Isolated Client Session Life Cycle|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|VPD with Oracle Database Proxy Authentication]] and [[#VPD Without Oracle Database Proxy Authentication|VPD Without Oracle Database Proxy Authentication]]).
 
For information, see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Configuring Exclusive Isolated Client Sessions for Virtual Private Database]].
 
 
  
 
====VPD with Oracle Database Proxy Authentication====
 
====VPD with Oracle Database Proxy Authentication====
If you are using Oracle Database proxy authentication ( [[Introduction%20to%20Data%20Access%20(ELUG)#Oracle Database Proxy Authentication|Oracle Database Proxy Authentication]]), you must implement a session event handler for the following session events:
+
If you are using Oracle Database proxy authentication, you must implement a session event handler for the following session events:
* <tt>noRowsModifiedSessionEvent</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using NoRowsModifiedSessionEvent Event Handler|Using NoRowsModifiedSessionEvent Event Handler]])
+
* <tt>noRowsModifiedSessionEvent</tt>
  
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 [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PostAcquireExclusiveConnection Event Handler|Using PostAcquireExclusiveConnection Event Handler]] and [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PreReleaseExclusiveConnection Event Handler|Using PreReleaseExclusiveConnection Event Handler]]), the database performs the required setup in an after login trigger using the proxy <tt>session_user</tt>.
+
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, the database performs the required setup in an after login trigger using the proxy <tt>session_user</tt>.
  
  
 
====VPD Without Oracle Database Proxy Authentication====
 
====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:
 
If you are not using Oracle Database proxy authentication, you must implement session event handlers for the following session events:
* <tt>postAcquireExclusiveConnection</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PostAcquireExclusiveConnection Event Handler|Using PostAcquireExclusiveConnection Event Handler]]): used to perform VPD setup at the time EclipseLink allocates a dedicated connection to an isolated session and before the isolated session user uses the connection to interact with the database.
+
* <tt>postAcquireExclusiveConnection</tt>: used to perform VPD setup at the time EclipseLink allocates a dedicated connection to an isolated session and before the isolated session user uses the connection to interact with the database.
* <tt>preReleaseExclusiveConnection</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PreReleaseExclusiveConnection Event Handler|Using 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.
+
* <tt>preReleaseExclusiveConnection</tt>: used to perform VPD cleanup at the time the isolated session is released and after the user is finished interacting with the database.
* <tt>noRowsModifiedSessionEvent</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using NoRowsModifiedSessionEvent Event Handler|Using NoRowsModifiedSessionEvent Event Handler]])
+
* <tt>noRowsModifiedSessionEvent</tt>
  
In your implementation of these handlers, you obtain the required user credentials from the <tt>ConnectionPolicy</tt> associated with the session (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How to Acquire a Client Session that Uses Connection Properties|How to Acquire a Client Session that Uses Connection Properties]]).
+
In your implementation of these handlers, you obtain the required user credentials from the <tt>ConnectionPolicy</tt> associated with the session.
  
  
Line 98: Line 89:
 
<li> Configure your project and session:
 
<li> Configure your project and session:
 
<ul>
 
<ul>
  <li> Designate descriptors as isolated (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Isolation at the Descriptor Level|Configuring Cache Isolation at the Descriptor Level]]).</li>
+
  <li> Designate descriptors as isolated.</li>
  <li> Configure your server session to allocate exclusive connections (see [[Configuring%20a%20Session%20(ELUG)#Configuring Connection Policy|onfiguring Connection Policy]]).</li>
+
  <li> Configure your server session to allocate exclusive connections.</li>
 
  <li> Implement session event listeners for the required connection events:
 
  <li> Implement session event listeners for the required connection events:
<ul><li>If you are using [[Introduction%20to%20Data%20Access%20(ELUG)#Oracle Database Proxy Authentication|Oracle Database proxy authentication]], see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using NoRowsModifiedSessionEvent Event Handler|Using NoRowsModifiedSessionEvent Event Handler]].</li>
 
<li> If you are not using Oracle Database proxy authentication, see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PostAcquireExclusiveConnection Event Handler|Using PostAcquireExclusiveConnection Event Handler]], [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PreReleaseExclusiveConnection Event Handler|Using PreReleaseExclusiveConnection Event Handler]], and [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using NoRowsModifiedSessionEvent Event Handler|Using NoRowsModifiedSessionEvent Event Handler]]<br><table class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"><tr><td>'''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%20a%20Session%20(ELUG)#Configuring Session Event Listeners|Configuring Session Event Listeners]]</td></tr></table></li></ul></li>
 
<li>Implement exception handlers for the appropriate exceptions (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using ValidationException Handler|Using ValidationException Handler]]).</li>
 
</ul>
 
 
<li> Acquire an isolated session:
 
<li> Acquire an isolated session:
 
<ul>
 
<ul>
<li> If you are using [[Introduction%20to%20Data%20Access%20(ELUG)#Oracle Database Proxy Authentication|Oracle Database proxy authentication]]:
+
<li> If you are using Oracle Database proxy authentication:
 
<br>
 
<br>
 
<div class="pre">
 
<div class="pre">
Line 121: Line 108:
 
</div>
 
</div>
 
<br>
 
<br>
Set the user's credentials as appropriate properties on <tt>myConnectionPolicy</tt>. Because you configured one or more descriptors as isolated, <tt>myIsolatedClientSession</tt> is an isolated session with an exclusive connection.<br>The EclipseLink runtime raises a <tt>SessionEvent.PostAcquireExclusiveConnection</tt> event handled by your <tt>SessionEventListener</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHJFGFD|Using PostAcquireExclusiveConnection Event Handler]]).</li>
+
Set the user's credentials as appropriate properties on <tt>myConnectionPolicy</tt>. Because you configured one or more descriptors as isolated, <tt>myIsolatedClientSession</tt> is an isolated session with an exclusive connection.<br>The EclipseLink runtime raises a <tt>SessionEvent.PostAcquireExclusiveConnection</tt> event handled by your <tt>SessionEventListener</tt>.</li>
 
</ul>
 
</ul>
 
</li>
 
</li>
<li> Use <tt>myIsolatedClientSession</tt> to interact with the database.<br>If the EclipseLink runtime raises a <tt>SessionEvent.NoRowsModified</tt> event, it is handled by your <tt>SessionEventListener</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHHJCDG|Using NoRowsModifiedSessionEvent Event Handler]]).</li>
+
<li> Use <tt>myIsolatedClientSession</tt> to interact with the database.<br>If the EclipseLink runtime raises a <tt>SessionEvent.NoRowsModified</tt> event, it is handled by your <tt>SessionEventListener</tt>.</li>
 
<li> When you are finished using <tt>myIsolatedClientSession</tt>, release the isolated session:<br>
 
<li> When you are finished using <tt>myIsolatedClientSession</tt>, release the isolated session:<br>
 
<div class="pre">
 
<div class="pre">
 
  myIsolatedClientSession.release();
 
  myIsolatedClientSession.release();
 
</div>
 
</div>
<br>The EclipseLink runtime prepares to destroy the isolated cache and to close the exclusive connection associated with this isolated session.<br>The EclipseLink runtime raises a <tt>SessionEvent.PreReleaseExclusiveConnection</tt> event handled by your <tt>SessionEventListener</tt> (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#CIHEEIEF|Using PreReleaseExclusiveConnection Event Handler]]).</li>
+
<br>The EclipseLink runtime prepares to destroy the isolated cache and to close the exclusive connection associated with this isolated session.<br>The EclipseLink runtime raises a <tt>SessionEvent.PreReleaseExclusiveConnection</tt> event handled by your <tt>SessionEventListener</tt>.</li>
 
<li> Repeat steps #3 to #5 (as required) until the application exits.</li>
 
<li> Repeat steps #3 to #5 (as required) until the application exits.</li>
 
</ol>
 
</ol>

Revision as of 13:02, 4 May 2011


link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug example icon.png Examples


Shared and Isolated Cache

Isolated Cache

This caching technique always goes to the database for the initial read operation of an object whose descriptor is configured as isolated. By avoiding the shared session cache, you do not need to use the more complicated descriptor and query APIs to disable cache hits or always refresh.

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.

Use isolated client sessions to do the following:

If in your EclipseLink project you configure all classes as isolated, or one or more classes as isolated, then all client sessions that you acquire from a parent server session will be isolated client sessions.

This figure illustrates the relationship between a parent server session's shared session cache and its child isolated client sessions.

Isolated Client Sessions

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.

Elug note icon.png

Note: You cannot define mappings from shared classes to isolated classes.


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. Using an exclusive connection provides improved user-based security for reads and writes. Named queries can also use an exclusive connection).

Elug note icon.png

Note: If an isolated session contains an exclusive connection, you must release the session when you are finished using it. We do 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.


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

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


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

Any class that maps to a table that uses VPD must have the descriptor configured as isolated.

When you use isolated client sessions with VPD, you typically use exclusive connections.

To support VPD, you are responsible for implementing session event handlers that the EclipseLink 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).

VPD with Oracle Database Proxy Authentication

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

  • noRowsModifiedSessionEvent

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, 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: used to perform VPD setup at the time EclipseLink allocates a dedicated connection to an isolated session and before the isolated session user uses the connection to interact with the database.
  • preReleaseExclusiveConnection: used to perform VPD cleanup at the time the isolated session is released and after the user is finished interacting with the database.
  • noRowsModifiedSessionEvent

In your implementation of these handlers, you obtain the required user credentials from the ConnectionPolicy associated with the session.


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:
    • Designate descriptors as isolated.
    • Configure your server session to allocate exclusive connections.
    • Implement session event listeners for the required connection events:
    • Acquire an isolated session:
      • If you are using 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 EclipseLink runtime raises a SessionEvent.PostAcquireExclusiveConnection event handled by your SessionEventListener.
    • Use myIsolatedClientSession to interact with the database.
      If the EclipseLink runtime raises a SessionEvent.NoRowsModified event, it is handled by your SessionEventListener.
    • When you are finished using myIsolatedClientSession, release the isolated session:
      myIsolatedClientSession.release();
      

      The EclipseLink runtime prepares to destroy the isolated cache and to close the exclusive connection associated with this isolated session.
      The EclipseLink runtime raises a SessionEvent.PreReleaseExclusiveConnection event handled by your SessionEventListener.
    • Repeat steps #3 to #5 (as required) until the application exits.
    • </ol>

      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 EclipseLink 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 EclipseLink 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 EclipseLink 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

      We recommend that you do not configure a sequencing object or sequence table using VPD security. EclipseLink does not access sequencing objects using the isolated session's dedicated connection, and so VPD restricted sequence values are not available to the isolated session. Sequence objects not using VPD security are fine.

      Transactions and JTA

      We recommend 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.


      Eclipselink-logo.gif
      Version: 2.2.0 DRAFT
      Other versions...