Difference between revisions of "EclipseLink/UserGuide/JPA/2.4/a cache"

Revision as of 14:17, 19 June 2012

Beta Draft: 2012-06-18

@Cache

Use @Cache) to configure the EclipseLink object cache. By default, EclipseLink uses a shared object cache to cache all objects. You can configure the caching type and options on a per class basis to allow optimal caching.

Annotation Elements

Table 2-4 describes this annotation's elements.

Table 2-4 @Cache Annotation Elements

Usage

You can define the @Cache annotation on the following:

• @Entity
• @MappedSuperclass
• the root of the inheritance hierarchy (if applicable)

If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. If you define the @Cache annotation on @Embeddable EclipseLink will throw an exception.

Caching in EclipseLink

The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:

• Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.
• Manage locking and isolation level.
• Manage object identity.

For more information about the EclipseLink cache and its default behavior, see:

• "Caching Overview" http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Caching Overview
• http://wiki.eclipse.org/Introduction_to_Cache_%28ELUG%29

EclipseLink defines the following entity caching annotations:

• @Cache
• @TimeOfDay
• @ExistenceChecking

EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache. These properties may compliment or provide an alternative to the usage of annotations.

For more information, see the following:

• How to Use the Persistence Unit Properties for Caching http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_Persistence_Unit_Properties_for_Caching
• What You May Need to Know About Overriding Annotations in JPA http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#What_You_May_Need_to_Know_About_Overriding_Annotations_in_JPA
• What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#What_You_May_Need_to_Know_About_Using_EclipseLink_JPA_Persistence_Unit_Properties

Examples

Example 2-10 illustrates an @Cache annotation.

Example 2-10 Using @Cache Annotation

...
@Entity
@Cache(
  type=CacheType.SOFT, // Cache everything until the JVM decides memory is low.
  size=64000  // Use 64,000 as the initial cache size.
  expiry=36000000,  // 10 minutes
  coordinationType=CacheCoordinationType.INVALIDATE_CHANGED_OBJECTS  // if cache coordination is used, only send invalidation messages.
)
public class Employee {
  ...
}

Example 2-11 shows how to use this annotation in the eclipselink-orm.xml file.

Example 2-11 Using <cache> Element

<?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="64000" expiry="36000000" coordination-type="INVALIDATE_CHANGED_OBJECTS"/>
    </entity>
</entity-mappings>

You can also specify caching properties at the persistence unit level (in the persistence.xml file) as shown here:

Example 2-12 Specifying Caching in persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd"
  version="2.0">
    <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL">
      <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
          <property name="eclipselink.cache.shared.default" value="false"/>
          <property name="eclipselink.cache.shared.Employee" value="true"/>
          <property name="eclipselink.cache.type.Employee" value="SOFT"/>
          <property name="eclipselink.cache.size.Employee" value="64000"/>
        </properties>
    </persistence-unit>
</persistence>

See Also

For more information, see:

• "@ExistenceChecking"
• "@TimeOfDay"
• "@CacheInterceptor"
• "Configuring Caching"