EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Caching Overview

---

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

---

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

Key API

• @Cacheable
• @Cache
• @CacheIndex
• @ReadOnly
• @Noncacheable
• @CacheInterceptor
• @ExistenceChecking
• @PersistenceUnitProperties

Examples

• How to use caching
• How to enable cache coordination
• How to use database event driven cache invalidation

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

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.

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.

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

Version: 2.4 DRAFT
Other versions...

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