Extensions : Level 2 Cache

Plugin

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the Level 2 caching of objects (between PM/EMs for the same PMF/EMF). DataNucleus provides a large selection of Level 2 caches (builtin-map-based, Coherence, EHCache, OSCache, others) 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 others. You can extend DataNucleuss 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 jcache Level 2 Cache using JCache (early javax.cache) datanucleus-cache
org.datanucleus.cache_level2 javax.cache Level 2 Cache using javax.cache datanucleus-core
org.datanucleus.cache_level2 cacheonix Level 2 Cache using Cacheonix datanucleus-cache
org.datanucleus.cache_level2 xmemcached Level 2 Cache using Xmemcached datanucleus-cache
org.datanucleus.cache_level2 spymemcached Level 2 Cache using Spymemcached datanucleus-cache
org.datanucleus.cache_level2 coherence Level 2 Cache using Oracle Coherence 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

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. Javadoc.

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

Lets 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 Extensions Guide.

Plugin Usage

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