To enable the basic single-factory cache set the openjpa.DataCache property to true, and set the openjpa.RemoteCommitProvider property to sjvm :

<property name="openjpa.DataCache" value="true"/>
<property name="openjpa.RemoteCommitProvider" value="sjvm"/>

To configure the data cache to remain up-to-date in a distributed environment, set the openjpa.RemoteCommitProvider property appropriately, or integrate OpenJPA with a third-party caching solution. Remote commit providers are described in Section 2, “ Remote Event Notification Framework ”.

OpenJPA's default implementation maintains a map of object ids to cache data. By default, 1000 elements are kept in cache. When the cache overflows, random entries are evicted. The maximum cache size can be adjusted by setting the CacheSize property in your plugin string - see below for an example. Objects that are pinned into the cache are not counted when determining if the cache size exceeds its maximum size.

Expired objects are moved to a soft reference map, so they may stick around for a little while longer. You can control the number of soft references OpenJPA keeps with the SoftReferenceSize property. Soft references are unlimited by default. Set to 0 to disable soft references completely.

Both the QueryCache and DataCache can be configured to use a backing Lru map rather than the default concurrent HashMap. Note that enabling the Lru cache can hurt performance as this map in not as scalable as the default map.

<property name="openjpa.DataCache" value="true(Lru=true)"/>
<property name="openjpa.QueryCache" value="true(Lru=true)"/>

<property name="openjpa.DataCache" value="true(CacheSize=5000, SoftReferenceSize=0)"/>

You can specify a cache timeout value for a class by setting the timeout metadata extension to the amount of time in milliseconds a class's data is valid. Use a value of -1 for no expiration. This is the default value.

@Entity
@DataCache(timeout=10000)
public class Employee {
    ...
}

Entities may be explicitly excluded from the cache by providing a list of fully qualified class names in the ExcludedTypes argument. The entities provided via ExcludedTypes will not be cached regardless of the @DataCache annotation.

<property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/>
                    

Entities may be explicitly included from the cache by providing a list of fully qualified class names in the Types argument. The entities provided via ExcludedTypes will not cached regardless of the @DataCache annotation. Any entities which are not included in this list will not be cached.

<property name="openjpa.DataCache" value="true(Types=foo.bar.FullTimeEmployee)"/>
                    

See the org.apache.openjpa.persistence.DataCache Javadoc for more information on the DataCache annotation.

A cache can specify that it should be cleared at certain times rather than using data timeouts. The EvictionSchedule property of OpenJPA's cache implementation can be input in two different formats. The first is a cron style eviction schedule. The format of this property is a whitespace-separated list of five tokens, where the * symbol (asterisk), indicates match all. The tokens are, in order:

For example, the following openjpa.DataCache setting schedules the default cache to evict values from the cache at 15 and 45 minutes past 3 PM on Sunday.

true(EvictionSchedule='15,45 15 * * 1')

The second format for this property is an interval style eviction schedule. The format of this property is a + followed by the number of minutes between each time that the cache should be evicted.

For example, the following openjpa.DataCache setting schedules the default cache to evict values from the cache every 120 minutes.

true(EvictionSchedule='+120')

<property name="openjpa.DataCache" value="true(EvictOnBulkUpdate=false)"/>

<property name="openjpa.CacheDistributionPolicy" value="org.acme.foo.DistributionPolicy"/>
<property name="openjpa.DataCache" value="partitioned(PartitionType=concurrent,partitions=
                '(name=a,cacheSize=100),(name=b,cacheSize=200)')"/>

The distribution policy is configured by a full-qualified class name that implements org.apache.openjpa.datacahe.CacheDistributionPolicy. The partitions are specified as value of the partitions attribute as a series of individually configurable plug-in strings. As the example shows, i) each partition plug-in configuration must be enclosed in parentheses, ii) must be separated by comma and iii) the complete set be enclosed in single quote. Each individual partition is a Data Cache by itself and the class that implements the partition can be configured via PartitionType attribute. The above example configuration will configure a partitioned cache with two partitions named a and b of cache size 100 and 200, respectively. The partitions are of concurrent type which is a mnemonic or alias for org.apache.openjpa.datacache.ConcurrentDataCache. The PartitionType is defaulted to concurrent though explicitly mentioned in this example.

The org.apache.openjpa.datacache package defines OpenJPA's data caching framework. While you may use this framework directly (see its Javadoc for details), its APIs are meant primarily for service providers. In fact, Section 1.5, “ Cache Extension ” below has tips on how to use this package to extend OpenJPA's caching service yourself.

Rather than use the low-level org.apache.openjpa.datacache package APIs, JPA users should typically access the data cache through the JPA standard javax.persistence.Cache interface, or OpenJPA's high-level org.apache.openjpa.persistence.StoreCache facade.

Both interfaces provide methods to evict data from the cache and detect whether an entity is in the cache. The OpenJPA facade adds methods to pin and unpin records, additional methods to evict data, and provides basic statistics of number of read or write requests and hit ratio of the cache.

import javax.persistence.Cache;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
. . .
EntityManagerFactory em = 
    Persistence.createEntityManagerFactory("myPersistenceUnit");
Cache cache = em.getCache();
. . .
        

// Check whether the cache contains an entity with a provided ID
Cache cache = em.getCache();
boolean contains = cache.contains(MyEntity.class, entityID);

// evict a specific entity from the cache
cache.evict(MyEntity.class, entityID);

// evict all instances of an entity class from the cache
cache.evict(AnotherEntity.class);

// evict everything from the cache 
cache.evictAll();
        

import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
StoreCache cache = oemf.getStoreCache();
...

import org.apache.openjpa.persistence.StoreCache;
...
StoreCache cache = (StoreCache) emf.getCache();

public void evict(Class cls, Object oid);
public void evictAll();
public void evictAll(Class cls, Object... oids);
public void evictAll(Class cls, Collection oids);

public void pin(Class cls, Object oid);
public void pinAll(Class cls, Object... oids);
public void pinAll(Class cls, Collection oids);
public void unpin(Class cls, Object oid);
public void unpinAll(Class cls, Object... oids);
public void unpinAll(Class cls, Collection oids);

import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
StoreCache cache = oemf.getStoreCache();
cache.pin(Magazine.class, popularMag.getId());
cache.evict(Magazine.class, changedMag.getId());

The examples above include calls to evict to manually remove data from the data cache. Rather than evicting objects from the data cache directly, you can also configure OpenJPA to automatically evict objects from the data cache when you use the OpenJPAEntityManager's eviction APIs.

<property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/>

import org.apache.openjpa.persistence.*;

...

OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
oem.evict(changedMag);  // will evict from data cache also

Number of requests to read and write requests and hit ratio of the data cache is available via org.apache.openjpa.datacache.CacheStatistics interface. The collection of cache statistics is disabled by default and needs to be enabled on a per cache basis. By default all counts returned from the CacheStatistics interface will return 0.

<property name="openjpa.DataCache" value="true(EnableStatistics=true)"/>

Once cache statistics are enabled you can access them via StoreCache

import org.apache.openjpa.datacache.CacheStatistics;
...
OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
CacheStatistics statistics = oemf.getStoreCache().getCacheStatistics();

The statistics includes number of read and write requests made to the cache since start and last reset. The statistics can be obtained also per class basis.

public interface org.apache.openjpa.datacache.CacheStatistics extends java.io.Serializable{
    // Statistics since last reset
    public long getReadCount();
    public long getHitCount();
    public long getWriteCount();
    
    // Statistics since start
    public long getTotalReadCount();
    public long getTotalHitCount();
    public long getTotalWriteCount();
    
    // Per-Class statistics since last reset
    public long getReadCount(java.lang.Class);
    public long getHitCount(java.lang.Class);
    public long getWriteCount(java.lang.Class);
    
    // Per-Class statistics since start
    public long getTotalReadCount(java.lang.Class);
    public long getTotalHitCount(java.lang.Class);
    public long getTotalWriteCount(java.lang.Class);
    
    // Starting and last reset time 
    public java.util.Date since();
    public java.util.Date start();
    
    // Resets the statistics. 
    public void reset();
    
    // Returns whether or not statistics will be collected.
    public boolean isEnabled();
}

Collecting per-class statistics depends on determining the runtime type of a cached data element, when the given context does not permit determination of exact runtime type, the statistics is registered against generic java.lang.Object. Also each method that accepts Class argument, treats null argument as java.lang.Object

In addition to the data cache, the org.apache.openjpa.datacache package defines service provider interfaces for a query cache. The query cache is disabled by default and needs to be enabled separately from the data cache. The query cache stores the object ids returned by query executions. When you run a query, OpenJPA assembles a key based on the query properties and the parameters used at execution time, and checks for a cached query result. If one is found, the object ids in the cached result are looked up, and the resultant persistence-capable objects are returned. Otherwise, the query is executed against the database, and the object ids loaded by the query are put into the cache. The object id list is not cached until the list returned at query execution time is fully traversed.

OpenJPA exposes a high-level interface to the query cache through the org.apache.openjpa.persistence.QueryResultCache class. You can access this class through the OpenJPAEntityManagerFactory.

import org.apache.openjpa.persistence.*;

...

OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();

The default query cache implementation caches 100 query executions in a least-recently-used cache. This can be changed by setting the cache size in the CacheSize plugin property. Like the data cache, the query cache also has a backing soft reference map. The SoftReferenceSize property controls the size of this map. It is disabled by default.

<property name="openjpa.QueryCache" value="true(CacheSize=1000, SoftReferenceSize=100)"/>

To disable the query cache (default), set the openjpa.QueryCache property to false:

<property name="openjpa.QueryCache" value="false"/>

Query Cache's default behaviour on eviction is to evict all the queries from the cache if any of the entities that are in the access path of the query are modified. Scanning through the whole query cache to evict the queries upon an entity update slows down the entity update action. The configurable eviction policy "timestamp" is to track the timestamp of the query and the timestamp of last update for each entity class and compare the timestamps when retrieving the query for reuse. If the timestamp of the query result is older than the last update time of any entity in the access path of the query, the query result would not be reused and the query result would be evicted from the query cache. To configure the EvictPolicy to timestamp, here is an example:

<property name="openjpa.QueryCache" value="true(EvictPolicy='timestamp')"/>

There are certain situations in which the query cache is bypassed:

Cache results are removed from the cache when instances of classes in a cached query's access path are touched. That is, if a query accesses data in class A, and instances of class A are modified, deleted, or inserted, then the cached query result is dropped from the cache.

It is possible to tell the query cache that a class has been altered. This is only necessary when the changes occur via direct modification of the database outside of OpenJPA's control. You can also evict individual queries, or clear the entire cache.

public void evict(Query q);
public void evictAll(Class cls);
public void evictAll();

For JPA queries with parameters, set the desired parameter values into the Query instance before calling the above methods.

import org.apache.openjpa.persistence.*;

...

OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();

// evict all queries that can be affected by changes to Magazines
qcache.evictAll(Magazine.class);

// evict an individual query with parameters
EntityManager em = emf.createEntityManager();
Query q = em.createQuery(...).
    setParameter(0, paramVal0).
    setParameter(1, paramVal1);
qcache.evict(q);

When using one of OpenJPA's distributed cache implementations, it is necessary to perform this in every JVM - the change notification is not propagated automatically. When using a third-party coherent caching solution, it is not necessary to do this in every JVM (although it won't hurt to do so), as the cache results are stored directly in the coherent cache.

Queries can also be pinned and unpinned through the QueryResultCache. The semantics of these operations are the same as pinning and unpinning data from the data cache.

public void pin(Query q);
public void unpin(Query q);

For JPA queries with parameters, set the desired parameter values into the Query instance before calling the above methods.

The following example shows these APIs in action.

import org.apache.openjpa.persistence.*;

...

OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
QueryResultCache qcache = oemf.getQueryResultCache();
EntityManager em = emf.createEntityManager();

Query pinQuery = em.createQuery(...).
    setParameter(0, paramVal0).
    setParameter(1, paramVal1);
qcache.pin(pinQuery);
Query unpinQuery = em.createQuery(...).
    setParameter(0, paramVal0).
    setParameter(1, paramVal1);
qcache.unpin(unpinQuery);

Pinning data into the cache instructs the cache to not expire the pinned results when cache flushing occurs. However, pinned results will be removed from the cache if an event occurs that invalidates the results.

You can disable caching on a per-EntityManager or per-Query basis:

import org.apache.openjpa.persistence.*;

...

// temporarily disable query caching for all queries created from em
OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
oem.getFetchPlan().setQueryResultCacheEnabled(false);

// re-enable caching for a particular query
OpenJPAQuery oq = oem.createQuery(...);
oq.getFetchPlan().setQueryResultCacheEnabled(true);

The provided data cache classes can be easily extended to add additional functionality. If you are adding new behavior, you should extend org.apache.openjpa.datacache.ConcurrentDataCache. To use your own storage mechanism, extend org.apache.openjpa.datacache.AbstractDataCache (preferred), or implement org.apache.openjpa.datacache.DataCache directly. If you want to implement a distributed cache that uses an unsupported method for communications, create an implementation of org.apache.openjpa.event.RemoteCommitProvider. This process is described in greater detail in Section 2.2, “ Customization ”.

The query cache is just as easy to extend. Add functionality by extending the default org.apache.openjpa.datacache.ConcurrentQueryCache. Implement your own storage mechanism for query results by extending org.apache.openjpa.datacache.AbstractQueryCache (preferred) or implementing the org.apache.openjpa.datacache.QueryCache interface directly.