Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Caching Overview"

(Caching Overview)
m
 
(33 intermediate revisions by one other user not shown)
Line 1: Line 1:
 +
----
 +
 +
 +
'''[[Image:Elug_draft_icon.png|Warning]] This page is obsolete. Please see "Understanding Caching" in the ''[http://www.eclipse.org/eclipselink/documentation/ Understanding EclipseLink (Concepts Guide)]'' for current information.'''
 +
 +
 +
----
 +
 +
 
{{EclipseLink_UserGuide|info=y
 
{{EclipseLink_UserGuide|info=y
 +
|toc=y
 
|api=y
 
|api=y
 
|apis=
 
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Cacheable.html @Cacheable]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache]
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/TimeOfDay.html @TimeOfDay]
+
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheIndex.html @CacheIndex]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/ReadOnly.html @ReadOnly]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Noncacheable.html @Noncacheable]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheInterceptor.html @CacheInterceptor]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/ExistenceChecking.html @ExistenceChecking]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/ExistenceChecking.html @ExistenceChecking]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html @PersistenceUnitProperties]
 
|examples=y
 
|examples=y
 
|example=
 
|example=
*[[EclipseLink/Examples/JPA/Caching|Caching]]
+
*[[EclipseLink/Examples/JPA/Caching|How to use caching]]
}}
+
*[[EclipseLink/Examples/JPA/CacheCoordination|How to enable cache coordination]]
 +
*[[EclipseLink/Examples/JPA/DCN|How to use database event driven cache invalidation]]}}
 +
 
 
=Caching Overview=
 
=Caching Overview=
 
The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and Id values. EclipseLink uses the cache to do the following:
 
The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and Id values. EclipseLink uses the cache to do the following:
  
* Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.
+
* Improve performance by holding recently read or written objects and their relationships and accessing them in-memory to minimize database access.
 
* Manage locking and isolation level.
 
* Manage locking and isolation level.
 
* Manage object identity.
 
* Manage object identity.
  
For more information about the EclipseLink cache and its default behavior, see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]].
+
EclipseLink offers an integrated and functional cache including the following features:
  
EclipseLink defines the following entity caching annotations:
+
* Isolated persistence context cache (L1), and shared persistence unit cache (L2)
 +
* Caching configurable at the entity level, entities can be cached, or not, cached entities can reference non-cached entities
 +
* Multiple cache type options (weak, soft, full, weak-cache, soft-cache)
 +
* Configurable size
 +
* Read-only entities
 +
* Cache indexes
 +
* Query-level cache options
 +
* In-memory querying and conforming
 +
* Time to live, and daily cache invalidation
 +
* Clustered cache coordination through RMI and JMS
 +
* Database event driven cache invalidation and Oracle DCN/QCN
 +
* Support for JPA 2.0 @Cachable configuraiton and API
 +
* Extended JpaCache API
 +
* Query cache
  
* <tt>@Cache</tt>
+
EclipseLink supports the following caching annotations and XML elements:
* <tt>@TimeOfDay</tt>
+
* <tt>@ExistenceChecking</tt>
+
  
EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache (see [[#How to Use the Persistence Unit Properties for Caching|How to Use the Persistence Unit Properties for Caching]]). These properties may compliment or provide an alternative to the usage of annotations.
+
* @Cacheable (JPA 2.0)
 +
* @Cache
 +
* @CacheIndex
 +
* @ReadOnly
 +
* @Noncacheable
 +
* @CacheInterceptor
 +
* @ExistenceChecking
 +
  
For more information, see the following:  
+
EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache. These properties may compliment or provide an alternative to the usage of annotations.  Caching options can also be configured through the EclipseLink Java API using a <code>SessionCustomizer</code>.
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
 
* [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]
+
==Cache Architecture==
 +
EclipseLink uses two types of cache: the shared '''persistence unit cache'''  (L2) maintains objects retrieved from and written to the data source; and the isolated '''persistence context cache''' (L1) holds objects while they participate in transactions. When a persistence context (entity manager) successfully commits to the data source, EclipseLink updates the persistence unit cache accordingly.  Conceptually the persistence context cache is represented by the <code>EntityManager</code> and the persistence unit cache is represented by the <code>EntityManagerFactory</code>.
 +
 
 +
Internally EclipseLink stores the persistence unit cache on an EclipseLink session, and the persistence context cache on an EclipseLink unit of work.  As this figure shows, the persistence unit cache (session) cache and the persistence context cache (unit of work cache) work together with the data source connection to manage objects in an EclipseLink application. The object life cycle relies on these three mechanisms.
 +
 
 +
 
 +
<span id="Figure 98-1"></span>
 +
''''' Object Life Cycle and the EclipseLink Caches'''''
 +
 
 +
[[Image:cacharch.gif|Object Life Cycle and the EclipseLink Caches]]<br /><br />
 +
 
 +
 
 +
===Persistence Unit Cache===
 +
The persistence unit cache is a shared cache (L2) that services clients attached to a given persistence unit. When you read objects from or write objects to the data source using an <code>EntityManager</code>, EclipseLink saves a copy of the objects in the persistence unit's cache and makes them accessible to all other processes accessing the same persistence unit.
 +
 
 +
EclipseLink adds objects to the persistence unit cache from the following:
 +
* The data store, when EclipseLink executes a read operation
 +
* The persistence context cache, when a persistence context successfully commits a transaction
 +
 
 +
EclipseLink defines three cache isolation levels:
 +
* 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
 +
 
 +
For more information, see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated|Shared, Isolated, Protected, Weak, and Read-Only Cache]].
 +
 
 +
There is a separate persistence unit cache for each unique persistence unit name.  Although the cache is conceptually stored with the <code>EntityManagerFactory</code>, in EclipseLink two factories with the same persistence unit name will share the same cache (and effectively be the same persistence unit instance).  If the same persistence unit is deployed in two separate applications in Java EE, their full persistence unit name will normally still be unique, and they will use separate caches.  Certain persistence unit properties, such as data-source, database URL, user, and tenant id can affect the unique name of the persistence unit, and result in seperate persistence unit instances and separate caches.  The <code>"eclipselink.session.name"</code> persistence unit property can be used to force two persistence units to resolve to the same instance and share a cache.
 +
 
 +
===Persistence Context Cache===
 +
 
 +
The persistence context cache is an isolated cache (L1) that services operations within an <code>EntityManager</code>. It maintains and isolates objects from the persistence unit cache, and writes changed or new objects to the persistence unit cache after the persistence context commits changes to the data source.
 +
 
 +
{{EclipseLink_Note
 +
|note=Only committed changes are merged into the shared persistence unit cache, <code>flush</code> or other operations do not affect the persistence unit cache until the transaction is committed.
 +
}}
 +
 
 +
The life-cycle for the persistence context cache differs between application managed, and container managed persistence contexts.
 +
 
 +
====Application managed persistence contexts====
 +
An application managed persistence context is created by the application from an <code>EntityManagerFactory</code>.  The application managed persistence context's cache will remain until the <code>EntityManager</code> is closed or <code>clear()</code> is called.  It is important to keep application managed persistence unit's short lived, or to make use of <code>clear()</code> to avoid the persistence context cache from growing to big, or from becoming out of sync with the persistence unit cache and the database.  Typically a separate <code>EntityManager</code> should be created for each transaction or request.
 +
 
 +
An extended persistence context has the same caching behavior as an application managed persistence context, even if it is managed by the container.
 +
 
 +
EclipeLink also supports a <code>WEAK</code> reference mode option for long lived persistence contexts, such as two-tier applications.  See [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated#Weak Reference Mode|Weak Reference Mode]].
 +
 
 +
====Container managed persistence contexts====
 +
A container managed persistence context is typically injected into a SessionBean or other managed object by a Java EE container, or frameworks such as Spring.  The container managed persistence context's cache will only remain for the duration of the transaction.  Entities read in a transaction will become detached after the completion of the transaction and will require to be merged to be edited in subsequent transactions.
 +
 
 +
{{EclipseLink_Note
 +
|note=EclipseLink supports accessing an entity's <code>LAZY</code> relationships after the persistence context has been closed.
 +
}}
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
 
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
 
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Cache Annotation|@Cache]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Configuring|Configuring Caching]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
|version=2.2.0 DRAFT}}
+
|version=2.4 DRAFT}}

Latest revision as of 13:50, 5 February 2013



Warning This page is obsolete. Please see "Understanding Caching" in the Understanding EclipseLink (Concepts Guide) for current information.





Caching Overview

The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and Id values. EclipseLink uses the cache to do the following:

  • Improve performance by holding recently read or written objects and their relationships and accessing them in-memory to minimize database access.
  • Manage locking and isolation level.
  • Manage object identity.

EclipseLink offers an integrated and functional cache including the following features:

  • Isolated persistence context cache (L1), and shared persistence unit cache (L2)
  • Caching configurable at the entity level, entities can be cached, or not, cached entities can reference non-cached entities
  • Multiple cache type options (weak, soft, full, weak-cache, soft-cache)
  • Configurable size
  • Read-only entities
  • Cache indexes
  • Query-level cache options
  • In-memory querying and conforming
  • Time to live, and daily cache invalidation
  • Clustered cache coordination through RMI and JMS
  • Database event driven cache invalidation and Oracle DCN/QCN
  • Support for JPA 2.0 @Cachable configuraiton and API
  • Extended JpaCache API
  • Query cache

EclipseLink supports the following caching annotations and XML elements:

  • @Cacheable (JPA 2.0)
  • @Cache
  • @CacheIndex
  • @ReadOnly
  • @Noncacheable
  • @CacheInterceptor
  • @ExistenceChecking


EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache. These properties may compliment or provide an alternative to the usage of annotations. Caching options can also be configured through the EclipseLink Java API using a SessionCustomizer.

Cache Architecture

EclipseLink uses two types of cache: the shared persistence unit cache (L2) maintains objects retrieved from and written to the data source; and the isolated persistence context cache (L1) holds objects while they participate in transactions. When a persistence context (entity manager) successfully commits to the data source, EclipseLink updates the persistence unit cache accordingly. Conceptually the persistence context cache is represented by the EntityManager and the persistence unit cache is represented by the EntityManagerFactory.

Internally EclipseLink stores the persistence unit cache on an EclipseLink session, and the persistence context cache on an EclipseLink unit of work. As this figure shows, the persistence unit cache (session) cache and the persistence context cache (unit of work cache) work together with the data source connection to manage objects in an EclipseLink application. The object life cycle relies on these three mechanisms.


Object Life Cycle and the EclipseLink Caches

Object Life Cycle and the EclipseLink Caches


Persistence Unit Cache

The persistence unit cache is a shared cache (L2) that services clients attached to a given persistence unit. When you read objects from or write objects to the data source using an EntityManager, EclipseLink saves a copy of the objects in the persistence unit's cache and makes them accessible to all other processes accessing the same persistence unit.

EclipseLink adds objects to the persistence unit cache from the following:

  • The data store, when EclipseLink executes a read operation
  • The persistence context cache, when a persistence context successfully commits a transaction

EclipseLink defines three cache isolation levels:

  • 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

For more information, see Shared, Isolated, Protected, Weak, and Read-Only Cache.

There is a separate persistence unit cache for each unique persistence unit name. Although the cache is conceptually stored with the EntityManagerFactory, in EclipseLink two factories with the same persistence unit name will share the same cache (and effectively be the same persistence unit instance). If the same persistence unit is deployed in two separate applications in Java EE, their full persistence unit name will normally still be unique, and they will use separate caches. Certain persistence unit properties, such as data-source, database URL, user, and tenant id can affect the unique name of the persistence unit, and result in seperate persistence unit instances and separate caches. The "eclipselink.session.name" persistence unit property can be used to force two persistence units to resolve to the same instance and share a cache.

Persistence Context Cache

The persistence context cache is an isolated cache (L1) that services operations within an EntityManager. It maintains and isolates objects from the persistence unit cache, and writes changed or new objects to the persistence unit cache after the persistence context commits changes to the data source.

Elug note icon.png

Note: Only committed changes are merged into the shared persistence unit cache, flush or other operations do not affect the persistence unit cache until the transaction is committed.

The life-cycle for the persistence context cache differs between application managed, and container managed persistence contexts.

Application managed persistence contexts

An application managed persistence context is created by the application from an EntityManagerFactory. The application managed persistence context's cache will remain until the EntityManager is closed or clear() is called. It is important to keep application managed persistence unit's short lived, or to make use of clear() to avoid the persistence context cache from growing to big, or from becoming out of sync with the persistence unit cache and the database. Typically a separate EntityManager should be created for each transaction or request.

An extended persistence context has the same caching behavior as an application managed persistence context, even if it is managed by the container.

EclipeLink also supports a WEAK reference mode option for long lived persistence contexts, such as two-tier applications. See Weak Reference Mode.

Container managed persistence contexts

A container managed persistence context is typically injected into a SessionBean or other managed object by a Java EE container, or frameworks such as Spring. The container managed persistence context's cache will only remain for the duration of the transaction. Entities read in a transaction will become detached after the completion of the transaction and will require to be merged to be edited in subsequent transactions.

Elug note icon.png

Note: EclipseLink supports accessing an entity's LAZY relationships after the persistence context has been closed.

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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.