docs/3.0/query-result-caching.html

Title: Query Result Caching

	<H2><A name="QueryResultCaching-QueryResultCaching"></A>Query Result Caching</H2>

<P>In addition to caching individual objects, Cayenne can cache query results. Just like with object cache, the actual caching happens behind the scenes, so users only need to declare the desired cache policy, either in the code or via the Modeler:</P>

<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">SelectQuery query = <SPAN class="code-keyword">new</SPAN> SelectQuery(Artist.class, /* some qualifier */);
query.setCacheStrategy(QueryCacheStrategy.LOCAL_CACHE);
query.setCacheGroups(<SPAN class="code-quote">&quot;artists&quot;</SPAN>, <SPAN class="code-quote">&quot;recent_exhibits&quot;</SPAN>);
List&lt;Artist&gt; artists = context.performQuery(query);
</PRE>
</DIV></DIV>

<P>This query runs against the DB for the first time. Later if this query (or another query with the same parameters) is run again, the result is quickly returned from cache, and no DB access is performed.</P>

<P>Next we'll discuss what cache strategies and cache groups mean.</P>

<H3><A name="QueryResultCaching-CacheStrategies"></A>Cache Strategies</H3>

<P>Following Cayenne stack structure, query cache can be attached either to an ObjectContext or to a DataDomain. In the former case it is not shared between the contexts, and therefore is called &quot;local&quot;, in the later case, the cache is shared between all contexts from a given stack, and the cache is called &quot;shared&quot;. Access to the local cache is much faster, but the tradeoff is that it takes more memory if many contexts use local caching and also it hits database more often in a situation with multiple contexts. </P>

<P>Formally cache strategies are defined in the QueryCacheStrategy enum as NO_CACHE, LOCAL_CACHE, LOCAL_CACHE_REFRESH, SHARED_CACHE, SHARED_CACHE_REFRESH. Strategies ending with &quot;_REFRESH&quot; would actually run the query against database, but then cache the result. These are not used very often, as it is a good idea to separate cache refresh logic from the query code (as discussed below). Therefore the most common caching strategies are LOCAL_CACHE and SHARED_CACHE.</P>

<H3><A name="QueryResultCaching-CacheGroups"></A>Cache Groups</H3>

<P>As shown in the example above, each query can be tagged with one or more &quot;cache groups&quot;. Cache groups are symbolic names that a user assigns to certain queries to group them for the purpose of defining a common cache policy. These cache groups are just strings which can then be used as a way to indicate what data you'd like to refresh and when you'd like it refreshed.</P>

<H3><A name="QueryResultCaching-QueryCacheManagement"></A>QueryCache Management</H3>

<P>The query cache provider is installed via <TT>org.apache.cayenne.cache.QueryCacheFactory</TT>. The factory can be configured in the Modeler for the DataDomain, or set in code. Cayenne supplies a few factories out of the box that should be sufficient in most cases.</P>

<H4><A name="QueryResultCaching-SimpleCacheProviderLRUMap"></A>Simple Cache Provider - LRUMap</H4>

<P>The default factory is <TT>org.apache.cayenne.cache.MapQueryCacheFactory</TT> that is simply an LRU map. Cache entries never expire by themselves, but rarely used entries will be eventually swapped out when the cache is operating at the 100% capacity. This is the simplest form of query cache that requires users to implement their own &quot;active&quot; invalidation strategies accessing the methods of <TT>org.apache.cayenne.cache.QueryCache</TT> interface directly.</P>

<H4><A name="QueryResultCaching-AdvancedCacheProviderOSCache"></A>Advanced Cache Provider - OSCache</H4>

<P>A much more advanced cache provider can be installed via <TT>org.apache.cayenne.cache.OSQueryCacheFactory</TT>. The actual cache is using <A href="http://www.opensymphony.com/oscache/" class="external-link" rel="nofollow">OSCache</A> by OpenSymphony, so <A href="jar-files-and-dependencies.html" title="JAR Files and Dependencies">OSCache jars</A> need to be added to the application classpath. Cache configuration should be created outside Cayenne tools (e.g. in a text editor or in Eclipse) in a file called <BR>
<TT>&quot;oscache.properties&quot;</TT>. This file should be placed in the application classpath. The file format follows a regular java properties file. Here is an example that shows some of its capabilities, and demonstrates how to configure cache policies per cache group. More standard properties are discussed in the <A href="http://www.opensymphony.com/oscache/wiki/Configuration.html" class="external-link" rel="nofollow">OSCache documentation</A>.</P>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE># OSCache standard configuration:
                       
#cache.memory=true
#cache.blocking=false
cache.capacity=5000
cache.algorithm=com.opensymphony.oscache.base.algorithm.LRUCache
                        
# Cayenne specific properties:
                       
# Default refresh period in seconds 
# (used for all cache groups not explicitly overriding it here)
cayenne.default.refresh = 60

# Default expiry specified as cron expressions per
#    http://www.opensymphony.com/oscache/wiki/Cron%20Expressions.html
# expire entries every hour on the 10's minute
cayenne.default.cron = 10 * * * *
                        
# Same parameters can be defined per cache group, overriding the defaults
# cache group name is specified inside the property key. E.g. &quot;artists&quot; below 
# is a cache group name
cayenne.group.artists.refresh = 120
cayenne.group.artists.cron = 10 1 * * *
</PRE>
</DIV></DIV>

<P>As shown in this example, you can specify either a fixed expiration time since the entry was created or a cron-like cache expiration expression. Both can be specified either for the entire cache and/or one or more cache groups. As you see, cache groups become really useful when OSCache is used, and you don't have to do explicit cache management in the code. It is all 100% declarative. OSCache itself is very efficient when expiring groups that may potentially contain thousands of entries. Instead of scanning the entire cache for all entries that need to be expired, it simply tags the entire group as expired, so performance of this solution is really great.</P>

<H3><A name="QueryResultCaching-InstantCacheInvalidation"></A>Instant Cache Invalidation</H3>

<P>The above OSCache configuration is very flexible, however even this setup it does not address one important scenario - invalidation of a cache group on demand. This is often needed when a certain object is updated in the application, potentially rendering invalid a whole bunch of previously cached query results. How do we invalidate those cached object lists? </P>

<P>The first step is to find a place where an explicit cache update should be triggered. Usually this is done via <A href="lifecycle-callbacks.html" title="Lifecycle Callbacks">post commit callbacks</A>. A callback or a listener method would gain access to the QueryCache instance and call &quot;removeGroup&quot; for all groups that need to be invalidated. Here is where careful selection of query cache groups pays off. E.g. we may have tagged all queries fetching deceased artists with &quot;classics&quot; and all modern artists as &quot;modern&quot;. The Artist entity can map a callback method similar to this:</P>

<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">void onCommit() {
   QueryCache cache = ((BaseContext) getObjectContext()).getQueryCache();
   <SPAN class="code-keyword">if</SPAN>(isModern()) {
      cache.removeGroup(<SPAN class="code-quote">&quot;modern&quot;</SPAN>);
   }
   <SPAN class="code-keyword">else</SPAN> {
      cache.removeGroup(<SPAN class="code-quote">&quot;classic&quot;</SPAN>);
   }
}
}</PRE>
</DIV></DIV>

<P>This will ensure that subsequent &quot;performQuery&quot; calls will not use stale data, and the cache gets lazily refreshed.</P>

<P>The above approach is applicable to both LRU Map and OSCache. As expected, OSCache gives us extra capabilities in this area as well. As we've mentioned already, sending object change notifications between (possibly remote) Cayenne stacks is inefficient most of the time. Not so with OSCache. It can send remote invalidation notifications that are simply cache group names, so they create very little network traffic. Also on the receiving end invalidation is processed lazily, so no extra CPU cycles are immediately needed for the application to process an event. OSCache comes with support for JavaGroups and JMS notifications. To enable it add one of the following entries to <TT>&quot;oscache.properties&quot;</TT> per <A href="http://www.opensymphony.com/oscache/wiki/Clustering.html" class="external-link" rel="nofollow">OSCache clustering guide</A> :</P>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE>cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JMSBroadcastingListener
# other JMS paramaters go here...</PRE>
</DIV></DIV>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE>cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JavaGroupsBroadcastingListener
# other JavaGroups paramaters go here...</PRE>
</DIV></DIV>

<H3><A name="QueryResultCaching-QueryCacheConclusions"></A>Query Cache Conclusions</H3>

<P>The consequence of consistently using caching strategies and coming up with reasonable set of ache groups is that many applications no longer has to cache fetched lists explicitly. Re-running a query with a one of the caching strategies (especially with &quot;LOCAL_CACHE&quot;) becomes an extremely fast operation. Also the code becomes cleaner, as the state is stored in Cayenne, not in the application code. One possible exception from this rule is when the application needs to access the same list between requests, regardless of whether it is stale or not. </P>