blob: d51cd8312c0516e0a8ace02beeaedb7f88d7586a [file] [log] [blame]
<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE- 2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Caching | Apache Shiro</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="keywords" content='caching,cache'>
<meta name="generator" content="JBake">
<meta name="google-site-verification" content="QIax6uT5UX3enoU0G8Pz2pXbQ45KaQuHZ3nCh9V27mw">
<meta name="google-site-verification" content="ecFap6dWJgS_GCCtxmJQJ_nFYQhM6EgSpBPZDU7xsCE">
<meta name="google-site-verification" content="gBTYOG8lMfNb_jrWrH3kFbudpEs_WrAJ2lb2-zLRaso"/>
<meta name="msvalidate.01" content="0B57EB46CBFAD8FD45008D2DB6B6C68C">
<meta property="og:title" content="Caching | Apache Shiro"/>
<meta property="og:type" content="article"/>
<meta name="twitter:card" content="summary" />
<meta name="twitter:site" content="@ApacheShiro" />
<meta property="article:modification_time" content="2010-03-18T00:00:00Z"/>
<meta property="article:tag" content='caching'/>
<meta property="article:tag" content='cache'/>
<meta property="og:locale" content="en_US" />
<meta property="og:url" content='https://shiro.apache.org/caching.html'/>
<meta property="og:image" content='images/shiro-featured-image.png'/>
<meta property="og:image:width" content='1200'/>
<meta property="og:image:height" content='628'/>
<meta property="og:site_name" content="Apache Shiro"/>
<!-- Le styles -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="bootstrap-icons-1.5.0/bootstrap-icons.css" rel="stylesheet">
<link href="css/asciidoctor.css" rel="stylesheet">
<link href="css/base.css" rel="stylesheet">
<link href="highlight.js-11.2.0/styles/default.min.css" rel="stylesheet">
<link href="css/gh-pages/gh-fork-ribbon.css" rel="stylesheet"/>
<!-- Fav and touch icons -->
<!--<link rel="apple-touch-icon-precomposed" sizes="144x144" href="../assets/ico/apple-touch-icon-144-precomposed.png">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="../assets/ico/apple-touch-icon-114-precomposed.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="../assets/ico/apple-touch-icon-72-precomposed.png">
<link rel="apple-touch-icon-precomposed" href="../assets/ico/apple-touch-icon-57-precomposed.png">-->
<link rel="shortcut icon" href="favicon.ico">
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//matomo.privacy.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '2']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</head>
<body>
<div id="top-bar"></div>
<a class="github-fork-ribbon right-top" href="https://github.com/apache/shiro" title="Fork me on GitHub">Fork me on GitHub</a>
<div id="wrap">
<div class="masthead">
<p class="lead">
<a href="index.html"><img src="images/apache-shiro-logo.png" style="height:100px; width:auto; vertical-align: bottom; margin-top: 20px;" alt="Apache Shiro Logo"></a>
<span class="tagline">Simple. Java. Security.</span>
<a class="pull-right" href="https://www.apache.org/events/current-event.html">
<img style="padding-top: 8px" src="https://www.apache.org/events/current-event-125x125.png" alt="Apache Software Foundation Event Banner"/>
</a>
</p>
</div>
<!-- Fixed navbar -->
<nav class="navbar navbar-expand-lg navbar-light bg-light shadow-sm mb-4">
<div class="container-fluid">
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav me-auto mb-2 mb-lg-0">
<li class="nav-item">
<a class="nav-link" href="get-started.html">Get Started</a>
</li>
<li class="nav-item">
<a class="nav-link" href="documentation.html">Docs</a>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown-webapps" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Web Apps
</a>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-webapps">
<li><a class="dropdown-item" href="web.html">General</a></li>
<li><a class="dropdown-item" href="jaxrs.html">JAX-RS</a></li>
<li><a class="dropdown-item" href="jakarta-ee.html">Jakarta EE</a></li>
<li><hr class="dropdown-divider"></li>
<li><a class="dropdown-item" href="web-features.html">Features</a></li>
</ul>
</li>
<li><a class="nav-link" href="features.html">Features</a></li>
<!-- integrations -->
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown-integrations" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Integrations
</a>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-integrations">
<li><a class="dropdown-item" href="spring-boot.html">Spring</a></li>
<li><a class="dropdown-item" href="guice.html">Guice</a></li>
<li><hr class="dropdown-divider"></li>
<li><a class="dropdown-item" href="integration.html">Third-Party Integrations</a></li>
</ul>
</li>
<!-- Community -->
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown-community" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Community
</a>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-community">
<li><a class="dropdown-item" href="forums.html">Community Forums</a></li>
<li><a class="dropdown-item" href="mailing-lists.html">Mailing Lists</a></li>
<li><a class="dropdown-item" href="articles.html">Articles</a></li>
<li><a class="dropdown-item" href="news.html">News</a></li>
<li><a class="dropdown-item" href="events.html">Events</a></li>
<li><hr class="dropdown-divider"></li>
<li><a class="dropdown-item" href="community.html">More</a></li>
</ul>
</li>
<!-- About -->
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown-about" role="button" data-bs-toggle="dropdown" aria-expanded="false">
About
</a>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-about">
<li><a class="dropdown-item" href="about.html">About</a></li>
<li><a class="dropdown-item" href="privacy-policy.html">Privacy Policy</a></li>
<li><a class="dropdown-item" href="security-reports.html">Vulnerability Reports</a></li>
</ul>
</li>
</ul>
<ul class="d-flex justify-content-end navbar-nav mb-2 mb-lg-0">
<!-- The ASF -->
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown-asf" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Apache Software Foundation
</a>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-asf">
<li><a class="dropdown-item" href="https://www.apache.org/">Apache Homepage</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/licenses/">License</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/security/">Security</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<div class="page-header">
<h1>Caching</h1>
</div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon">
<div class="title">Handy Hint</div>
</td>
<td class="content">
<div class="title">Shiro v1 version notice</div>
<div class="paragraph">
<p>As of 2024-03-01, Shiro v1 will soon be superseded by v2.<p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<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 &#8216;sit&#8217; 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>
</div>
</div>
</div>
<div class="sect1">
<h2 id="caching_api">Caching API</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Shiro has three important cache interfaces:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="static/current/apidocs/org/apache/shiro/cache/CacheManager.html"><code>CacheManager</code></a></p>
<div class="ulist">
<ul>
<li>
<p>The primary Manager component for all caching, it returns <code>Cache</code>
instances.</p>
</li>
</ul>
</div>
</li>
<li>
<p><a href="static/current/apidocs/org/apache/shiro/cache/Cache.html"><code>Cache</code></a></p>
<div class="ulist">
<ul>
<li>
<p>Maintains key/value pairs</p>
</li>
</ul>
</div>
</li>
<li>
<p><a href="static/current/apidocs/org/apache/shiro/cache/CacheManagerAware.html"><code>CacheManagerAware</code></a></p>
<div class="ulist">
<ul>
<li>
<p>Implemented by components wishing to receive and use a CacheManager
instance</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>A <code>CacheManager</code> returns <code>Cache</code> instances and various Shiro
components use those <code>Cache</code> instances to cache data as necessary. Any
Shiro component that implements <code>CacheManagerAware</code> will automatically
receive a configured <code>CacheManager</code>, where it can be used to acquire
<code>Cache</code> instances.</p>
</div>
<div class="paragraph">
<p>The Shiro <a href="securitymanager.html">SecurityManager</a> implementations and
all
<a href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html"><code>AuthenticatingRealm</code></a>
and
<a href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html"><code>AuthorizingRealm</code></a>
implementations implement CacheManagerAware. If you set the
<code>CacheManager</code> on the <code>SecurityManager</code>, it will in turn set it on
the various Realms that implement CacheManagerAware as well (OO
delegation). For example, in shiro.ini:</p>
</div>
<div class="listingblock">
<div class="title">example shiro.ini CacheManager configuration</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-ini hljs" data-lang="ini">securityManager.realms = $myRealm1, $myRealm2, ..., $myRealmN
...
cacheManager = my.implementation.of.CacheManager
...
securityManager.cacheManager = $cacheManager
# at this point, the securityManager and all CacheManagerAware
# realms have been set with the cacheManager instance</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="cachemanager_implementations">CacheManager Implementations</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Shiro provides a number of out-of-the-box <code>CacheManager</code>
implementations that you might find useful instead of implementing your
own.</p>
</div>
<div class="sect2">
<h3 id="memoryconstrainedcachemanager"><code>MemoryConstrainedCacheManager</code></h3>
<div class="paragraph">
<p>The
<a href="static/current/apidocs/org/apache/shiro/cache/MemoryConstrainedCacheManager.html"><code>MemoryConstrainedCacheManager</code></a>
is a <code>CacheManager</code> 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 implement instead.</p>
</div>
<div class="paragraph">
<p>The <code>MemoryConstrainedCacheManager</code> manages <a href="static/current/apidocs/org/apache/shiro/cache/MapCache.html"><code>MapCache</code></a> instances, one <code>MapCache</code> instance per named cache.
Each <code>MapCache</code> instance is backed by a Shiro <a href="static/current/apidocs/org/apache/shiro/util/SoftHashMap.html"><code>SoftHashMap</code></a> which can auto-resize itself based on an application’s runtime memory constraints/needs (by leveraging JDK <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html"><code>SoftReference</code></a> instances).</p>
</div>
<div class="paragraph">
<p>Because the <code>MemoryConstrainedCacheManager</code> 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 <code>CacheManager</code> offerings below.</p>
</div>
<div class="listingblock">
<div class="title">MemoryConstrainedCacheManager shiro.ini configuration example</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-ini hljs" data-lang="ini">...
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
...
securityManager.cacheManager = $cacheManager</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="hazelcastcachemanager"><code>HazelcastCacheManager</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>TBD</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="ehcachemanager"><code>EhCacheManager</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>TBD</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="authorization_cache_invalidation">Authorization Cache Invalidation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Finally, note that
<a href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html"><code>AuthorizingRealm</code></a>
has a
<a 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>
</div>
</div>
</div>
<hr />
</div>
<div class="footer-padding"></div>
<div class="container-fluid pt-2 border-top" id="custom-footer">
<footer class="row justify-content-between align-items-center">
<div class=" col-md-5">
<div class="copyright-footer justify-content-start">
<a href="https://www.apache.org/foundation/contributing.html">Donate to the ASF</a>&nbsp;|&nbsp;
<a href="https://www.apache.org/licenses/LICENSE-2.0.html">License</a>&nbsp;
<p class="text-muted">Copyright &copy; 2008-2024 The Apache Software Foundation</p>
</div>
</div>
<div class="d-flex justify-content-center col-md-1">
<a class="btn btn-social"><span class="social-icon social-twitter"><i class="bi bi-twitter"></i></span></a>
<a class="btn btn-social"><span class="social-icon social-facebook"><i class="bi bi-facebook"></i></span></a>
<a class="btn btn-social"><span class="social-icon social-linkedin"><i class="bi bi-linkedin"></i></span></a>
</div>
<div class="d-flex justify-content-end col-md-4" id="editThisPage">
<input type="hidden" id="ghEditPage" value="https://github.com/apache/shiro-site/edit/main/src/site/content/caching.adoc"/>
</div>
<div class="d-flex col-md-2 justify-content-end" style="position: relative">
<div class="footer-shield"></div>
</div>
</footer>
</div>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="js/bootstrap.min.js"></script>
<script src="highlight.js-11.2.0/highlight.min.js"></script>
<script src="js/shiro.js"></script>
<script>
docReady(
addPageEditLink()
);
</script>
<script>hljs.highlightAll();</script>
</body>
</html>