Cache Loaders

A CacheLoader is an interface which specifies load and loadAll methods with a variety of parameters.

CacheLoaders come from JCache, but are a frequently requested feature, so they have been incorporated into the core Ehcache classes and can be configured in ehcache.xml.

CacheLoaders are invoked in the following Cache methods:

  • getWithLoader (synchronous)
  • getAllWithLoader (synchronous)
  • load (asynchronous)
  • loadAll (asynchronous)

They are also invoked in similar (though slightly different named) JCache methods.

The methods will invoke a CacheLoader if there is no entry for the key or keys requested. By implementing CacheLoader, an application form of loading can take place. The get... methods follow the pull-through cache pattern. The load... methods are useful as cache warmers.

CacheLoaders are similar to the CacheEntryFactory used in SelfPopulatingCache. However SelfPopulatingCache is a decorator to ehcache. The CacheLoader functionality is available right in a Cache, Ehcache or JCache and follows a more industry standard convention.

CacheLoaders may be set either declaratively in the ehcache.xml configuration file or programmatically. This becomes the default CacheLoader. Some of the methods invoking loaders enable an override CacheLoader to be passed in as a parameter.

Declarative Configuration

Cache event listeners are configured per cache. Each cache can have at most one exception handler.

An exception handler is configured by adding a cacheExceptionHandlerFactory element as shown in the following example:

<cache ...>
      <cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory"
                                      properties="type=int,startCounter=10"/>
</cache>

Implementing a CacheLoaderFactory and CacheLoader

CacheLoaderFactory is an abstract factory for creating CacheLoaders. Implementers should provide their own concrete factory, extending this abstract factory. It can then be configured in ehcache.xml

The factory class needs to be a concrete subclass of the abstract factory class CacheLoaderFactory, which is reproduced below:

/**
 * An abstract factory for creating cache loaders. Implementers should provide their own
 * concrete factory extending this factory.
 * <p/>
 * There is one factory method for JSR107 Cache Loaders and one for Ehcache ones. The Ehcache
 * loader is a sub interface of the JSR107 Cache Loader.
 * <p/>
 * Note that both the JCache and Ehcache APIs also allow the CacheLoader to be set
 * programmatically.
 * @author Greg Luck
 * @version $Id: cache_loaders.apt 564 2007-11-28 08:52:18Z gregluck $
 */
public abstract class CacheLoaderFactory {

    /**
     * Creates a CacheLoader using the JSR107 creational mechanism.
     * This method is called from {@link net.sf.ehcache.jcache.JCacheFactory}
     *
     * @param environment the same environment passed into
     * {@link net.sf.ehcache.jcache.JCacheFactory}.
     * This factory can extract any properties it needs from the environment.
     * @return a constructed CacheLoader
     */
    public abstract net.sf.jsr107cache.CacheLoader createCacheLoader(Map environment);


    /**
     * Creates a CacheLoader using the Ehcache configuration mechanism at the time
     * the associated cache is created.
     *
     * @param properties implementation specific properties. These are configured as comma
     *                   separated name value pairs in ehcache.xml
     * @return a constructed CacheLoader
     */
    public abstract net.sf.ehcache.loader.CacheLoader createCacheLoader(Properties properties);
}

The factory creates a concrete implementation of the CacheLoader interface, which is reproduced below:

/**
 * Extends JCache CacheLoader with load methods that take an argument in addition to a key
 * @author Greg Luck
 * @version $Id: cache_loaders.apt 564 2007-11-28 08:52:18Z gregluck $
 */
public interface CacheLoader extends net.sf.jsr107cache.CacheLoader {


    /**
     * Load using both a key and an argument.
     *
     * JCache will call through to the load(key) method, rather than this method,
     * where the argument is null.
     * @param key the key to load the object for
     * @param argument can be anything that makes sense to the loader
     * @return the Object loaded
     *
     *
     * @throws CacheException
     */
    Object load(Object key, Object argument) throws CacheException;

    /**
     * Load using both a key and an argument.
     *
     * JCache will use the loadAll(key) method where the argument is null.
     * @param keys the keys to load objects for
     * @param argument can be anything that makes sense to the loader
     * @return a map of Objects keyed by the collection of keys passed in.
     * @throws CacheException
     */
    Map loadAll(Collection keys, Object argument) throws CacheException;

    /**
     * Gets the name of a CacheLoader
     * @return the name of this CacheLoader
     */
    String getName();
}

The implementations need to be placed in the classpath accessible to ehcache.

See the chapter on Classloading for details on how classloading of these classes will be done.

Programmatic Configuration

A CacheLoader can be set on a Cache at any time using:

    cache.setCacheLoader(CacheLoader cacheLoader)