Ehcache(2.9.x) - API Developer Guide, Cache Exception Handlers

About Exception Handlers

By default, most cache operations will propagate a runtime CacheException on failure. An interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can be configured to intercept Exceptions. Errors are not intercepted.

Caches with ExceptionHandling configured are of type Ehcache. To get the exception handling behavior they must be referenced using CacheManager.getEhcache(), not CacheManager.getCache(), which returns the underlying undecorated cache.

Exception handlers are configured per cache. Each cache can have at most one exception handler. You can set CacheExceptionHandlers either declaratively in the ehcache.xml configuration file, or programmatically.

Declarative Configuration

To configure an exception handler declaratively, add the cacheExceptionHandlerFactory element to ehcache.xml as shown in the following example:

<cache ...>
　　<cacheExceptionHandlerFactory
   　　class="net.sf.ehcache.exceptionhandler.CountingExceptionHandlerFactory"
   　　properties="logLevel=FINE"/>
</cache>

Implementing a Cache Exception Handler Factory and Cache Exception Handler

A CacheExceptionHandlerFactory is an abstract factory for creating cache exception handlers. Implementers should provide their own concrete factory, extending this abstract factory. It can then be configured in ehcache.xml.

Note: Your implementations need to be placed in the classpath accessible to Ehcache. For information about how class loading is handled, see Class Loading.

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

/**
 * An abstract factory for creating <code>CacheExceptionHandler</code>s at configuration time, in ehcache.xml.
 * <p/>
 * Extend to create a concrete factory
 *
 * @author <a href="mailto:gluck@gregluck.com">Greg Luck</a>
 * @version $Id: CacheExceptionHandlerFactory.java 5594 2012-05-07 16:04:31Z cdennis $
 */
public abstract class CacheExceptionHandlerFactory {

    /**
     * Create an <code>CacheExceptionHandler</code>
     *
     * @param properties implementation specific properties. These are configured as comma
     *                   separated name value pairs in ehcache.xml
     * @return a constructed CacheExceptionHandler
     */
    public abstract CacheExceptionHandler createExceptionHandler(Properties properties);

}

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

/**
 * A handler which may be registered with an Ehcache, to handle exceptions on Cache operations.
 * <p/>
 * Handlers may be registered at configuration time in ehcache.xml, using a CacheExceptionHandlerFactory, or
 *  set at runtime (a strategy).
 * <p/>
 * If an exception handler is registered, the default behaviour of throwing the exception will not occur. The handler
 * method <code>onException</code> will be called. Of course, if the handler decides to throw the exception, it will
 * propagate up through the call stack. If the handler does not, it won't.
 * <p/>
 * Some common Exceptions thrown, and which therefore should be considered when implementing this class are listed below:
 * <ul>
 * <li>{@link IllegalStateException} if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
 * <li>{@link IllegalArgumentException} if an attempt is made to put a null element into a cache
 * <li>{@link net.sf.ehcache.distribution.RemoteCacheException} if an issue occurs in remote synchronous replication
 * <li>
 * <li>
 * </ul>
 *
 * @author <a href="mailto:gluck@gregluck.com">Greg Luck</a>
 * @version $Id: CacheExceptionHandler.java 5594 2012-05-07 16:04:31Z cdennis $
 */
public interface CacheExceptionHandler {

    /**
     * Called if an Exception occurs in a Cache method. This method is not called
     * if an <code>Error</code> occurs.
     *
     * @param ehcache   the cache in which the Exception occurred
     * @param key       the key used in the operation, or null if the operation does not use a key or the key was null
     * @param exception the Exception caught.
     */
    void onException(Ehcache ehcache, Object key, Exception exception);
}

Programmatic Configuration

The following example shows how to add exception handling to a cache, and then add the cache back into cache manager so that all clients obtain the cache handling decoration.

CacheManager cacheManager = ...
Ehcache cache = cacheManger.getCache("exampleCache");
ExceptionHandler handler = new ExampleExceptionHandler(...);
cache.setCacheLoader(handler);
Ehcache proxiedCache = ExceptionHandlingDynamicCacheProxy.createProxy(cache);
cacheManager.replaceCacheWithDecoratedCache(cache, proxiedCache);