blob: b08fa3d67b5cf0439717d243d8df7c3144804784 [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 Type and Size | 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 Type and Size" />
<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="cache001.htm" title="Previous" type="text/html" />
<link rel="next" href="cache003.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="cache001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="cache003.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="CHEFCFEG" name="CHEFCFEG"></a><a id="OTLCG00011" name="OTLCG00011"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About Cache Type and Size</font></h1>
<p>EclipseLink provides several different cache types which have different memory requirements. The size of the cache (in number of cached objects) can also be configured. The cache type and size to use depends on the application, the possibility of stale data, the amount of memory available in the JVM and on the machine, the garbage collection cost, and the amount of data in the database.</p>
<p>By default, EclipseLink uses a <code>SOFT_CACHE</code> with an initial size of 100 objects. The cache size is not fixed, but just the initial size, EclipseLink will never eject an object from the cache until it has been garbage collected from memory. It will eject the object if the <code>CACHE</code> type is used, but this is not recommended. The cache size of the <code>SOFT_CACHE</code> and <code>HARD_CACHE</code> is also the size of the soft or hard sub-cache that can determine a minimum number of objects to hold in memory.</p>
<p>You can configure how object identity is managed on a class-by-class basis. The <code>ClassDescriptor</code> object provides the cache and identity map options described in <a href="#CHEJBDHH">Table 9-1</a>.</p>
<div class="tblhruleformal"><a id="OTLCG93799" name="OTLCG93799"></a><a id="sthref63" name="sthref63"></a><a id="CHEJBDHH" name="CHEJBDHH"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 9-1 Cache and Identity Map Options</font></em></strong></p>
<table class="HRuleFormal" title="Cache and Identity Map Options" summary="This table describes the cache and identity map options providedd by the Descriptor object." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="*" />
<col width="14%" />
<col width="26%" />
<col width="18%" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t5"><font face="Arial, Helvetica, sans-serif"><strong>Option (Cache Type)</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t5"><font face="Arial, Helvetica, sans-serif"><strong>Caching</strong></font></th>
<th align="left" valign="bottom" id="r1c3-t5"><font face="Arial, Helvetica, sans-serif"><strong>Guaranteed Identity</strong></font></th>
<th align="left" valign="bottom" id="r1c4-t5"><font face="Arial, Helvetica, sans-serif"><strong>Memory Use</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t5" headers="r1c1-t5">
<p><a href="#CHEHGEEB">FULL Cache Type</a></p>
<br /></td>
<td align="left" headers="r2c1-t5 r1c2-t5">
<p>Yes</p>
</td>
<td align="left" headers="r2c1-t5 r1c3-t5">
<p>Yes</p>
</td>
<td align="left" headers="r2c1-t5 r1c4-t5">
<p>Very High</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t5" headers="r1c1-t5">
<p><a href="#CHEGIBAC">WEAK Cache Type</a></p>
<br /></td>
<td align="left" headers="r3c1-t5 r1c2-t5">
<p>Yes</p>
</td>
<td align="left" headers="r3c1-t5 r1c3-t5">
<p>Yes</p>
</td>
<td align="left" headers="r3c1-t5 r1c4-t5">
<p>Low</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t5" headers="r1c1-t5">
<p><a href="#CACHBJGE">SOFT Cache Type</a></p>
<br /></td>
<td align="left" headers="r4c1-t5 r1c2-t5">
<p>Yes</p>
</td>
<td align="left" headers="r4c1-t5 r1c3-t5">
<p>Yes</p>
</td>
<td align="left" headers="r4c1-t5 r1c4-t5">
<p>High</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t5" headers="r1c1-t5">
<p><a href="#CHEJDCBH">SOFT_CACHE and HARD_CACHE Cache Type</a></p>
<br /></td>
<td align="left" headers="r5c1-t5 r1c2-t5">
<p>Yes</p>
</td>
<td align="left" headers="r5c1-t5 r1c3-t5">
<p>Yes</p>
</td>
<td align="left" headers="r5c1-t5 r1c4-t5">
<p>Medium-high</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" -->
<p>There are two other options, <code>NONE</code>, and <code>CACHE</code>. These options are not recommend.</p>
<a id="CHEHGEEB" name="CHEHGEEB"></a><a id="OTLCG00180" name="OTLCG00180"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">FULL Cache Type</font></h2>
<p>This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.</p>
<p>It caches all objects and does not remove them. Cache size doubles whenever the maximum size is reached. This method may be memory-intensive when many objects are read. Do not use this option on batch operations.</p>
<p>Oracle recommends using this identity map when the data set size is small and memory is in large supply.</p>
</div>
<!-- class="sect2" -->
<a id="CHEGIBAC" name="CHEGIBAC"></a><a id="OTLCG00181" name="OTLCG00181"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">WEAK Cache Type</font></h2>
<p>This option only caches objects that have not been garbage collected. Any object still referenced by the application will still be cached.</p>
<p>The weak cache type uses less memory than full identity map but also does not provide a durable caching strategy across client/server transactions. Objects are available for garbage collection when the application no longer references them on the server side (that is, from within the server JVM).</p>
</div>
<!-- class="sect2" -->
<a id="CACHBJGE" name="CACHBJGE"></a><a id="OTLCG93800" name="OTLCG93800"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">SOFT Cache Type</font></h2>
<p>This option is similar to the weak cache type, except that the cache uses soft references instead of weak references. Any object still referenced by the application will still be cached, and objects will only be removed from the cache when memory is low.</p>
<p>The soft identity map allows for optimal caching of the objects, while still allowing the JVM to garbage collect the objects if memory is low.</p>
</div>
<!-- class="sect2" -->
<a id="CHEJDCBH" name="CHEJDCBH"></a><a id="OTLCG00182" name="OTLCG00182"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">SOFT_CACHE and HARD_CACHE Cache Type</font></h2>
<p>These options are similar to the weak cache except that they maintain a most frequently used sub-cache. The sub-cache uses soft or hard references to ensure that these objects are not garbage collected, or only garbage collected only if the JVM is low on memory.</p>
<p>The soft cache and hard cache provide more efficient memory use. They release objects as they are garbage-collected, except for a fixed number of most recently used objects. Note that weakly cached objects might be flushed if the transaction spans multiple client/server invocations. The size of the sub-cache is proportional to the size of the cache as specified by the size option. You should set the cache size to the number of objects you wish to hold in your transaction.</p>
<p>Oracle recommends using this cache in most circumstances as a means to control memory used by the cache.</p>
</div>
<!-- class="sect2" -->
<a id="CHEEBFCI" name="CHEEBFCI"></a><a id="OTLCG00183" name="OTLCG00183"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">NONE and CACHE</font></h2>
<p><code>NONE</code> and <code>CACHE</code> options do not preserve object identity and should only be used in very specific circumstances. <code>NONE</code> does not cache any objects. <code>CACHE</code> only caches a fixed number of objects in an <code>LRU</code> fashion. These cache types should only be used if there are no relationships to the objects.Oracle does not recommend using these options. To disable caching set the cache isolation to <code>ISOLATED</code> instead.</p>
</div>
<!-- class="sect2" -->
<a id="OTLCG94332" name="OTLCG94332"></a>
<div class="sect2"><a id="sthref64" name="sthref64"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Guidelines for Configuring the Cache and Identity Maps</font></h2>
<p>Use the following guidelines when configuring your cache type:</p>
<ul>
<li>
<p>For objects with a long life span, use a <code>SOFT</code>, <code>SOFT_CACHE</code> or <code>HARD_CACHE</code> cache type. For more information on when to choose one or the other, see <a href="#CDEJFBEH">About the Internals of Weak, Soft, and Hard Cache Types.</a>.</p>
</li>
<li>
<p>For objects with a short life span, use a <code>WEAK</code> cache type.</p>
</li>
<li>
<p>For objects with a long life span, that have few instances, such as reference data, use a <code>FULL</code> cache type.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>Use the <code>FULL</code> cache type only if the class has a small number of finite instances. Otherwise, a memory leak will occur.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</li>
<li>
<p>If caching is not required or desired, disable the shared cache by setting the cache isolation to <code>ISOLATED</code>.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>Oracle does not recommend the use of <code>CACHE</code> and <code>NONE</code> cache types.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</li>
</ul>
<p>See <a href="#CDEJFBEH">About the Internals of Weak, Soft, and Hard Cache Types.</a></p>
<a id="CDEJFBEH" name="CDEJFBEH"></a><a id="OTLCG94333" name="OTLCG94333"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">About the Internals of Weak, Soft, and Hard Cache Types</font></h3>
<p>The <code>WEAK</code> and <code>SOFT</code> cache types use JVM weak and soft references to ensure that any object referenced by the application is held in the cache. Once the application releases its reference to the object, the JVM is free to garbage collection the objects. When a weak or a soft reference is garbage collected is determined by the JVM. In general, expect a weak reference to be garbage collected with each JVM garbage-collection operation.</p>
<p>The <code>SOFT_CACHE</code> and <code>HARD_CACHE</code> cache types contain the following two caches:</p>
<ul>
<li>
<p>Reference cache: implemented as a <code>LinkedList</code> that contains soft or hard references, respectively.</p>
</li>
<li>
<p>Weak cache: implemented as a <code>Map</code> that contains weak references.</p>
</li>
</ul>
<p>When you create a <code>SOFT_CACHE</code> or <code>HARD_CACHE</code> cache with a specified size, the reference cache <code>LinkedList</code> is exactly this size. The weak cache <code>Map</code> has the size as its initial size: the weak cache will grow when more objects than the specified size are read in. Because EclipseLink does not control garbage collection, the JVM can reap the weakly held objects whenever it sees fit.</p>
<p>Because the reference cache is implemented as a <code>LinkedList</code>, new objects are added to the end of the list. Because of this, it is by nature a least recently used (LRU) cache: fixed size, object at the top of the list is deleted, provided the maximum size has been reached.</p>
<p>The <code>SOFT_CACHE</code> and <code>HARD_CACHE</code> are essentially the same type of cache. The <code>HARD_CACHE</code> was constructed to work around an issue with some JVMs.</p>
<p>If your application reaches a low system memory condition frequently enough, or if your platform's JVM treats weak and soft references the same, the objects in the reference cache may be garbage-collected so often that you will not benefit from the performance improvement provided by it. If this is the case, Oracle recommends that you use the <code>HARD_CACHE</code>. It is identical to the <code>SOFT_CACHE</code> except that it uses hard references in the reference cache. This guarantees that your application will benefit from the performance improvement provided by it.</p>
<p>When an object in a <code>HARD_CACHE</code> or <code>SOFT_CACHE</code> is pushed out of the reference cache, it gets put in the weak cache. Although it is still cached, EclipseLink cannot guarantee that it will be there for any length of time because the JVM can decide to garbage-collect weak references at anytime.</p>
</div>
<!-- class="sect3" --></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="cache001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="cache003.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>