Jump to: navigation, search

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

(Shared, Isolated and Protected Cache)
Line 6: Line 6:
  
 
The cache isolation levels are:
 
The cache isolation levels are:
 
+
* Isolated - entities are only cached in the persistence context, not in the persistence unit
 +
* Shared - entities are cached both in the persistence context and persistence unit, read-only entities are shared and only cached in the persistence unit
 +
* Protected - entities are cached both in the persistence context and persistence unit, read-only entities are isolated and cached in the persistence unit and persistence context
  
 
==Isolated Cache==
 
==Isolated Cache==
The isolated cache (L1) is the cache stored in the persistence context.  It is a transactional or user session based cache.  Setting the cache isolation to isolated disables the shared cache.  With an isolated cache all queries and find operations will access the database unless the object has already been read into the persistence context and refreshing is not used.
+
The isolated cache (L1) is the cache stored in the persistence context.  It is a transactional or user session based cache.  Setting the cache isolation to isolated for an entity disables its shared cache.  With an isolated cache all queries and find operations will access the database unless the object has already been read into the persistence context and refreshing is not used.
  
 
Use a isolated cache to do the following:
 
Use a isolated cache to do the following:
 
* avoid caching highly volatile data in the shared cache;
 
* avoid caching highly volatile data in the shared cache;
 
* achieve serializable transaction isolation;
 
* achieve serializable transaction isolation;
* use the Oracle Virtual Private Database (VPD) feature in your EclipseLink-enabled application (see [[#Oracle Virtual Private Database (VPD)|Oracle Virtual Private Database (VPD)]]).
+
* use the Oracle Virtual Private Database (VPD) feature (see [[#Oracle Virtual Private Database (VPD)|Oracle Virtual Private Database (VPD)]]).
  
 
Each persistence context owns an initially empty isolated cache.  The persistence context's isolated cache is discarded when the persistence context is closed, or the <code>EntityManager.clear()</code> operation is used.
 
Each persistence context owns an initially empty isolated cache.  The persistence context's isolated cache is discarded when the persistence context is closed, or the <code>EntityManager.clear()</code> operation is used.
Line 20: Line 22:
 
When you use an <code>EntityManager</code>  to read an isolated entity, the <code>EntityManager</code> reads the entity directly from the database and stores it in the persistence context's isolated cache. When you use an <code>EntityManager</code> to read a shared entity, the <code>EntityManager</code> reads the shared entity from the persistence unit's shared cache. If the shared entity is not in the persistence unit's shared cache, it will read it from the database and store a copy in the persistence unit's shared cache, and another copy in the persistence context's isolated cache.
 
When you use an <code>EntityManager</code>  to read an isolated entity, the <code>EntityManager</code> reads the entity directly from the database and stores it in the persistence context's isolated cache. When you use an <code>EntityManager</code> to read a shared entity, the <code>EntityManager</code> reads the shared entity from the persistence unit's shared cache. If the shared entity is not in the persistence unit's shared cache, it will read it from the database and store a copy in the persistence unit's shared cache, and another copy in the persistence context's isolated cache.
  
The persistence context can access the data source using a connection pool or an exclusive connection. To use an exclusive connection, acquire the <code>EntityManager</code> using a <tt>ConnectionPolicy</tt>. Using an exclusive connection provides improved user-based security for reads and writes. Specific queries can also use an exclusive connection.
+
The persistence context can access the data source using a connection pool or an exclusive connection. The persistence unit property <code>"eclipselink.jdbc.exclusive-connection.mode"</code> can be used to use an exclusive connection. Using an exclusive connection provides improved user-based security for reads and writes. Specific queries can also be configured to use the persistence context's exclusive connection.
 
{{EclipseLink_Note
 
{{EclipseLink_Note
 
|note=If an <code>EntityManager</code> contains an exclusive connection, you must close the <code>EntityManager</code> when you are finished using it. We do not recommend relying on the finalizer to release the connection when the <code>EntityManager</code> is garbage-collected. If you are using a managed persistence context, then you do not need to close it.
 
|note=If an <code>EntityManager</code> contains an exclusive connection, you must close the <code>EntityManager</code> when you are finished using it. We do not recommend relying on the finalizer to release the connection when the <code>EntityManager</code> is garbage-collected. If you are using a managed persistence context, then you do not need to close it.
Line 27: Line 29:
  
 
===Oracle Virtual Private Database (VPD)===
 
===Oracle Virtual Private Database (VPD)===
Oracle9''i'' 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:
+
Oracle Database Server 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:
  
 
<tt>http://www.oracle.com/technology/deploy/security/index.html</tt>.
 
<tt>http://www.oracle.com/technology/deploy/security/index.html</tt>.
  
  
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, an isolated cache should be used.
  
Any class that maps to a table that uses VPD must have the descriptor configured as isolated.
+
Any entity that maps to a table that uses VPD should have the descriptor configured as isolated.
  
When you use isolated client sessions with VPD, you typically use exclusive connections.
+
When you use VPD, you typically should also 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 persistence context's 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]]).
  
 
====VPD with 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:
+
If you are using Oracle Database proxy authentication, you should implement a session event handler for the following session events:
 
* <tt>noRowsModifiedSessionEvent</tt>
 
* <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, 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 session event handlers to execute SQL, the database performs the required setup in an after login trigger using the proxy <tt>session_user</tt>.
  
  
Line 53: Line 55:
 
* <tt>noRowsModifiedSessionEvent</tt>
 
* <tt>noRowsModifiedSessionEvent</tt>
  
In your implementation of these handlers, you obtain the required user credentials from the <tt>ConnectionPolicy</tt> associated with the session.
+
In your implementation of these handlers, you can obtain the required user credentials from the associated session's 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:
+
<ol>
+
<li>Prepare VPD configuration in the database.</li>
+
<li> Configure your project and session:
+
<ul>
+
<li> Designate descriptors as isolated.</li>
+
<li> Configure your server session to allocate exclusive connections.</li>
+
<li> Implement session event listeners for the required connection events:
+
<li> Acquire an isolated session:
+
<ul>
+
<li> If you are using Oracle Database proxy authentication:
+
<br>
+
<div class="pre">
+
Session myIsolatedClientSession = <br>server.acquireClientSession();
+
</div>
+
<br>Because you configured one or more descriptors as isolated, <tt>myIsolatedClientSession</tt> is an isolated session with an exclusive connection.</li>
+
<li> If you are not using Oracle Database proxy authentication:
+
<br>
+
<div class="pre">
+
ConnectionPolicy myConnPolicy = (ConnectionPolicy)server.getDefaultConnectionPolicy().clone();
+
myConnectionPolicy.setProperty("credentials", myUserCredentials);
+
Session myIsolatedClientSession = server.acquireClientSession(myConnectionPolicy);
+
</div>
+
<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>.</li>
+
</ul>
+
</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>
+
<div class="pre">
+
myIsolatedClientSession.release();
+
</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>.</li>
+
<li> Repeat steps #3 to #5 (as required) until the application exits.</li>
+
</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|Mapping]]
+
* [[#Inheritance|Inheritance]]
+
* [[#Caching and Cache Coordination|Caching and Cache Coordination]]
+
* [[#Sequencing|Sequencing]]
+
* [[#Transactions and JTA|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 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.
+
  
  

Revision as of 12:02, 9 May 2012


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


Shared, Isolated and Protected Cache

EclipseLink defines three cache isolation levels. The cache isolation level defines how caching for an entity is performed by the persistence unit and the persistence context.

The cache isolation levels are:

  • Isolated - entities are only cached in the persistence context, not in the persistence unit
  • Shared - entities are cached both in the persistence context and persistence unit, read-only entities are shared and only cached in the persistence unit
  • Protected - entities are cached both in the persistence context and persistence unit, read-only entities are isolated and cached in the persistence unit and persistence context

Isolated Cache

The isolated cache (L1) is the cache stored in the persistence context. It is a transactional or user session based cache. Setting the cache isolation to isolated for an entity disables its shared cache. With an isolated cache all queries and find operations will access the database unless the object has already been read into the persistence context and refreshing is not used.

Use a isolated cache to do the following:

  • avoid caching highly volatile data in the shared cache;
  • achieve serializable transaction isolation;
  • use the Oracle Virtual Private Database (VPD) feature (see Oracle Virtual Private Database (VPD)).

Each persistence context owns an initially empty isolated cache. The persistence context's isolated cache is discarded when the persistence context is closed, or the EntityManager.clear() operation is used.

When you use an EntityManager to read an isolated entity, the EntityManager reads the entity directly from the database and stores it in the persistence context's isolated cache. When you use an EntityManager to read a shared entity, the EntityManager reads the shared entity from the persistence unit's shared cache. If the shared entity is not in the persistence unit's shared cache, it will read it from the database and store a copy in the persistence unit's shared cache, and another copy in the persistence context's isolated cache.

The persistence context can access the data source using a connection pool or an exclusive connection. The persistence unit property "eclipselink.jdbc.exclusive-connection.mode" can be used to use an exclusive connection. Using an exclusive connection provides improved user-based security for reads and writes. Specific queries can also be configured to use the persistence context's exclusive connection.

Elug note icon.png

Note: If an EntityManager contains an exclusive connection, you must close the EntityManager when you are finished using it. We do not recommend relying on the finalizer to release the connection when the EntityManager is garbage-collected. If you are using a managed persistence context, then you do not need to close it.


Oracle Virtual Private Database (VPD)

Oracle Database Server 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, an isolated cache should be used.

Any entity that maps to a table that uses VPD should have the descriptor configured as isolated.

When you use VPD, you typically should also use exclusive connections.

To support VPD, you are responsible for implementing session event handlers that the EclipseLink runtime invokes during the persistence context's 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 should 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 session event handlers to 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 can obtain the required user credentials from the associated session's properties.


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