cache-usage

Use eclipselink.cache-usage to specify how the query should interact with the EclipseLink cache.

Values

Table 4-3 describes this query hint's valid values.

Table 4-3 Valid Values for org.eclipse.persistence.config.CacheUsage

Value	Description
`DoNotCheckCache`	Always go to the database.
`CheckCacheByExactPrimaryKey`	If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory
`CheckCacheByPrimaryKey`	If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.
`CheckCacheThenDatabase`	You can configure any read-object query to check the cache completely before you resort to accessing the database.
`CheckCacheOnly`	You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.
`ConformResultsInUnitOfWork`	You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.
`UseEntityDefault`	(Default) Use the cache configuration as specified by the EclipseLink descriptor API for this entity. Note: The entity default value is to not check the cache (`DoNotCheckCache`). The query will access the database and synchronize with the cache. Unless refresh has been set on the query, the cached objects will be returned without being refreshed from the database. EclipseLink does not support the cache usage for native queries or queries that have complex result sets such as returning data or multiple objects.

Usage

EclipseLink JPA uses a shared cache assessed across the entire persistence unit. After completing an operation in a particular persistence context, EclipseLink merges the results into the shared cache, so that other persistence contexts can use the results regardless of whether the entity manager and persistence context are created in Java SE or Java EE.

Any entity persisted or removed using the entity manager will always consistently maintained with the cache.

Examples

Example 4-7 shows how to use this hint in a JPA query.

Example 4-7 Using cache-usage in a JPA Query

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);

Example 4-8 shows how to use this hint with the @QueryHint annotation.

Example 4-8 Using cache-usage in a @QueryHint Annotation

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);

See Also

For more information, see:

"EclipseLink Caches" in Understanding EclipseLink
"Querying" in Solutions Guide for EclispeLink
"Enhancing Performance" in Solutions Guide for EclispeLink
"cache-usage.indirection-policy"