Product Documentation : Ehcache Developer Guide : Cache Event Listeners : Implementing a Cache Event Listener Factory and Cache Event Listener
Implementing a Cache Event Listener Factory and Cache Event Listener
A CacheEventListenerFactory is an abstract factory for creating cache event listeners. Implementers should provide their own concrete factory, extending this abstract factory. It can then be configured in ehcache.xml. The following example demonstrates how to create an abstract CacheEventListenerFactory:
/**
* An abstract factory for creating listeners. Implementers should provide
* their own concrete factory extending this factory. It can then be configured
* in ehcache.xml
*
*/
public abstract class CacheEventListenerFactory {
/**
* Create a CacheEventListener
*
* @param properties implementation specific properties. These are configured
* as comma-separated name-value pairs in ehcache.xml
* @return a constructed CacheEventListener
*/
public abstract CacheEventListener createCacheEventListener(Properties properties);
}
The following example demonstrates how to create a concrete implementation of the CacheEventListener interface:
/**
* Allows implementers to register callback methods that will be executed when
* a cache event occurs.
* The events include:
* <ol>
* <li>put Element
* <li>update Element
* <li>remove Element
* <li>an Element expires, either because timeToLive or timeToIdle has been
* reached.
* </ol>
*
* 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.
*
* Events are guaranteed to be notified in the order in which they occurred.
*
* Cache also has putQuiet and removeQuiet methods which do not notify listeners.
*
*/
public interface CacheEventListener extends Cloneable {
/**
* Called immediately after an element has been removed. The remove method will
* block until this method returns.
*
* Ehcache does not check for
*
*
* As the {@link net.sf.ehcache.Element} has been removed, only what was the
* key of the element is known.
*
*
* @param cache the cache emitting the notification
* @param element just deleted
*/
void notifyElementRemoved(final Ehcache cache, final Element element) throws
  CacheException;
/**
* Called immediately after an element has been put into the cache. The
* {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
* will block until this method returns.
*
* Implementers may wish to have access to the Element's fields, including value,
* so the element is provided. Implementers should be careful not to modify the
* element. The effect of any modifications is undefined.
*
* @param cache the cache emitting the notification
* @param element the element which was just put into the cache.
*/
void notifyElementPut(final Ehcache cache, final Element element) throws
  CacheException;
/**
* Called immediately after an element has been put into the cache and the element
* already existed in the cache. This is thus an update.
*
* The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
* will block until this method returns.
*
* Implementers may wish to have access to the Element's fields, including value,
* so the element is provided. Implementers should be careful not to modify the
* element. The effect of any modifications is undefined.
*
* @param cache the cache emitting the notification
* @param element the element which was just put into the cache.
*/
void notifyElementUpdated(final Ehcache cache, final Element element) throws
  CacheException;
/**
* Called immediately after an element is found to be expired. The
* {@link net.sf.ehcache.Cache#remove(Object)} method will block until this
* method returns.
* As the {@link Element} has been expired, only what was the key of the element
* is known.
*
* Elements are checked for expiry in Ehcache at the following times:
* <ul>
* <li>When a get request is made
* <li>When an element is spooled to diskStore in accordance with a MemoryStore
* eviction policy
* <li>In the DiskStore when the expiry thread runs, which by default is
* {@link net.sf.ehcache.Cache#DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS}
* </ul>
* If an element is found to be expired, it is deleted and this method is
* notified.
*
* @param cache the cache emitting the notification
* @param element the element that has just expired
*
* Deadlock Warning: expiry will often come from the DiskStore
* expiry thread. It holds a lock to the DiskStore at the time the
* notification is sent. If the implementation of this method calls into a
* synchronized Cache method and that subsequently calls into
* DiskStore a deadlock will result. Accordingly implementers of this method
* should not call back into Cache.
*/
void notifyElementExpired(final Ehcache cache, final Element element);
/**
* Give the replicator a chance to cleanup and free resources when no longer
* needed
*/
void dispose();
/**
* Creates a clone of this listener. This method will only be called by Ehcache
* before a cache is initialized.
*
* This may not be possible for listeners after they have been initialized.
* Implementations should throw CloneNotSupportedException if they do not support
* clone.
* @return a clone
* @throws CloneNotSupportedException if the listener could not be cloned.
*/
public Object clone() throws CloneNotSupportedException;
}
Two other methods are also available:
*void notifyElementEvicted(Ehcache cache, Element element)
Called immediately after an element is evicted from the cache. Eviction, which happens when a cache entry is deleted from a store, should not be confused with removal, which is a result of calling Cache.removeElement(Element).
*void notifyRemoveAll(Ehcache cache)
Called during Ehcache.removeAll() to indicate that all elements have been removed from the cache in a bulk operation. The usual notifyElementRemoved(net.sf.ehcache.Ehcache, net.sf.ehcache.Element) is not called. Only one notification is emitted because performance considerations do not allow for serially processing notifications where potentially millions of elements have been bulk deleted.
The implementations need to be placed in the classpath accessible to Ehcache. For details on how the loading of these classes will be done, see Class Loading.
Copyright © 2010-2015 Software AG, Darmstadt, Germany.

Product Logo |   Feedback