DataNucleus - Plugins : Level 2 Cache

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the Level 2 caching of objects (between PersistenceManagers for the same PersistenceManagerFactory). The Cache guide (JDO or JPA) defines a large selection of Level 2 caches (builtin, Coherence, EHCache, OSCache, SwarmCache) but is structured so that you can easily add your own variant and have it usable within your DataNucleus usage.

DataNucleus is able to support third party Level 2 Cache products. There are provided plugins for EHCache, SwarmCache, OSCache, and Oracle Coherence. You can extend DataNucleus's capabilities using the plugin extension org.datanucleus.cache_level2 .

Plugin extension-point	Key	Description	Location
org.datanucleus.cache_level2	default	Level 2 Cache (default)	datanucleus-core
org.datanucleus.cache_level2	soft	Level 2 Cache using Soft maps	datanucleus-core
org.datanucleus.cache_level2	ehcache	Level 2 Cache using EHCache	datanucleus-cache
org.datanucleus.cache_level2	ehcacheclassbased	Level 2 Cache using EHCache (based on classes)	datanucleus-cache
org.datanucleus.cache_level2	oscache	Level 2 Cache using OSCache	datanucleus-cache
org.datanucleus.cache_level2	swarmcache	Level 2 Cache using SwarmCache	datanucleus-cache
org.datanucleus.cache_level2	coherence	Level 2 Cache using Oracle Coherence	datanucleus-cache

The following sections describe how to create your own Level 2 cache plugin for DataNucleus.

Interface

If you have your own Level2 cache you can easily use it with DataNucleus. DataNucleus defines a Level2Cache interface and you need to implement this.

package org.datanucleus.cache;
public interface Level2Cache
{
    void close();

    void evict (Object oid);
    void evictAll ();
    void evictAll (Object[] oids);
    void evictAll (Collection oids);
    void evictAll (Class pcClass, boolean subclasses);

    void pin (Object oid);
    void pinAll (Collection oids);
    void pinAll (Object[] oids);
    void pinAll (Class pcClass, boolean subclasses);

    void unpin(Object oid);
    void unpinAll(Collection oids);
    void unpinAll(Object[] oids);
    void unpinAll(Class pcClass, boolean subclasses);

    int getNumberOfPinnedObjects();
    int getNumberOfUnpinnedObjects();
    int getSize();
    CachedPC get(Object oid);
    CachedPC put(Object oid, CachedPC pc);
    boolean isEmpty();
    void clear();
    boolean containsOid(Object oid);
}

Implementation

Let's suppose your want to implement your own Level 2 cache MyLevel2Cache

package mydomain;

import org.datanucleus.OMFContext;
import org.datanucleus.cache.Level2Cache;

public class MyLevel2Cache implements Level2Cache
{
    /**
     * Constructor.
     * @param omfCtx OMF Context
     */
    public MyLevel2Cache(OMFContext omfCtx)
    {
        ...
    }

    ... (implement the interface)
}

Plugin Specification

Once you have this implementation you then need to make the class available as a DataNucleus plugin. You do this by putting a file plugin.xml in your JAR at the root of the CLASSPATH. The file plugin.xml will look like this

<?xml version="1.0"?>
<plugin id="mydomain" name="DataNucleus plug-ins" provider-name="My Company">
    <extension point="org.datanucleus.cache_level2">
	    <cache name="MyCache" class-name="mydomain.MyLevel2Cache"/>
    </extension>
</plugin>

Note that you also require a MANIFEST.MF file as per the Plugins Guide.

Plugin Usage

The only thing remaining is to use your L2 Cache plugin. To do this you specify the PersistenceManagerFactory property datanucleus.cache.level2.type as MyCache (the "name" in plugin.xml ).