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

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

kodo.DataCache: true
kodo.RemoteCommitProvider: sjvm

To configure the data cache to remain up-to-date in a distributed environment, set the kodo.RemoteCommitProvider property appropriately, or integrate Kodo with a third-party caching solution. Remote commit providers are described in Section 11.3, “Remote Event Notification Framework”. Section 10.1.4, “Third-Party Integrations” enumerates supported third-party caching solutions.

Kodo's default implementation maintains a concurrent map of object ids to cache data. By default, 1000 elements are kept in cache. This 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 the maximum.

When the maximum cache size is exceeded, random entries are 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 Kodo keeps with the SoftReferenceSize property. Soft references are unlimited by default. Set to 0 to disable soft references completely.

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

kodo.DataCache: true(CacheSize=5000, SoftReferenceSize=0)

Kodo offers a least-recently-used (LRU) caching option in addition to the default concurrent cache. Substitute lru for true in your kodo.DataCache setting to utilize the LRU cache. Note that while the LRU cache's eviction scheme is more optimal than the default cache's random evictions, it also requires much more synchronization. Generally, the default cache's higher concurrency results in better performance than the LRU cache's smarter eviction scheme.

Note

The default concurrent cache does not fully index its contents by class. Rather, it tracks which clasess are in the cache. It services requests to drop given classes by checking to see if any instances of that class might be in the cache, and then clearing the entire cache. You can work around this inefficiency with careful cache partitioning. The LRU cache, however, does not suffer from this limitation. Dropping a class from the LRU cache only drops entries for that class.

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

kodo.DataCache: lru(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
{
    ...
}

<class name="Employee">
    <extension vendor-name="kodo" key="data-cache-timeout" value="10000"/>
    ...
</class>

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 Kodo's cache implementation accepts 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 kodo.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')

It is also possible for different persistence-capable classes to use different caches. This is achieved by specifying a cache name in a metadata extension.

import org.apache.openjpa.persistence.*;

@Entity
@DataCache(name="small-cache", timeout=10000)
public class Employee
{
    ...
}

<class name="Employee">
    <extension vendor-name="kodo" key="data-cache" value="small-cache"/>
    <extension vendor-name="kodo" key="data-cache-timeout" value="10000"/>
    ...
</class>

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

The metadata above will cause instances of the Employee class to be stored in a cache named small-cache. This small-cache cache can be explicitly configured in the kodo.DataCache plugin string, or can be implicitly defined, in which case it will take on the same default configuration properties as the default cache identified in the kodo.DataCache property.

<property name="kodo.DataCache" value="true, true(Name=small-cache, CacheSize=100)"/>

kodo.DataCache: true, true(Name=small-cache, CacheSize=100)

The kodo.datacache package defines Kodo'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 10.1.5, “Cache Extension” below has tips on how to use this package to extend Kodo's caching service yourself.

Rather than use the low-level kodo.datacache package APIs, JPA users should typically access the data cache through Kodo's high-level org.apache.openjpa.persistence.StoreCache facade. This facade has methods to pin and unpin records, evict data from the cache, and more.

public StoreCache getStoreCache ();
public StoreCache getStoreCache (String name);

You obtain the StoreCache through the OpenJPAEntityManagerFactory.getStoreCache methods. When you have multiple data caches configured as in the small-cache example above, the StoreCache can act as a unified facade over all your caches. For every oid parameter to the StoreCache methods, it determines the correct data cache for that oid's corresponding persistent class, and dynamically delegates to that cache.

If you know that you want to access a certain data cache and no others, the OpenJPAEntityManagerFactory.getStoreCache(String name) method returns a StoreCache interface to a particular named data cache.

import org.apache.openjpa.persistence.*;

...

OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast (emf);
StoreCache cache = oemf.getStoreCache ();
...
StoreCache smallCache = oemf.getStoreCache ("small-cache");
...

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

The evict methods tell the cache to release data. Each method takes an entity class and one or more identity values, and releases the cached data for the corresponding persistent instances. The evictAll method with no arguments clears the cache. Eviction is useful when the datastore is changed by a separate process outside Kodo's control. In this scenario, you typically have to manually evict the data from the datastore cache; otherwise the Kodo runtime, oblivious to the changes, will maintain its stale copy.

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);

Most caches are of limited size. Pinning an identity to the cache ensures that the cache will mill not kick the data for the corresponding instance out of the cache, unless you manually evict it. Note that even after manual eviction, the data will get pinned again the next time it is fetched from the store. You can only remove a pin and make the data once again available for normal cache overflow eviction through the unpin methods. Use pinning when you want a guarantee that a certain object will always be available from cache, rather than requiring a datastore trip.

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 ());

See the StoreCache Javadoc for information on additional functionality it provides. Also, Chapter 9, Runtime Extensions discusses Kodo's other extensions to the standard set of JPA runtime interfaces.

JDO users can access the data cache through the JDO-standard javax.jdo.datastore.DataStoreCache facade. The JDO Overview describes this interface in Chapter 13, DataStoreCache. Kodo extends the standard JDO cache in two ways:

import kodo.jdo.*;

...

KodoPersistenceManagerFactory kpmf = KodoJDOHelper.cast (pmf);
DataStoreCache cache = kpmf.getDataStoreCache ("small-cache");
cache.evict (JDOHelper.getObjectId (changedObj));
cache.pin (JDOHelper.getObjectId (popularObj));

You can read more about Kodo extensions to JDO APIs in Chapter 9, Runtime Extensions.

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 Kodo to automatically evict objects from the data cache when you use the OpenJPAEntityManager or PersistenceManager's eviction APIs.

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

kodo.BrokerImpl: EvictFromDataCache=true

import org.apache.openjpa.persistence.*;

...

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

PersistenceManager pm = ...;
pm.evict (changedMag);  // will evict from data cache also

In addition to the data cache, the kodo.datacache package defines service provider interfaces for a query cache. The query cache is enabled by default when the data cache is enabled. The query cache stores the object ids returned by query executions. When you run a query, Kodo 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.

Kodo JPA 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.

Kodo JDO exposes a high-level interface to the query cache through the kodo.jdo.QueryResultCache class. You can access this class through the KodoPersistenceManagerFactory.

import org.apache.openjpa.persistence.*;

...

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

import kodo.jdo.*;

...

KodoPersistenceManagerFactory kpmf = KodoJDOHelper.cast (pmf);
QueryResultCache qcache = kpmf.getQueryResultCache ();

The default query cache implementation caches 100 query executions in a concurrent map. 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="kodo.QueryCache" value="CacheSize=1000, SoftReferenceSize=100"/>

kodo.QueryCache: CacheSize=1000, SoftReferenceSize=100

Just as Kodo offers an LRU data caching option, Kodo includes an LRU query cache as well. Once again, it has the same sizing options as the default query cache.

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

kodo.QueryCache: lru(CacheSize=1000, SoftReferenceSize=100)

To disable the query cache completely, set the kodo.QueryCache property to false:

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

kodo.QueryCache: false

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 Kodo's control. You can also evict individual queries, or clear the entire cache.

JPA:

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

JDO:

public void evict (Query q);
public void evict (Query q, Object[] params);
public void evict (Query q, Map params);
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.

For JDO queries with parameters, pass the parameter values of the query in the params array or map.

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);

import kodo.jdo.*;

...

KodoPersistenceManagerFactory kpmf = KodoJDOHelper.cast (pmf);
QueryResultCache qcache = kpmf.getQueryResultCache ();

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

// evict an individual query with parameters
PersistenceManager pm = pmf.getPersistenceManager ();
Query q = pm.newQuery (...);
qcache.evictAll (q, new Object[] { paramVal0, paramVal1 });

When using one of Kodo's distributed cache implementations, it is necessary to perform this in every JVM - the change notification is not propagated automatically. When using a coherent cache implementation such as Kodo's Tangosol cache implementation, 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.

JPA:

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

JDO:

public void pin (Query q);
public void pin (Query q, Object[] params);
public void pin (Query q, Map params);
public void unpin (Query q);
public void unpin (Query q, Object[] params);
public void unpin (Query q, Map params);

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

For JDO queries with parameters, pass the parameter values of the query in the params array or map.

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);

import kodo.jdo.*;

...

KodoPersistenceManagerFactory kpmf = KodoJDOHelper.cast (pmf);
QueryResultCache qcache = kpmf.getQueryResultCache ();
PersistenceManager pm = pmf.getPersistenceManager ();

Query pinQuery = pm.newQuery (...);
qcache.pin (pinQuery, new Object[] { paramVal0, paramVal1 });
Query unpinQuery = pm.newQuery (...);
qcache.unpin (unpinQuery, new Object[] { paramVal0, paramVal1 });

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, per-PersistenceManager 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 ().setQueryResultCache (false);

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

import kodo.jdo.*;

...

// temporarily disable query caching for all queries created from pm
PersistenceManager pm = ...;
KodoFetchPlan fetch = (KodoFetchPlan) pm.getFetchPlan ();
fetch.setQueryResultCache (false);

// re-enable caching for a particular query
Query q = pm.newQuery (...);
KodoFetchPlan fetch = KodoJDOHelper.cast (pm.getFetchPlan ());
fetch.setQueryResultCache (true);

Kodo includes built-in integrations with Tangosol Coherence and GemStone GemFire caching products.

<property name="kodo.DataCache" value="tangosol(TangosolCacheName=kodo)"/>

kodo.DataCache: tangosol(TangosolCacheName=kodo)

<property name="kodo.QueryCache" value="tangosol(TangosolCacheName=kodo-query)"/>

kodo.QueryCache: tangosol(TangosolCacheName=kodo-query)

<?xml version="1.0" encoding="UTF-8"?>
<!-- Gemfire cache configuration for Kodo testing -->
<!DOCTYPE cache PUBLIC
  "-//GemStone Systems, Inc.//GemFire Declarative Caching 5.0//EN"
  "http://www.gemstone.com/dtd/cache5_0.dtd">
<cache search-timeout="60" lock-lease="300" copy-on-read="false">
    <region name="root">
        <region-attributes scope="local"/>
        <region name="kodo-data-cache">
            <region-attributes scope="local"/>
        </region>
        <region name="kodo-query-cache">
            <region-attributes scope="local"/>
        </region>
    </region>
</cache>

<property name="kodo.DataCache" 
    value="gemfire(GemFireCacheName=/root/my-kodo-data-cache)"/>
<property name="kodo.QueryCache" 
    value="gemfire(GemFireCacheName=/root/my-kodo-query-cache)"/>

kodo.DataCache: gemfire(GemFireCacheName=/root/My-kodo-data-cache)
kodo.QueryCache: gemfire(GemFireCacheName=/root/My-kodo-query-cache)

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

The query cache is just as easy to extend. Add functionality by extending the default kodo.datacache.QueryCacheImpl. Implement your own storage mechanism for query results by extending kodo.datacache.AbstractQueryCache or implementing the kodo.datacache.QueryCache interface directly.