About Cache Expiration and Invalidation

By default, objects remain in the shared cache until they are explicitly deleted or garbage collected.

You can configure any entity with an expiry that lets you specify either the number of milliseconds after which an entity instance should expire from the cache, or a time of day that all instances of the entity class should expire from the cache. Expiry is set on the @Cache annotation or <cache> XML element, and can be configured in two ways:

expiry—The number of milliseconds after which an entity instance will expire.
expiryTimeOfDay—A @TimeOfDay representing the 24-hour time at which all instances of the entity class will expire from the cache.

When an instance expires, it is only invalidated in the cache. It is not removed from the cache, but when next accessed it will be refreshed from the database as part of the query that was used to access it.

The application can also explicitly invalidate objects in the cache using the JPA Cache API, or the EclipseLink JpaCache API.

Expiry can also be used in the query results cache. See About Query Results Cache.

Invalidation can also be used in a cluster through cache coordination, or from database events using database event notification. See Coordinated Cache and Clustering.

Advanced Cache Invalidation

Alternatively, you can configure any object with a CacheInvalidationPolicy that lets you specify, either with annotations or XML, under what circumstances a cached object is invalid. When any query attempts to read an invalid object, EclipseLink will go to the data source for the most up-to-date version of that object, and update the cache with this information.

For descriptions of the available CacheInvalidationPolicy instances, see "Setting Cache Expiration" in Solutions Guide for EclipseLink.

You can configure a cache invalidation policy in the following ways:

At the project level that applies to all objects
At the descriptor level to override the project level configuration on a per-object basis
At the query level that applies to the results returned by the query

If you configure a query to cache results in its own internal cache, the cache invalidation policy you configure at the query level applies to the query's internal cache in the same way it would apply to the session cache.

If you are using a coordinated cache you can customize how EclipseLink communicates the fact that an object has been declared invalid. See About Cache Coordination.

The EclipseLink CacheInvalidationPolicy API offers a few advanced features that are not available through annotations or XML. It is also possible to define your own expiry or invalidation policy by defining your own CacheInvalidationPolicy. Advanced configuration can be done through using a DescriptorCustomizer to customize your entity's ClassDescriptor.

Here are a few of the CacheInvalidationPolicy advanced options:

isInvalidationRandomized—This allows the invalidation time to be randomized by 10% to avoid a large number of instances becoming invalid at the same time and causing a bottleneck in the database load. This is not used by default.
shouldRefreshInvalidObjectsOnClone—This ensures that an invalid object accessed through a relationship from another object will be refreshed in the persistence context. This is enabled by default.
shouldUpdateReadTimeOnUpdate—This updates an object's read time when the object is successfully updated. This is not enabled by default.