Chapter 13. DataStoreCache
Prev | Part 3. Java Data Objects | Next

## Chapter 13. DataStoreCache

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 `PersistenceManager`s, 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.

Example 13.1. Using the DataStoreCache

    /**
     *  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]));
    }

Prev | Up | Next
Chapter 12. FetchPlan | Home | Chapter 14. JDOR