Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Type and Size"

m (Guidelines for Configuring the Cache and Identity Maps)
(What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types)
 
(36 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Cache Type and Size=
+
{{EclipseLink_UserGuide
EclipseLink preserves object identity through its cache using the primary key attributes of a persistent entity. These attributes may or may not be assigned through sequencing (see [[Introduction%20to%20Projects (ELUG)#Projects and Sequencing|Projects and Sequencing]]). In a Java application, object identity is preserved if each object in memory is represented by one, and only one, object instance. Multiple retrievals of the same object return references to the same object instance–not multiple copies of the same object.
+
|info=y
 +
|toc=y
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 +
|api=y
 +
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheType.html CacheType]
 +
|nativeapi=y
 +
|nativeapis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/CachePolicy.html CachePolicy]
 +
|examples=y
 +
|example=
 +
*[[EclipseLink/Examples/JPA/Caching|How to use EclipseLink Caching]]
 +
}}
  
Maintaining object identity is extremely important when the application's object model contains circular references between objects. You must ensure that the two objects are referencing each other directly, rather than copies of each other. Object identity is important when multiple parts of the application may be modifying the same object simultaneously.
+
=Cache Type and Size=
 
+
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.
We recommend that you always maintain object identity. Disable object identity only if absolutely necessary, for example, for read-only objects (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Read-Only Descriptors]]).
+
  
You can configure how object identity is managed on a class-by-class basis. The <tt>ClassDescriptor</tt> object provides the cache and identity map options described in this table.
+
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 garbage collected from memory (unless 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.
  
  
 
<span id="Table 98-1"></span>
 
<span id="Table 98-1"></span>
''''' Cache and Identity Map Options'''''
+
''''' Cache Options'''''
 
+
{| class="HRuleFormal" dir="ltr" title="Cache Options" summary="This table describes the cache options provided." border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
{| class="HRuleFormal" dir="ltr" title="Cache and Identity Map Options" summary="This table describes the cache and identity map options providedd by the Descriptor object." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
! id="r1c1-t3" align="left" valign="bottom" | '''Option (Identity Map)'''
+
! id="r1c1-t3" align="left" valign="bottom" | '''Option (cache type)'''
! id="r1c2-t3" align="left" valign="bottom" | '''Caching'''
+
! id="r1c3-t3" align="left" valign="bottom" | '''Guaranteed Identity'''
+
 
! id="r1c4-t3" align="left" valign="bottom" | '''Memory Use'''
 
! id="r1c4-t3" align="left" valign="bottom" | '''Memory Use'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
[[#Full Identity Map|Full Identity Map]]<br />
+
[[#FULL|FULL]]<br />
| headers="r2c1-t3 r1c2-t3" align="left" |
+
Yes
+
| headers="r2c1-t3 r1c3-t3" align="left" |
+
Yes
+
 
| headers="r2c1-t3 r1c4-t3" align="left" |
 
| headers="r2c1-t3 r1c4-t3" align="left" |
 
Very High
 
Very High
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
[[#Weak Identity Map|Weak Identity Map]]<br />
+
[[#WEAK|WEAK]]<br />
| headers="r3c1-t3 r1c2-t3" align="left" |
+
Yes
+
| headers="r3c1-t3 r1c3-t3" align="left" |
+
Yes
+
 
| headers="r3c1-t3 r1c4-t3" align="left" |
 
| headers="r3c1-t3 r1c4-t3" align="left" |
 
Low
 
Low
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
[[#Soft Identity Map|Soft Identity Map]]<br />
+
[[#SOFT|SOFT]]<br />
| headers="r4c1-t3 r1c2-t3" align="left" |
+
Yes
+
| headers="r4c1-t3 r1c3-t3" align="left" |
+
Yes
+
 
| headers="r4c1-t3 r1c4-t3" align="left" |
 
| headers="r4c1-t3 r1c4-t3" align="left" |
 
High
 
High
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
[[#Soft Cache Weak Identity Map and Hard Cache Weak Identity Map|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]]<br />
+
[[#SOFT_CACHE and HARD_CACHE|SOFT_CACHE and HARD_CACHE]]<br />
| headers="r5c1-t3 r1c2-t3" align="left" |
+
Yes
+
| headers="r5c1-t3 r1c3-t3" align="left" |
+
Yes
+
 
| headers="r5c1-t3 r1c4-t3" align="left" |
 
| headers="r5c1-t3 r1c4-t3" align="left" |
Medium-high
+
Medium
|- align="left" valign="top"
+
| id="r6c1-t3" headers="r1c1-t3" align="left" |
+
[[#No Identity Map|No Identity Map]]<br />
+
| headers="r6c1-t3 r1c2-t3" align="left" |
+
No
+
| headers="r6c1-t3 r1c3-t3" align="left" |
+
No
+
| headers="r6c1-t3 r1c4-t3" align="left" |
+
None
+
 
|}
 
|}
  
 +
There are two other options, <code>NONE</code>, and <code>CACHE</code>.  These options are not recommend.
  
For more information, see [[#Guidelines for Configuring the Cache and Identity Maps|Guidelines for Configuring the Cache and Identity Maps]].
+
For more information, see [[#Guidelines for Configuring the Cache Type|Guidelines for Configuring the Cache Type]].
  
 +
==FULL==
 +
This option provides full caching: objects are never flushed from memory unless they are deleted.
  
====Full Identity Map====
+
It caches all objects and does not remove them even if memory is low. 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 for entities with a large number of instances.
This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.
+
  
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.
+
We recommend using FULL only when the data set size is small and memory is in large supply.
  
We recommend using this identity map when the data set size is small and memory is in large supply.
+
==WEAK==
 +
This option only caches objects that have not been garbage collected.  Any object still referenced by the application will still be cached.
  
 +
The weak cache uses less memory than the full cache 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).
  
====Weak Identity Map====
+
==SOFT==
 +
This option is similar to the weak cache, 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.
  
This option is similar to the full identity map, except that the map holds the objects by using weak references. This method allows full garbage collection and provides full caching and guaranteed identity.
+
The soft cache allows for full caching of the objects, while still allowing the JVM to garbage collect the objects if memory is low.
  
The weak identity map 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).
+
==SOFT_WEAK and HARD_WEAK==
 +
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.
  
 +
The soft-weak cache and hard-weak 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 <tt>size</tt> option. You should set the cache size to number of objects you wish to hold in your transaction.
  
====Soft Identity Map====
+
We recommend using this cache in most circumstances as a means to control memory used by the cache.
  
This option is similar to the weak identity map, except that the map uses soft references instead of weak references. This method allows full garbage collection and provides full caching and guaranteed identity.
+
For more information, see [[#What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types|What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types]].
  
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.
+
==NONE and CACHE==
 +
NONE and CACHE options do not preserve object identity and should only be used in very specific circumstances.  NONE does not cache any objects.  CACHE only caches a fixed number of objects in an LRU fashion.  These cache types should only be used if there are no relationships to the objects.
  
 +
We do not recommend using these options. To disable caching set the cache <code>isolation</code> to <code>ISOLATED</code> instead.
  
====Soft Cache Weak Identity Map and Hard Cache Weak Identity Map====
+
==Guidelines for Configuring the Cache Type==
  
These options are similar to the weak identity map except that they maintain a most frequently used subcache. The subcache uses soft or hard references to ensure that these objects are garbage-collected only if the system is low on memory.
+
You can configure the cache type for the persistence unit, or for a specific entity.
  
The soft cache weak identity map and hard cache weak identity map 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 subcache is proportional to the size of the identity map as specified by the <tt>ClassDescriptor</tt> method <tt>setIdentityMapSize</tt>. You should set this cache size to be as large as the maximum number of objects (of the same type) referenced within a transaction (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Type and Size at the Descriptor Level|Configuring Cache Type and Size at the Descriptor Level]]).
+
Use the following guidelines when configuring your cache type:
 +
* For objects with a long life span, use a <tt>SOFT</tt>, <tt>SOFT_WEAK</tt> or <tt>HARD_WEAK</tt> cache type. For more information on when to choose one or the other, see [[#What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types|What you may need to Know About the Internals of Weak, Soft, and Hard Cache Types]].
 +
* For objects with a short life span, use a <tt>WEAK</tt> cache type.
 +
* For objects with a long life span, that have few instances, such as reference data, use a <tt>FULL</tt> cache type.<br />
  
We recommend using this identity map in most circumstances as a means to control memory used by the cache.
+
{{EclipseLink_Warning
 
+
|warning=Use the <tt>FULL</tt> cache type only if the class has a small number of finite instances. Otherwise, a memory leak will occur.'''
For more information, see [[#What you may need to Know About the Internals of Weak, Soft, and Hard Identity Maps|What you may need to Know About the Internals of Weak, Soft, and Hard Identity Maps]].
+
}}
 
+
* If caching is not required, or not desired that disable the shared cache by setting the cache <tt>isolation</tt> to <tt>ISOLATED</tt>.
====No Identity Map====
+
 
+
This option does not preserve object identity and does not cache objects.
+
 
+
We do not recommend using the no identity map option. Instead, review the alternatives of cache invalidation and isolated caching.
+
 
+
 
+
====Guidelines for Configuring the Cache and Identity Maps====
+
 
+
You can configure the cache at the project ([[Configuring%20a%20Project%20(ELUG)#Configuring Cache Type and Size at the Project Level|Configuring Cache Type and Size at the Project Level]]) or descriptor ([[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Type and Size at the Descriptor Level|Configuring Cache Type and Size at the Descriptor Level]]) level.
+
 
+
Use the following guidelines when configuring your cache and identity map:
+
* If objects with a long life span and object identity are important, use a <tt>SoftIdentityMap</tt>, <tt>SoftCacheWeakIdentityMap</tt> or <tt>HardCacheWeakIdentityMap</tt> policy. For more information on when to choose one or the other, see [[#What you may need to Know About the Internals of Weak, Soft, and Hard Identity Maps|What you may need to Know About the Internals of Weak, Soft, and Hard Identity Maps]].
+
* If object identity is important, but caching is not, use a <tt>WeakIdentityMap</tt> policy.
+
* If an object has a long life span or requires frequent access, or object identity is important, use a <tt>FullIdentityMap</tt> policy.<br />
+
 
+
{| class="NoteWarn oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''WARNING:''' Use the <tt>FullIdentityMap</tt> only if the class has a small number of finite instances. Otherwise, a memory leak will occur.'''
+
|}<br />
+
* If an object has a short life span or requires frequent access, and identity is not important, use a <tt>CacheIdentityMap</tt> policy.
+
* If objects are discarded immediately after being read from the database, such as in a batch operation, use a <tt>NoIdentityMap</tt> policy. The <tt>NoIdentityMap</tt> does not preserve object identity.
+
  
{{EclipseLink:Note
+
{{EclipseLink_Note
|note=We do not recommend the use of <tt>CacheIdentityMap</tt> and <tt>NoIdentityMap</tt> policies.
+
|note=We do not recommend the use of <tt>CACHE</tt> and <tt>NONE</tt> cache types.
 
}}
 
}}
  
====What You May Need to Know About the Internals of Weak, Soft, and Hard Identity Maps====
+
==What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types==
  
The <tt>WeakIdentiyMap</tt> and <tt>SoftIdentityMap</tt> 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 and soft reference is garbage collected - is determined by the JVM. In general one could expect a weak reference to be garbage collected on each JVM garbage collector, and a soft reference to be garbage collected when the JVM determines memory is low.
+
The <tt>WEAK</tt> and <tt>SOFT</tt> 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 and soft reference is garbage collected - is determined by the JVM. In general one could expect a weak reference to be garbage collected on each JVM garbage collection, and a soft reference to be garbage collected when the JVM determines memory is low.
  
The <tt>SoftCacheWeakIdentityMap</tt> and <tt>HardCacheWeakIdentityMap</tt> types of identity map contain the following two caches:
+
The <tt>SOFT_WEAK</tt> and <tt>HARD_WEAK</tt> cache types contain the following two caches:
  
 
* Reference cache: implemented as a <tt>LinkedList</tt> that contains soft or hard references, respectively.
 
* Reference cache: implemented as a <tt>LinkedList</tt> that contains soft or hard references, respectively.
* Weak cache: implemented as a <tt>HashMap</tt> that contains weak references.
+
* Weak cache: implemented as a <tt>Map</tt> that contains weak references.
  
When you create a <tt>SoftCacheWeakIdentityMap</tt> or <tt>HardCacheWeakIdentityMap</tt> with a specified size, the reference cache <tt>LinkedList</tt> is exactly this size. The weak cache <tt>HashMap</tt> is initialized to 100 percent of the specified 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.
+
When you create a <tt>SOFT_WEAK</tt> or <tt>HARD_WEAK</tt> cache with a specified size, the reference cache <tt>LinkedList</tt> is exactly this size. The weak cache <tt>Map</tt> 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.
  
 
Because the reference cache is implemented as a <tt>LinkedList</tt>, 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.
 
Because the reference cache is implemented as a <tt>LinkedList</tt>, 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.
  
The <tt>SoftCacheWeakIdentityMap</tt> and <tt>HardCacheWeakIdentityMap</tt> are essentially the same type of identity map. The <tt>HardCacheWeakIdentityMap</tt> was constructed to work around an issue with some JVMs.
+
The <tt>SOFT_WEAK</tt> and <tt>HARD_WEAK</tt> are essentially the same type of cache. The <tt>HARD_WEAK</tt> was constructed to work around an issue with some JVMs.
 +
 
 +
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, we recommend that you use the <tt>HARD_WEAK</tt>. It is identical to the <tt>SOFT_WEAK</tt> except that it uses hard references in the reference cache. This guarantees that your application will benefit from the performance improvement provided by it.
  
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, we recommend that you use the <tt>HardCacheWeakIdentityMap</tt>. It is identical to the <tt>SoftCacheWeakIdentityMap</tt> except that it uses hard references in the reference cache. This guarantees that your application will benefit from the performance improvement provided by it.
+
When an object in a <tt>SOFT_WEAK</tt> or <tt>HARD_WEAK</tt> 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.
  
When an object in a <tt>HardCacheWeakIdentityMap</tt> or <tt>SoftCacheWeakIdentityMap</tt> 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.
+
==Cache Type Examples==
 +
======''@Cache type annotation example''======
 +
<source lang="java">
 +
...
 +
@Entity
 +
@Cache(
 +
  type=CacheType.SOFT,
 +
  size=10000
 +
)
 +
public class Employee {
 +
  ...
 +
}
 +
</source>
  
 +
======''Cache type XML example''======
 +
<source lang="xml">
 +
<?xml version="1.0"?>
 +
<entity-mappings
 +
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
 +
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
 +
version="2.4">
 +
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
 +
        <cache type="SOFT" size="10000"/>
 +
    </entity>
 +
</entity-mappings>
 +
</source>
  
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Shared and Isolated|Shared and Isolated]]
+
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Shared and Isolated|Shared, Isolated, Protected, Weak, and Read-only Cache]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Expiration|Expiration]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Expiration|Cache Expiration and Invalidation]]
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Cache]]}}
+
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
 +
|version=2.4 DRAFT}}

Latest revision as of 09:51, 13 May 2013

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API

Elug api package icon.png Native API

Cache Type and Size

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.

By default EclipseLink uses a SOFT_CACHE 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 garbage collected from memory (unless the CACHE type is used, but this is not recommended). The cache size of the SOFT_CACHE and HARD_CACHE is also the size of the soft or hard sub-cache that can determine a minimum number of objects to hold in memory.


Cache Options

Option (cache type) Memory Use

FULL

Very High

WEAK

Low

SOFT

High

SOFT_CACHE and HARD_CACHE

Medium

There are two other options, NONE, and CACHE. These options are not recommend.

For more information, see Guidelines for Configuring the Cache Type.

FULL

This option provides full caching: objects are never flushed from memory unless they are deleted.

It caches all objects and does not remove them even if memory is low. 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 for entities with a large number of instances.

We recommend using FULL only when the data set size is small and memory is in large supply.

WEAK

This option only caches objects that have not been garbage collected. Any object still referenced by the application will still be cached.

The weak cache uses less memory than the full cache 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).

SOFT

This option is similar to the weak cache, 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.

The soft cache allows for full caching of the objects, while still allowing the JVM to garbage collect the objects if memory is low.

SOFT_WEAK and HARD_WEAK

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.

The soft-weak cache and hard-weak 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 number of objects you wish to hold in your transaction.

We recommend using this cache in most circumstances as a means to control memory used by the cache.

For more information, see What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types.

NONE and CACHE

NONE and CACHE options do not preserve object identity and should only be used in very specific circumstances. NONE does not cache any objects. CACHE only caches a fixed number of objects in an LRU fashion. These cache types should only be used if there are no relationships to the objects.

We do not recommend using these options. To disable caching set the cache isolation to ISOLATED instead.

Guidelines for Configuring the Cache Type

You can configure the cache type for the persistence unit, or for a specific entity.

Use the following guidelines when configuring your cache type:

Elug warning icon.png

Warning: Use the FULL cache type only if the class has a small number of finite instances. Otherwise, a memory leak will occur.

  • If caching is not required, or not desired that disable the shared cache by setting the cache isolation to ISOLATED.

Elug note icon.png

Note: We do not recommend the use of CACHE and NONE cache types.

What You May Need to Know About the Internals of Weak, Soft, and Hard Cache Types

The WEAK and SOFT 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 and soft reference is garbage collected - is determined by the JVM. In general one could expect a weak reference to be garbage collected on each JVM garbage collection, and a soft reference to be garbage collected when the JVM determines memory is low.

The SOFT_WEAK and HARD_WEAK cache types contain the following two caches:

  • Reference cache: implemented as a LinkedList that contains soft or hard references, respectively.
  • Weak cache: implemented as a Map that contains weak references.

When you create a SOFT_WEAK or HARD_WEAK cache with a specified size, the reference cache LinkedList is exactly this size. The weak cache Map 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.

Because the reference cache is implemented as a LinkedList, 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.

The SOFT_WEAK and HARD_WEAK are essentially the same type of cache. The HARD_WEAK was constructed to work around an issue with some JVMs.

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, we recommend that you use the HARD_WEAK. It is identical to the SOFT_WEAK except that it uses hard references in the reference cache. This guarantees that your application will benefit from the performance improvement provided by it.

When an object in a SOFT_WEAK or HARD_WEAK 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.

Cache Type Examples

@Cache type annotation example
...
@Entity
@Cache(
  type=CacheType.SOFT,
  size=10000
)
public class Employee {
  ...
}
Cache type XML example
<?xml version="1.0"?>
<entity-mappings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
	version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <cache type="SOFT" size="10000"/>
    </entity>
</entity-mappings>


Eclipselink-logo.gif
Version: 2.4 DRAFT
Other versions...