Revision as of 11:27, 15 June 2009

JPA 2.0: Cache Usage Settings

JPA 2.0 Root | bug 277039

Summary

The specification introduces cache usage controls in JPA 2.0. Users can use settings on the Entity and Query hints to control how the cache should be used. There are separate settings for how a provider can use the cache for query results and when the cache should be updated with database query results.

Section 3.7.1

Whether the entities and entity-related state of a persistence unit will be cached is determined by the value of the caching element of the persistence.xml file.

The caching element has four possible values: ALL, NONE, ENABLE_SELECTIVE, DISABLE_SELECTIVE.

A value of ALL causes all entities and entity-related state and data to be cached.

A value of NONE causes caching to be disabled for the persistence unit. Persistence providers must not cache if NONE is specified.

The values ENABLE_SELECTIVE and DISABLE_SELECTIVE are used in conjunction with the Cacheable annotation (or XML element). The Cacheable annotation specifies whether an entity should be cached if caching is enabled by the persistence.xml caching element. Cacheable( false) means that the entity and its state must not be cached by the provider.

// From JPA 2.0 Specification
@Target({TYPE}) @Retention(RUNTIME)
public @interface Cacheable {
boolean value() default true;

A value of ENABLE_SELECTIVE enables the cache and causes entities for which Cacheable( true) (or its XML equivalent) is specified to be cached. Entities for which Cacheable( true) is not specified or for which Cacheable(false) is specified must not be cached.

A value of DISABLE_SELECTIVE enables the cache and causes all entities to be cached except those for which Cacheable(false) is specified. Entities for which Cacheable(false) is specified must not be cached.

Section 3.7.2

// From JPA 2.0 Specification
public enum CacheRetrieveMode {
 
    /**
     * Read entity data from the cache: this is
     * the default behavior.
     */
    USE,
 
    /**
     * Bypass the cache: get data directly from
     * the database.
     */
    BYPASS
}
 
public enum CacheStoreMode {
 
    /**
     * Insert/update entity data into cache when read
     * from database and when committed into database:
     * this is the default behavior. Does not force refresh
     * of already cached items when reading from database.
     */
    USE,
 
    /**
     * Don't insert into cache.
     */
    BYPASS,
 
    /**
     * Insert/update entity data into cache when read
     * from database and when committed into database:
     * Forces refresh of cache for items read from database.
     */
    REFRESH
}

// From JPA 2.0 Specification
@Target({TYPE}) @Retention(RUNTIME)
public @interface Cacheable {
boolean value() default true;

Most of this support should already exist at the query level but entity level settings may need to be added. PersistenceUnitInfo class updates. orm.xml and persistence.xml processing and annotation processing will be required

Functional Requirements

• Support specification requirements.
• Default for the "caching element" will be DISABLE_SELECTIVE

Work Estimate

1. Develop model for testing cache usage settings

   approx 3 days

2. Update processing

   approx 3 days

3. Implement Functionality

   approx 3 days

Design

Documentation

Testing

Open Issues