'''[[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)]'' and "Object Caching" in the ''[http://www.eclipse.org/eclipselink/documentation/ EclipseLink Solutions Guide]''for current information.'''

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 or @Cache annotations.

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)

@Cacheable

The JPA 2 @Cacheable annotation or cacheable XML attribute can be used to selectively enable or disabling caching for a specific entity class.

You can define the @Cacheable annotation on the following:

@Entity

@MappedSuperclass

If you define the @Cacheable annotation on an entity inheritance subclass, the annotation will be ignored. The @Cacheable annotation is not supported on an @Embeddable.

@Cacheable annotation example

...
@Entity
@Cacheable(false)publicclass 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 can also be configured using the isolation attribute of the EclipseLink @Cache annotation.

@Cache

The @Cache annotation or <cache> XML element can be used to configure caching for a specific entity class.

You can define the @Cache annotation on the following:

@Entity

@MappedSuperclass

If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. The @Cache annotation is not supported on an @Embeddable.

@Cache Annotation Attributes

Attribute

Description

Default

Required?

type

Set this attribute to the type (CacheType enumerated type) of the cache that you will be using:

FULL

WEAK

SOFT

SOFT_WEAK

HARD_WEAK

There are also types, CACHE and NONE but these are not recommended, and should not be used, to disable caching set isolation=ISOLATED instead.

CacheType.SOFT_WEAK

Optional

size

Set this attribute to an int value to define the size of cache to use (number of objects)

100

Optional

isolation

Set the cache isolation. This allows the shared cache to be enabled or disabled.

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.

no expiry

Optional

expiryTimeOfDay

Specific time of day (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.

no expiry

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 (CacheCoordinationType enumerated type).
Note: cache coordination must also be configured in the persistence.xml.

CacheCoordinationType.SEND_OBJECT_CHANGES

Optional

databaseChangeNotificationType

Set this attribute to the database change notification mode (DatabaseChangeNotificationType enumerated type).

Note: database change notification must also be configured in the persistence.xml.