blob: 774d5a98fb8229eceac9d560865609e643437bb3 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>About Cache Expiration and Invalidation | EclipseLink 2.5.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.17" />
<meta name="date" content="2013-10-03T10:37:15Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="About Cache Expiration and Invalidation" />
<meta name="relnum" content="2.5" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="cache005.htm" title="Previous" type="text/html" />
<link rel="next" href="cache007.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:mdbgdwjv8zu', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><div class="booktitle">Understanding EclipseLink,
<b>2.5</b><br /></font></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="cache005.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="cache007.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CHEEHFCI" name="CHEEHFCI"></a><a id="OTLCG00008" name="OTLCG00008"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About Cache Expiration and Invalidation</font></h1>
<p>By default, objects remain in the shared cache until they are explicitly deleted or garbage collected.</p>
<p>You can configure any entity with an <code>expiry</code> that lets you specify either the number of milliseconds after which an entity instance should expire from the cache, or a time of day that all instances of the entity class should expire from the cache. Expiry is set on the <code>@Cache</code> annotation or <code>&lt;cache&gt;</code> XML element, and can be configured in two ways:</p>
<ul>
<li>
<p><code>expiry</code>&mdash;The number of milliseconds after which an entity instance will expire.</p>
</li>
<li>
<p><code>expiryTimeOfDay</code>&mdash;A <code>@TimeOfDay</code> representing the 24-hour time at which all instances of the entity class will expire from the cache.</p>
</li>
</ul>
<p>When an instance expires, it is only invalidated in the cache. It is not removed from the cache, but when next accessed it will be refreshed from the database as part of the query that was used to access it.</p>
<p>The application can also explicitly invalidate objects in the cache using the JPA <code>Cache</code> API, or the EclipseLink <code>JpaCache</code> API.</p>
<p>Expiry can also be used in the query results cache. See <a href="cache008.htm#CDEBGAHD">About Query Results Cache.</a></p>
<p>Invalidation can also be used in a cluster through cache coordination, or from database events using database event notification. See <a href="cache011.htm#CDEGDGAA">Coordinated Cache and Clustering.</a></p>
<a id="OTLCG94334" name="OTLCG94334"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref66" name="sthref66"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Advanced Cache Invalidation</font></h2>
<p>Alternatively, you can configure any object with a <code>CacheInvalidationPolicy</code> that lets you specify, either with annotations or XML, under what circumstances a cached object is invalid. When any query attempts to read an invalid object, EclipseLink will go to the data source for the most up-to-date version of that object, and update the cache with this information.</p>
<p>For descriptions of the available <code>CacheInvalidationPolicy</code> instances, see "Setting Cache Expiration" in <em>Solutions Guide for EclipseLink</em>.</p>
<p>You can configure a cache invalidation policy in the following ways:</p>
<ul>
<li>
<p>At the project level that applies to all objects</p>
</li>
<li>
<p>At the descriptor level to override the project level configuration on a per-object basis</p>
</li>
<li>
<p>At the query level that applies to the results returned by the query</p>
</li>
</ul>
<p>If you configure a query to cache results in its own internal cache, the cache invalidation policy you configure at the query level applies to the query's internal cache in the same way it would apply to the session cache.</p>
<p>If you are using a coordinated cache you can customize how EclipseLink communicates the fact that an object has been declared invalid. See <a href="cache011.htm#CDEIBJCE">About Cache Coordination</a>.</p>
<p>The EclipseLink <code>CacheInvalidationPolicy</code> API offers a few advanced features that are not available through annotations or XML. It is also possible to define your own expiry or invalidation policy by defining your own <code>CacheInvalidationPolicy</code>. Advanced configuration can be done through using a <code>DescriptorCustomizer</code> to customize your entity's <code>ClassDescriptor</code>.</p>
<p>Here are a few of the <code>CacheInvalidationPolicy</code> advanced options:</p>
<ul>
<li>
<p><code>isInvalidationRandomized</code>&mdash;This allows the invalidation time to be randomized by 10% to avoid a large number of instances becoming invalid at the same time and causing a bottleneck in the database load. This is not used by default.</p>
</li>
<li>
<p><code>shouldRefreshInvalidObjectsOnClone</code>&mdash;This ensures that an invalid object accessed through a relationship from another object will be refreshed in the persistence context. This is enabled by default.</p>
</li>
<li>
<p><code>shouldUpdateReadTimeOnUpdate</code>&mdash;This updates an object's read time when the object is successfully updated. This is not enabled by default.</p>
</li>
</ul>
</div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="cache005.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="cache007.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2012 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>