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

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

http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching

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:

"@ExistenceChecking"
"@TimeOfDay"
"@CacheInterceptor"
"Understanding Caching" in the Understanding EclipseLink
"Object Caching" in Solutions Guide for EclispeLink
EclipseLink Caching examples:
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching