Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Expiration"

m (Cache Expiration)
(Cache Expiration and Invalidation)
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Cache Expiration=
+
{{EclipseLink_UserGuide
By default, objects remain in the session cache until they are explicitly deleted (see [[Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)|Deleting Objects]]) or garbage collected when using a weak identity map (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Type and Size at the Project Level]]).
+
|info=y
 +
|toc=n
 +
|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/TimeOfDay.html @TimeOfDay]
 +
|nativeapi=y
 +
|nativeapis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/CachePolicy.html CachePolicy]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/invalidation/CacheInvalidationPolicy.html CacheInvalidationPolicy]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/invalidation/DailyCacheInvalidationPolicy.html DailyCacheInvalidationPolicy]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/invalidation/TimeToLiveCacheInvalidationPolicy.html TimeToLiveCacheInvalidationPolicy]
 +
|examples=y
 +
|example=
 +
*[[EclipseLink/Examples/JPA/Caching|How to use caching]]
 +
|
 +
}}
 +
=Cache Expiration and Invalidation=
 +
By default, entities remain in the shared cache until they are explicitly deleted or garbage collected.
  
Alternatively, you can configure any object with a <tt>CacheInvalidationPolicy</tt> that lets you specify, either automatically or manually, 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.
+
You can configure any entity with a <tt>expiry</tt> 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 <tt>@Cache</tt> annotation or <tt><cache></tt> XML element, and can be configured in two ways:
  
You can use any of the following <tt>CacheInvalidationPolicy</tt> instances:
+
* <tt>expiry</tt> - The number of milliseconds to expiry an entity instance in the cache after it has been read.
 +
* <tt>expiryTimeOfDay</tt> - The <tt>@TimeOfDay</tt> represent the 24h time of day to expiry all instances of the entity class in the cache.
  
* <tt>DailyCacheInvalidationPolicy</tt><nowiki>: the object is automatically flagged as invalid at a specified time of day.</nowiki>
+
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.
* <tt>NoExpiryCacheInvalidationPolicy</tt><nowiki>: the object can only be flagged as invalid by explicitly calling </nowiki><tt>org.eclipse.persistence.sessions.IdentityMapAccessor</tt> method <tt>invalidateObject</tt>.
+
* <tt>TimeToLiveCacheInvalidationPolicy</tt><nowiki>: the object is automatically flagged as invalid after a specified time period has elapsed since the object was read.</nowiki>
+
  
You can configure a cache invalidation policy in the following ways:
+
The application can also explicitly invalidate objects in the cache using the JPA <tt>Cache</tt> API, or the EclipseLink <tt>JpaCache</tt> API (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Cache API|Cache API]]).
  
* At the project level that applies to all objects ( [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Expiration at the Project Level]])
+
Expiry can also be used in the query results cache (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Query Cache|Query Results Cache]]).
* At the descriptor level to override the project level configuration on a per-object basis ( [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Cache Expiration at the Descriptor Level]])
+
* At the query level that applies to the results returned by the query ([[Using%20Advanced%20Query%20API%20(ELUG)|How to Configure Cache Expiration at the Query Level]])
+
  
If you configure a query to cache results in its own internal cache (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Cache Query Results in the Query 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.
+
Invalidation can also be used in a cluster through cache coordination (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Coordination|Clustering and Cache Coordination]]), or from database events using database event notification (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/DatabaseEvents|Database Event Notification and Oracle DCN/QCN]]).
  
If you are using a coordinated cache (see [[#Cache Coordination|Cache Coordination]]), you can customize how EclipseLink communicates the fact that an object has been declared invalid. For more information, see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Coordination Change Propagation at the Descriptor Level|Configuring Cache Coordination Change Propagation at the Descriptor Level]].
+
======''Cache expiry annotation example''======
 +
<source lang="java">
 +
...
 +
@Entity
 +
@Cache(
 +
  expiry=600000 // 10 minutes
 +
)
 +
public class Employee {
 +
  ...
 +
}
 +
</source>
  
 +
<source lang="java">
 +
...
 +
@Entity
 +
@Cache(
 +
  expiryTimeOfDay=@TimeOfDay(hour=3) // 3:00 AM
 +
)
 +
public class Project {
 +
  ...
 +
}
 +
</source>
 +
 +
======''Cache expiry 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>
 +
            <expiry>600000</expiry>
 +
        </cache>
 +
    </entity>
 +
    <entity name="Project" class="org.acme.Project" access="FIELD">
 +
        <cache>
 +
            <expiry-time-of-day hour="3"/>
 +
        </cache>
 +
    </entity>
 +
</entity-mappings>
 +
</source>
 +
 +
==Advanced Cache Invalidation==
 +
EclipseLink's cache expiry and invalidation support is provided through the <tt>CacheInvalidationPolicy</tt> class and its subclasses.  The EclipseLink 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 <tt>CacheInvalidationPolicy</tt>. Advanced configuration can be done through using a <tt>DescriptorCustomizer</tt> to customize your entity's <tt>ClassDescriptor</tt>.
 +
 +
<tt>CacheInvalidationPolicy</tt> advanced options:
 +
* <tt>isInvalidationRandomized</tt> - 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.
 +
* <tt>shouldRefreshInvalidObjectsOnClone</tt> - This ensures that an invalid object accessed through a relationship from another object will be refresh in the persistence context.  This is enabled by default.
 +
* <tt>shouldUpdateReadTimeOnUpdate</tt> - This updates an objects read time when the object is successfully updated.  This is not enabled by default.
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Type and Size|Type and Size]]
+
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Type and Size|Cache Type and Size]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Coordination|Coordination]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Coordination|Clustering and Cache Coordination]]
|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 11:16, 29 May 2012

EclipseLink JPA

Cache Expiration and Invalidation

By default, entities remain in the shared cache until they are explicitly deleted or garbage collected.

You can configure any entity with a expiry 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 @Cache annotation or <cache> XML element, and can be configured in two ways:

  • expiry - The number of milliseconds to expiry an entity instance in the cache after it has been read.
  • expiryTimeOfDay - The @TimeOfDay represent the 24h time of day to expiry all instances of the entity class in the cache.

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.

The application can also explicitly invalidate objects in the cache using the JPA Cache API, or the EclipseLink JpaCache API (see Cache API).

Expiry can also be used in the query results cache (see Query Results Cache).

Invalidation can also be used in a cluster through cache coordination (see Clustering and Cache Coordination), or from database events using database event notification (see Database Event Notification and Oracle DCN/QCN).

Cache expiry annotation example
...
@Entity
@Cache(
  expiry=600000 // 10 minutes
)
public class Employee {
  ...
}
...
@Entity
@Cache(
  expiryTimeOfDay=@TimeOfDay(hour=3) // 3:00 AM
)
public class Project {
  ...
}
Cache expiry 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>
            <expiry>600000</expiry>
        </cache>
    </entity>
    <entity name="Project" class="org.acme.Project" access="FIELD">
        <cache>
            <expiry-time-of-day hour="3"/>
        </cache>
    </entity>
</entity-mappings>

Advanced Cache Invalidation

EclipseLink's cache expiry and invalidation support is provided through the CacheInvalidationPolicy class and its subclasses. The EclipseLink 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 CacheInvalidationPolicy. Advanced configuration can be done through using a DescriptorCustomizer to customize your entity's ClassDescriptor.

CacheInvalidationPolicy advanced options:

  • isInvalidationRandomized - 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.
  • shouldRefreshInvalidObjectsOnClone - This ensures that an invalid object accessed through a relationship from another object will be refresh in the persistence context. This is enabled by default.
  • shouldUpdateReadTimeOnUpdate - This updates an objects read time when the object is successfully updated. This is not enabled by default.

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