3.11.1.4. Query Cache
In addition to the data cache, the org.apache.openjpa.datacache package defines service provider interfaces for a query cache.
The query cache is disabled by default and needs to be enabled separately from the data cache.
The query cache stores the object ids returned by query executions.
When you run a query, OpenJPA assembles a key based on the query properties and the parameters used at execution time, and checks for a cached query result.
If one is found, the object ids in the cached result are looked up, and the resultant persistence-capable objects are returned.
Otherwise, the query is executed against the database, and the object ids loaded by the query are put into the cache.
The object id list is not cached until the list returned at query execution time is fully traversed.
OpenJPA exposes a high-level interface to the query cache through the
org.apache.openjpa.persistence.QueryResultCache class.
You can access this class through the OpenJPAEntityManagerFactory.
import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();
The default query cache implementation caches 100 query executions in a least-recently-used cache.
This can be changed by setting the cache size in the CacheSize plugin property.
Like the data cache, the query cache also has a backing soft reference map.
The SoftReferenceSize property controls the size of this map.
It is disabled by default.
<property name="openjpa.QueryCache" value="true(CacheSize=1000, SoftReferenceSize=100)"/>
To disable the query cache (default), set the openjpa.QueryCache property to false:
<property name="openjpa.QueryCache" value="false"/>
Query Cache’s default behaviour on eviction is to evict all the queries from the cache if any of the entities that are in the access path of the query are modified.
Scanning through the whole query cache to evict the queries upon an entity update slows down the entity update action.
The configurable eviction policy "timestamp" is to track the timestamp of the query and the timestamp of last update for each entity class and compare the timestamps when retrieving the query for reuse.
If the timestamp of the query result is older than the last update time of any entity in the access path of the query, the query result would not be reused and the query result would be evicted from the query cache.
To configure the EvictPolicy to timestamp, here is an example:
<property name="openjpa.QueryCache" value="true(EvictPolicy='timestamp')"/>
There are certain situations in which the query cache is bypassed:
-
Caching is not used for in-memory queries (queries in which the candidates are a collection instead of a class or
Extent). -
Caching is not used in transactions that have
IgnoreChangesset tofalseand in which modifications to classes in the query’s access path have occurred. If none of the classes in the access path have been touched, then cached results are still valid and are used. -
Caching is not used in pessimistic transactions, since OpenJPA must go to the database to lock the appropriate rows.
-
Caching is not used when the data cache does not have any cached data for an id in a query result.
-
Queries that use persistence-capable objects as parameters are only cached if the parameter is directly compared to field, as in:
select e from Employee e where e.company.address = :addr
If you extract field values from the parameter in your query string, or if the parameter is used in collection element comparisons, the query is not cached.
* Queries that result in projections of custom field types or BigDecimal or BigInteger fields are not cached.
Cache results are removed from the cache when instances of classes in a cached query’s access path are touched.
That is, if a query accesses data in class A, and instances of class A are modified, deleted, or inserted, then the cached query result is dropped from the cache.
It is possible to tell the query cache that a class has been altered. This is only necessary when the changes occur via direct modification of the database outside of OpenJPA’s control. You can also evict individual queries, or clear the entire cache.
public void evict(Query q);
public void evictAll(Class cls);
public void evictAll();
For JPA queries with parameters, set the desired parameter values into the Query instance before calling the above methods.
import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();
// evict all queries that can be affected by changes to Magazines
qcache.evictAll(Magazine.class);
// evict an individual query with parameters
EntityManager em = emf.createEntityManager();
Query q = em.createQuery(...).
setParameter(0, paramVal0).
setParameter(1, paramVal1);
qcache.evict(q);
When using one of OpenJPA’s distributed cache implementations, it is necessary to perform this in every JVM - the change notification is not propagated automatically. When using a third-party coherent caching solution, it is not necessary to do this in every JVM (although it won’t hurt to do so), as the cache results are stored directly in the coherent cache.
Queries can also be pinned and unpinned through the QueryResultCache.
The semantics of these operations are the same as pinning and unpinning data from the data cache.
public void pin(Query q);
public void unpin(Query q);
For JPA queries with parameters, set the desired parameter values into the Query instance before calling the above methods.
The following example shows these APIs in action.
import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();
EntityManager em = emf.createEntityManager();
Query pinQuery = em.createQuery(...).
setParameter(0, paramVal0).
setParameter(1, paramVal1);
qcache.pin(pinQuery);
Query unpinQuery = em.createQuery(...).
setParameter(0, paramVal0).
setParameter(1, paramVal1);
qcache.unpin(unpinQuery);
Pinning data into the cache instructs the cache to not expire the pinned results when cache flushing occurs. However, pinned results will be removed from the cache if an event occurs that invalidates the results.
You can disable caching on a per-EntityManager or per-Query basis:
import org.apache.openjpa.persistence.*;
...
// temporarily disable query caching for all queries created from em
OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
oem.getFetchPlan().setQueryResultCacheEnabled(false);
// re-enable caching for a particular query
OpenJPAQuery oq = oem.createQuery(...);
oq.getFetchPlan().setQueryResultCacheEnabled(true);