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.
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.
|Mailing List • Forums • IRC • mattermost|
|Open • Help Wanted • Bug Day|
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)
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
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
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.
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.