Java Persistence API (JPA) Extensions Reference for EclipseLink, Release 2.5
  Go To Table Of Contents
 Search
 PDFComments
Comments


@Cache

Use @Cache (in place of the JPA @Cachable annotation) 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

Annotation Element Description Default

type

(Optional) Set this attribute to the type (org.eclipse.persistence.annotations.CacheType enumerated type) of the cache that you will be using:

  • FULL

  • WEAK

  • SOFT

  • SOFT_WEAK

  • HARD_WEAK

  • CACHE (not recommended)

  • NONE (not recommended, use isolation=ISOLATED instead)

You can override this attribute with these persistence unit properties:

  • eclipselink.cache.type.<ENTITY>

  • eclipselink.cache.type.default

CacheType.SOFT_WEAK

size

(Optional) Set this attribute to an int value to define the size of cache to use (number of objects).

100

isolation

(Optional) The caching level of the Entity:

  • shared – Entity instances will be cached within the EntityManagerFactory/ServerSession level.

  • isolated – The Entity and its data is not stored in the shared cache, but is isolated to the Persistence Context/UnitOfWork or IsolatedClientSession.

  • protected – Entity state information will be cached in the shared cache, but Entity instances will not be shared.

shared

expiry

(Optional) The int value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy.

no expiry

expiryTimeOfDay

(Optional) Specific time of day (org.eclipse.persistence.annotations.TimeOfDay) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.

no expiry

alwaysRefresh

(Optional) Set to a boolean value of true to force all queries that go to the database to always refresh the cache

false

refreshOnlyIfNewer

(Optional) Set to a boolean value of true to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).

Note:

  • This option only applies if one of the other refreshing options, such as alwaysRefresh, is already enabled.

  • A version field is necessary to apply this feature.

false

disableHits

(Optional) Set to a boolean value of true to force all queries to bypass the cache for hits, but still resolve against the cache for identity. This forces all queries to hit the database.

false

coordinationType

(Optional) Set this attribute to the cache coordination mode (org.eclipse.persistence.annotations.CacheCoordinationType enumerated type). You must also configure cache coordination in your persistence unit properties. See "Caching".

SEND_OBJECT_CHANGES

databaseChangeNotificationType

(Optional) The database change notification mode:

  • Invalidate – Invalidates the EclipseLink cache when a database change event is received for an object.

  • None – No database change events will be processed. The database event listener must also be configured for the persistence unit/session.

INVALIDATE



Usage

Use the @Cache annotation instead of the JPA @Cachable annotation to provide additional caching configuration.

You can define the @Cache annotation on the following:

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:

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

EclipseLink defines the following entity caching annotations:

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

For more information, see "Caching".


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> XML

<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

<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: