Recall that each PersistenceManager maintains a cache of persistent objects. Though this cache may improve performance, it is primarily in place to maintain data integrity and to satisfy JDO's uniqueness requirement. Thus, many vendors also implement a level 2 datastore cache for added performance. JDO's DataStoreCache interface gives you a standard way to access your vendor's level 2 cache.

public DataStoreCache getDataStoreCache ();

Datastore caches act across PersistenceManagers, at the PersistenceManagerFactory level. Some vendors may also go beyond the factory level to per-JVM and clustered caches. The PersistenceManagerFactory's getDataStoreCache method retrieves the datastore cache. Vendors who do not support a level 2 data cache will implement all DataStoreCache operations as no-ops.

Note

Kodo extends the standard DataStoreCache interface with the KodoDataStoreCache interface to provide additional functionality. You can cast any DataStoreCache in Kodo to a KodoDataStoreCache. As Section 10.1, “Data Cache” in the Reference Guide explains, Kodo allows you to define multiple named caches. The DataStoreCache facade in Kodo delegates to any of these caches as necessary. The KodoPersistenceManagerFactory also supplies a method to retrieve a DataStoreCache facade to a specific named cache. Interacting with a specific named cache can be more efficient than forcing Kodo to calculate which cache to delegate to for each operation on the generic facade.

public void evict (Object oid);
public void evictAll ();
public void evictAll (Object[] oids);
public void evictAll (Collection oids);

The evict methods tell the cache to release data. Each method takes one or more JDO identity objects, 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 your JDO implementation's control. In this scenario, you typically have to manually evict the data from the datastore cache; otherwise the JDO runtime, oblivious to the changes, will maintain its stale copy.

	Note
	In addition to manual eviction, Kodo offers per-class data timeouts and cron-style eviction schedules for caches. See Section 10.1, “Data Cache” in the Reference Guide for details.

public void pin (Object oid);
public void pinAll (Object[] oids);
public void pinAll (Collection oids);
public void unpin (Object oid);
public void unpinAll (Object[] oids);
public void unpinAll (Collection oids);

Most caches are of limited size. Pinning a JDO identity object to the cache ensures that the cache will not expire the data for the corresponding instance, 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.

/**
 *  This callback is invoked after an outside process runs to update the given
 *  Subscription records.  It evicts the records from the cache so that the
 *  JDO application does not receive stale data.
 */
public void postBatchProcess (PersistenceManagerFactory pmf, long[] subIds)
{
    DataStoreCache cache = pmf.getDataStoreCache ();
    for (int i = 0; i < subIds.length; i++)
        cache.evict (new LongIdentity (Subscription.class, subIds[i]));
}