EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

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 read a read-only entity it is still stored in the isolated cache, but is not change tracked.

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.

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.

Shared Cache

The shared cache (L2) is the cache stored in the persistence unit. It is a shared object cache for the entire persistence unit. Setting the cache isolation to SHARED for an entity enables its shared cache. With a shared cache queries and find operations will resolve against the shared cache unless refreshing is used.

Use a shared cache to do the following:

• improve performance by avoiding database access when finding or querying entities by Id or index;
• improve performance by avoiding database access when accessing entity's relationships;
• preserve object identity across persistence contexts for read-only entities.

When you use an EntityManager to find a shared entity, the EntityManager first checks the persistence unit's shared cache. If the 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. Any query not by Id, and not by an indexed attribute will first access the database. For each query result row, if the object is already in the shared cache, the shared object (with its relationships) will be used, otherwise a new object will be built from the row and put into the shared cache, and another copy with be put into the isolated cache. The isolated copy is always returned, unless read-only is used. For read-only the shared copy is returned as the isolated copy is not required.

The size and memory usage of the shared cache depends on the entities cache type. The JPA Cache and EclipseLink JpaCache can also be used to invalidate or clear the cache.

Protected Cache

The protected cache option allows for shared objects to reference isolated objects. Setting the cache isolation to PROTECTED for an entity enables its shared cache. The protected option is mostly the same as the shared option, except that protected entities can have relationships to isolated entities, where as shared can not.

Use a protected cache to do the following:

• improve performance by avoiding database access when finding or querying entities by Id or index;
• improve performance by avoiding database access when accessing entity's relationships to shared entities;
• ensure read-only entities are isolated to the persistence context;
• allows relationships to isolated entities.

Protected entities have the same life-cycle as shared entities, except for relationships, and read-only. Protected entities relationships to shared entities are cached in the shared cache, but their relationships to isolated entities are isolated. The Noncacheable annotation can also be used to disable caching of a shared relationship. Protected entities that are read-only are always copied into the isolated cache, but are not change tracked.

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.

Version: 2.2.0 DRAFT
Other versions...

Configuring Caching	Caching	Cache Type and Size
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...