Ehcache(2.9.x) - API Developer Guide, Cache Manager Event Listeners

About CacheManager Event Listeners

CacheManager event listeners allow implementers to register callback methods that will be executed when a CacheManager event occurs. CacheManager listeners implement the CacheManagerEventListener interface. The events include:

• Adding a Cache
• Removing a Cache

Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of the implementer to safely handle the potential performance and thread safety issues depending on what their listener is doing.

Configuring a Cache Manager Event Listener

One CacheManagerEventListenerFactory and hence one CacheManagerEventListener can be specified per CacheManager instance. The factory is configured as below:

<cacheManagerEventListenerFactory class="" properties=""/>

The entry specifies a CacheManagerEventListenerFactory which will be used to create a CacheManagerEventListener, which is notified when Caches are added or removed from the CacheManager. The attributes of a CacheManagerEventListenerFactory are:

• class — a fully qualified factory class name.
• properties — comma-separated properties having meaning only to the factory.

Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility of the implementer to safely handle the potential performance and thread safety issues depending on what their listener is doing. If no class is specified, or there is no cacheManagerEventListenerFactory element, no listener is created. There is no default.

Implementing a CacheManager Event Listener Factory and CacheManager Event Listener

CacheManagerEventListenerFactory is an abstract factory for creating CacheManager listeners. 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 CacheManagerEventListenerFactory, which is reproduced below:

/**
* An abstract factory for creating {@link CacheManagerEventListener}s.
* Implementers should provide their own concrete factory extending this
* factory. It can then be configured in ehcache.xml.
*
*/
public abstract class CacheManagerEventListenerFactory {
    /**
    * Create a CacheManagerEventListener
    *
    * @param properties implementation specific properties.
    * These are configured as comma-separated name value pairs in ehcache.xml.
    * Properties may be null.
    * @return a constructed CacheManagerEventListener
    */
    public abstract CacheManagerEventListener createCacheManagerEventListener(Properties properties);
}

The factory creates a concrete implementation of CacheManagerEventListener, which is reproduced below:

/**
 * Allows implementers to register callback methods that will be executed when a
 * <code>CacheManager</code> event occurs.
 *
 * The lifecycle events are:
 * <ol>
 * <li>init
 * <li>dispose
 * </ol>
 *
 *
 * CacheManager change events are:
 * <ol>
 * <li>adding a <code>Cache</code>
 * <li>removing a <code>Cache</code>
 * </ol>
 *
 * Note that the caches that are part of the initial configuration are not considered "changes".
 * It is only caches added or removed beyond the initial config.
 *
 * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of
 * the implementer to safely handle the potential performance and thread safety issues
 * depending on what their listener is doing.
 * @author Greg Luck
 * @version $Id: CacheManagerEventListener.java 5594 2012-05-07 16:04:31Z cdennis $
 * @since 1.2
 * @see CacheEventListener
 */
public interface CacheManagerEventListener {

    /**
     * Call to start the listeners and do any other required initialisation.
     * init should also handle any work to do with the caches that are part of the initial configuration.
     * @throws CacheException - all exceptions are wrapped in CacheException
     */
    void init() throws CacheException;

    /**
     * Returns the listener status.
     * @return the status at the point in time the method is called
     */
    Status getStatus();

    /**
     * Stop the listener and free any resources.
     * @throws CacheException - all exceptions are wrapped in CacheException
     */
    void dispose() throws CacheException;

    /**
     * Called immediately after a cache has been added and activated.
     * <p/>
     * Note that the CacheManager calls this method from a synchronized method. Any attempt to
     * call a synchronized method on CacheManager from this method will cause a deadlock.
     * <p/>
     * Note that activation will also cause a CacheEventListener status change notification
     * from {@link net.sf.ehcache.Status#STATUS_UNINITIALISED} to
     * {@link net.sf.ehcache.Status#STATUS_ALIVE}. Care should be taken on processing that
     * notification because:
     * <ul>
     * <li>the cache will not yet be accessible from the CacheManager.
     * <li>the addCaches methods which cause this notification are synchronized on the
     * CacheManager. An attempt to call {@link net.sf.ehcache.CacheManager#getEhcache(String)}
     * will cause a deadlock.
     * </ul>
     * The calling method will block until this method returns.
     * <p/>
     * @param cacheName the name of the <code>Cache</code> the operation relates to
     * @see CacheEventListener
     */
    void notifyCacheAdded(String cacheName);

    /**
     * Called immediately after a cache has been disposed and removed. The calling method will
     * block until this method returns.
     * <p/>
     * Note that the CacheManager calls this method from a synchronized method. Any attempt to
     * call a synchronized method on CacheManager from this method will cause a deadlock.
     * <p/>
     * Note that a {@link CacheEventListener} status changed will also be triggered. Any
     * attempt from that notification to access CacheManager will also result in a deadlock.
     * @param cacheName the name of the <code>Cache</code> the operation relates to
     */
    void notifyCacheRemoved(String cacheName);

}

The implementations need to be placed in the classpath accessible to Ehcache. Ehcache uses the ClassLoader returned by Thread.currentThread().getContextClassLoader() to load classes.