Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Configuring
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Examples
Contents
Configuring Caching
EclipseLink enables a shared (L2) object cache by default on all entity objects. The shared cache can be disabled, or configured through standard JPA 2 configuration or through EclipseLink specific configuration. The EclipseLink cache configuration allows for the configuration of EclipseLink extended cache functionality.
Caching can be configured in EclipseLink through the following mechanisms:
- JPA 2 persistence.xml elements
- JPA 2 @Cacheable annotation and ORM XML element
- EclipseLink @Cache annotation and ORM XML element
- EclipseLink persistence unit properties
JPA 2 persistence.xml Cache Configuration
JPA 2 allows caching to be enabled or disabled through the persistence.xml
element <shared-cache-mode>
. This configures the default caching mode for the entire persistence unit. The default cache mode can be overridden for a specific class using the @Cacheable
annotation.
The valid values for <shared-cache-mode>
are defined in the SharedCacheMode
enum as:
- ALL - enable caching for all entities (overrides any @Cacheable annotation settings)
- NONE - disable caching for all entities (overrides any @Cacheable annotation settings)
- ENABLE_SELECTIVE - disable caching for all entities (@Cacheable can be used to enable caching)
- DISABLE_SELECTIVE - enable caching for all entities (@Cacheable can be used to disable caching)
JPA 2 persistence.xml cache configuration example
<?xml version="1.0" encoding="UTF-8"?> <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd" version="2.0"> <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <exclude-unlisted-classes>false</exclude-unlisted-classes> <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> </persistence-unit> </persistence>
@Cacheable
The JPA 2 @Cacheable
annotation or cacheable
XML attribute can be used to selectively enable or disabling caching for a specific entity class.
@Cacheable annotation example
... @Entity @Cacheable(false) public class Employee { ... }
EclipseLink allows entities that are cached to have relationships to entities that are not cached. However, the relationships themselves from cached entities to non-cached entities will not be cached. Entities that are not cached are considered ISOLATED in EclipseLink, entities that are cached are considered SHARED, and cached entities that have relationships to non-cached entities are considered PROTECTED. This is defined in the isolation
attribute of the EclipseLink @Cache
annotation.
@Cache
The Cache annotation is used to configure the EclipseLink object cache. By default EclipseLink uses a shared object cache to cache all objects. The caching type and options can be configured on a per class basis to allow optimal caching.
You can define the @Cache annotation on the following:
- @Entity
- @MappedSuperclass
- the root of the inheritance hierarchy (if applicable)
If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. If you define the @Cache annotation on @Embeddable EclipseLink will throw an exception.
Attribute | Description | Default | Required? |
---|---|---|---|
type | Set this attribute to the type (org.eclipse.persistence.annotations.CacheType enumerated type) of the cache that you will be using:
You can override this attribute with these persistence unit properties:
|
CacheType.SOFT_WEAK | Optional |
size | Set this attribute to an int value to define the size of cache to use (number of objects) | 100 | |
shared | Indicate whether cached instances should be in the shared cache or in a client isolated cache (see Isolated Client Session Cache). This allows the shared cache (L2 cache) to be disabled.
|
true | Optional |
expiry | The int value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy. | -1 (no expiry) | Optional |
expiryTimeOfDay | Specific time of day (org.eclipse.persistence.annotations.TimeOfDay) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy. | @TimeOfDay(specified=false) | Optional |
alwaysRefresh | Set to a boolean value of true to force all queries that go to the database to always refresh the cache. | false | Optional |
refreshOnlyIfNewer | Set to a boolean value of true to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).
Note: This option only applies if one of the other refreshing options, such as alwaysRefresh, is already enabled. Note: A version field is necessary to apply this feature. |
false | Optional |
disableHits | Set to a boolean value of true to force all queries to bypass the cache for hits, but still resolve against the cache for identity. This forces all queries to hit the database. | false | Optional |
coordinationType | Set this attribute to the cache coordination mode (org.eclipse.persistence.annotations.CacheCoordinationType enumerated type). | CacheCoordinationType.SEND_OBJECT_CHANGES | Optional |
@Cache annotation example
... @Entity @Cache( type=CacheType.SOFT, // Cache everything until the JVM decides memory is low. size=64000 // Use 64,000 as the initial cache size. expiry=36000000, // 10 minutes coordinationType=CacheCoordinationType.INVALIDATE_CHANGED_OBJECTS // if cache coordination is used, only send invalidation messages. ) public class Employee { ... }