caching.html - shiro-site - Git at Google

 <h1><a name="Caching-Caching"></a>Caching</h1>

 <p>The Shiro development team understands performance is critical in many applications.  Caching is a first class feature built into Shiro from day one to ensure that security operations remain as fast as possible.</p>

 <p>However, while Caching as a concept is a fundamental part of Shiro, implementing a full Cache mechanism would be outside the core competency of a security framework.  To that end, Shiro's cache support is basically an abstraction (wrapper) API that will 'sit' on top of an underlying production Cache mechanism (e.g. Hazelcast, Ehcache, OSCache, Terracotta, Coherence, GigaSpaces, JBossCache, etc).  This allows a Shiro end-user to configure any cache mechanism they prefer.</p>

 <h2><a name="Caching-CachingAPI"></a>Caching API</h2>

 <p>Shiro has three important cache interfaces:</p>

 <ul><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/CacheManager.html">CacheManager</a></tt> - The primary Manager component for all caching, it returns <tt>Cache</tt> instances.</li><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/Cache.html">Cache</a></tt> - Maintains key/value pairs</li><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/CacheManagerAware.html">CacheManagerAware</a></tt> - Implemented by components wishing to receive and use a CacheManager instance</li></ul>


 <p>A <tt>CacheManager</tt> returns <tt>Cache</tt> instances and various Shiro components use those <tt>Cache</tt> instances to cache data as necessary.  Any Shiro<br clear="none">
 component that implements <tt>CacheManagerAware</tt> will automatically receive a configured <tt>CacheManager</tt>, where it can be used to acquire <tt>Cache</tt> instances.</p>

 <p>The Shiro <a href="securitymanager.html" title="SecurityManager">SecurityManager</a> implementations and all <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html">AuthenticatingRealm</a></tt> and <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a></tt> implementations implement CacheManagerAware.  If you set the <tt>CacheManager</tt> on the <tt>SecurityManager</tt>, it will in turn set it on the various Realms that implement CacheManagerAware as well (OO delegation).  For example, in shiro.ini:</p>

 <div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>example shiro.ini CacheManger configuration</b></div><div class="codeContent panelContent">
 <pre class="code-java">
 securityManager.realms = $myRealm1, $myRealm2, ..., $myRealmN
 ...
 cacheManager = my.implementation.of.CacheManager
 ...
 securityManager.cacheManager = $cacheManager
 # at <span class="code-keyword">this</span> point, the securityManager and all CacheManagerAware
 # realms have been set with the cacheManager instance
 </pre>
 </div></div>

 <h2><a name="Caching-CacheManagerImplementations"></a>CacheManager Implementations</h2>

 <p>Shiro provides a number of out-of-the-box <tt>CacheManager</tt> implementations that you might find useful instead of implementing your own.</p>

 <h3><a name="Caching-%7B%7BMemoryConstrainedCacheManager%7D%7D"></a><tt>MemoryConstrainedCacheManager</tt></h3>

 <p>The <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/MemoryConstrainedCacheManager.html">MemoryConstrainedCacheManager</a></tt> is a <tt>CacheManager</tt> implementation suitable for single-JVM production environments.  It is not clustered/distributed, so if your application spans across more than one JVM (e.g. web app running on multiple web servers), and you want cache entries to be accessible across JVMs, you will need to use a distributed cache implementation instead.</p>

 <p>The <tt>MemoryConstrainedCacheManager</tt> manages <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/MapCache.html">MapCache</a></tt> instances, one <tt>MapCache</tt> instance per named cache.  Each <tt>MapCache</tt> instance is backed by a Shiro <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/util/SoftHashMap.html">SoftHashMap</a></tt> which can auto-resize itself based on an application's runtime memory constraints/needs (by leveraging JDK <tt><a class="external-link" href="http://docs.oracle.com/javase/1.4.2/docs/api/java/lang/ref/SoftReference.html" rel="nofollow">SoftReference</a></tt> instances).</p>

 <p>Because the <tt>MemoryConstrainedCacheManager</tt> can auto-resize itself based on an application's memory profile, it is safe to use in a single-JVM production application as well as for testing needs.  However, it does not have more advanced features suche as cache entry Time-to-Live or Time-to-Expire settings.  For these more advanced cache management features, you'll likely want to use one of the more advanced <tt>CacheManager</tt> offerings below.</p>

 <div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>MemoryConstrainedCacheManger shiro.ini configuration example</b></div><div class="codeContent panelContent">
 <pre class="code-java">

 ...
 cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
 ...
 securityManager.cacheManager = $cacheManager
 </pre>
 </div></div>

 <h3><a name="Caching-%7B%7BHazelcastCacheManager%7D%7D"></a><tt>HazelcastCacheManager</tt></h3>

 <div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Shiro 1.3 or later</b><br clear="none">This feature is not yet available in current Shiro releases.  It will be available starting in Shiro 1.3</td></tr></table></div>

 <p>TBD</p>

 <h3><a name="Caching-%7B%7BEhCacheManager%7D%7D"></a><tt>EhCacheManager</tt></h3>

 <p>TBD</p>

 <h2><a name="Caching-AuthorizationCacheInvalidation"></a>Authorization Cache Invalidation</h2>

 <p>Finally note that <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a></tt> has a <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)">clearCachedAuthorizationInfo method</a> that can be called by subclasses to evict the cached authzInfo for a particular account.  It is usually called by custom logic if the corresponding account's authz data has changed (to ensure the next authz check will pick up the new data).</p>
	<h1><a name="Caching-Caching"></a>Caching</h1>

	<p>The Shiro development team understands performance is critical in many applications. Caching is a first class feature built into Shiro from day one to ensure that security operations remain as fast as possible.</p>

	<p>However, while Caching as a concept is a fundamental part of Shiro, implementing a full Cache mechanism would be outside the core competency of a security framework. To that end, Shiro's cache support is basically an abstraction (wrapper) API that will 'sit' on top of an underlying production Cache mechanism (e.g. Hazelcast, Ehcache, OSCache, Terracotta, Coherence, GigaSpaces, JBossCache, etc). This allows a Shiro end-user to configure any cache mechanism they prefer.</p>

	<h2><a name="Caching-CachingAPI"></a>Caching API</h2>

	<p>Shiro has three important cache interfaces:</p>

	<ul><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/CacheManager.html">CacheManager</a></tt> - The primary Manager component for all caching, it returns <tt>Cache</tt> instances.</li><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/Cache.html">Cache</a></tt> - Maintains key/value pairs</li><li><tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/CacheManagerAware.html">CacheManagerAware</a></tt> - Implemented by components wishing to receive and use a CacheManager instance</li></ul>


	<p>A <tt>CacheManager</tt> returns <tt>Cache</tt> instances and various Shiro components use those <tt>Cache</tt> instances to cache data as necessary. Any Shiro<br clear="none">
	component that implements <tt>CacheManagerAware</tt> will automatically receive a configured <tt>CacheManager</tt>, where it can be used to acquire <tt>Cache</tt> instances.</p>

	<p>The Shiro <a href="securitymanager.html" title="SecurityManager">SecurityManager</a> implementations and all <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html">AuthenticatingRealm</a></tt> and <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a></tt> implementations implement CacheManagerAware. If you set the <tt>CacheManager</tt> on the <tt>SecurityManager</tt>, it will in turn set it on the various Realms that implement CacheManagerAware as well (OO delegation). For example, in shiro.ini:</p>

	<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>example shiro.ini CacheManger configuration</b></div><div class="codeContent panelContent">
	<pre class="code-java">
	securityManager.realms = $myRealm1, $myRealm2, ..., $myRealmN
	...
	cacheManager = my.implementation.of.CacheManager
	...
	securityManager.cacheManager = $cacheManager
	# at <span class="code-keyword">this</span> point, the securityManager and all CacheManagerAware
	# realms have been set with the cacheManager instance
	</pre>
	</div></div>

	<h2><a name="Caching-CacheManagerImplementations"></a>CacheManager Implementations</h2>

	<p>Shiro provides a number of out-of-the-box <tt>CacheManager</tt> implementations that you might find useful instead of implementing your own.</p>

	<h3><a name="Caching-%7B%7BMemoryConstrainedCacheManager%7D%7D"></a><tt>MemoryConstrainedCacheManager</tt></h3>

	<p>The <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/MemoryConstrainedCacheManager.html">MemoryConstrainedCacheManager</a></tt> is a <tt>CacheManager</tt> implementation suitable for single-JVM production environments. It is not clustered/distributed, so if your application spans across more than one JVM (e.g. web app running on multiple web servers), and you want cache entries to be accessible across JVMs, you will need to use a distributed cache implementation instead.</p>

	<p>The <tt>MemoryConstrainedCacheManager</tt> manages <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/MapCache.html">MapCache</a></tt> instances, one <tt>MapCache</tt> instance per named cache. Each <tt>MapCache</tt> instance is backed by a Shiro <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/util/SoftHashMap.html">SoftHashMap</a></tt> which can auto-resize itself based on an application's runtime memory constraints/needs (by leveraging JDK <tt><a class="external-link" href="http://docs.oracle.com/javase/1.4.2/docs/api/java/lang/ref/SoftReference.html" rel="nofollow">SoftReference</a></tt> instances).</p>

	<p>Because the <tt>MemoryConstrainedCacheManager</tt> can auto-resize itself based on an application's memory profile, it is safe to use in a single-JVM production application as well as for testing needs. However, it does not have more advanced features suche as cache entry Time-to-Live or Time-to-Expire settings. For these more advanced cache management features, you'll likely want to use one of the more advanced <tt>CacheManager</tt> offerings below.</p>

	<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>MemoryConstrainedCacheManger shiro.ini configuration example</b></div><div class="codeContent panelContent">
	<pre class="code-java">

	...
	cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
	...
	securityManager.cacheManager = $cacheManager
	</pre>
	</div></div>

	<h3><a name="Caching-%7B%7BHazelcastCacheManager%7D%7D"></a><tt>HazelcastCacheManager</tt></h3>

	<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Shiro 1.3 or later</b><br clear="none">This feature is not yet available in current Shiro releases. It will be available starting in Shiro 1.3</td></tr></table></div>

	<p>TBD</p>

	<h3><a name="Caching-%7B%7BEhCacheManager%7D%7D"></a><tt>EhCacheManager</tt></h3>

	<p>TBD</p>

	<h2><a name="Caching-AuthorizationCacheInvalidation"></a>Authorization Cache Invalidation</h2>

	<p>Finally note that <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a></tt> has a <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)">clearCachedAuthorizationInfo method</a> that can be called by subclasses to evict the cached authzInfo for a particular account. It is usually called by custom logic if the corresponding account's authz data has changed (to ensure the next authz check will pick up the new data).</p>