Caching and Fresh Data has been edited by Ari Maniatis (Jun 20, 2008).

Change summary:

query cache clarification

(View changes)


What Is Cached in Cayenne

Cayenne uses multiple levels of cache to significantly improve performance by reducing the number of trips to the database. Cayenne caches individual objects, reducing the need to fetch them from the database. It also is able to cache query results, that is, the information about which objects were retrieved by a particular query.

Object cache

Individual objects are cached by Cayenne by default as they are fetched from the database or created by the user. Such caching is both a performance optimization mechanism and a way to ensure internal object uniquing. Users normally do not need to do anything special for this to work.

Cached objects are always shared between all DataContexts within Cayenne. They can optionally be shared between instanced in Cayenne in multiple Java Virtual Machines on the same computer.

This cache is defined on per application basis in the Cayenne model . A single number configured in the model defines the total number of records (of every type of entity) which can be stored within the cache.

The object cache is usually a good idea to enable. It reduces application memory use and increases query speed.

Refreshing query cache

The refresh query is used to

  • Refresh query - executing a refresh query using the name and/or cache key(s) will result in invalidating result lists associated with those keys.
  • Using LOCAL_CACHE_REFRESH or SHARED_CACHE_REFRESH as query cache policy

Refresh query is still being developed and further information can be found here .

Query cache

The query cache stores the result of a Query (SelectQuery, SqlTemplate or ProcedureQuery). The cached results are lists of objects. The cached list is matched to a query using a query name and cache keys, which are a user-definable array of Strings attached to the query. The same cache key can be used to refresh the cache using RefreshQuery. Please mind that the query cache does not automatically refresh when committing changes, so if you query for all Artists starting with 'B', create a new artist 'Bob' and commit them, perform the same query again without refreshing the cache, then 'Bob' will not be found since the earlier cached query will be returned.

The query cache is designed to improve performance of SelectQueries returning large result sets (by saving on sql execution and object faulting). Paging is another way of improving speed of large list queries, and it works nicely together with the query cache. Due to the limitations on how the data is refreshed, a query cache is best suited to use with queries on reference data (which rarely or never changes).

Query caches can be shared between all the queries within the context (LOCAL_CACHE) or between contexts (SHARED_CACHE). SHARED_CACHE does not work in ROP Cayenne.

Behind the scenes, for a LOCAL_CACHE Cayenne stores objects or DataRows (depending on which kind the query fetched), and for a SHARED_CACHE it stores DataRows which are converted to the target context objects on every cache hit.

Pluggable Cache

Third party caching providers can be used with Cayenne to provide more flexible caching options. Out of the box Cayenne provides two implementations of the pluggable cache factory:

  • 'org.apache.cayenne.cache.MapQueryCacheFactory' is a default factory that uses an LRU map to store query results. LRU map ensures that cached results would not take up all available memory, but otherwise it has no cache expiration mechanism.
  • 'org.apache.cayenne.cache.OSQueryCacheFactory' is a factory that installs OpenSymphony OSCache as a cache provider for Cayenne queries. It allows to configure cache expiration policies and cross-VM synchronization via an "" that should be placed in the CLASSPATH.


  1. RefreshQuery
  2. Object Caching

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences