net.sf.ehcache.event
Interface CacheEventListener
public
interface
CacheEventListener
extends Cloneable
Allows implementers to register callback methods that will be executed when a cache event
occurs.
The events include:
- put Element
- update Element
- remove Element
- evict Element
- an Element expires, either because timeToLive or timeToIdle has been reached.
- removeAll, which causes all elements to be cleared from the 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.
Cache also has putQuiet and removeQuiet methods which do not notify listeners.
Since: 1.2
Version: $Id: CacheEventListener.java 191 2006-09-03 22:41:48Z gregluck $
Author: Greg Luck
See Also: CacheManagerEventListener
public Object clone()
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.
Returns: a clone
Throws: CloneNotSupportedException if the listener could not be cloned.
public void dispose()
Give the replicator a chance to cleanup and free resources when no longer needed
Called immediately after an element is evicted from the cache. Evicted in this sense
means evicted from one store and not moved to another, so that it exists nowhere in the
local cache.
In a sense the Element has been
removed from the cache, but it is different,
thus the separate notification.
Parameters: cache the cache emitting the notification element the element that has just been evicted
Called immediately after an element is
found to be expired. The
remove method will block until this method returns.
As the
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:
- When a get request is made
- When an element is spooled to the diskStore in accordance with a MemoryStore
eviction policy
- In the DiskStore when the expiry thread runs, which by default is
DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
If an element is found to be expired, it is deleted and this method is notified.
Parameters: cache the cache emitting the notification element the element that has just expired
Deadlock Warning: expiry will often come from the DiskStore
expiry thread. It holds a lock to the DiskStorea 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.
Called immediately after an element has been put into the cache. The
put 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.
Parameters: cache the cache emitting the notification element the element which was just put into the cache.
Called immediately after an attempt to remove an element. The remove method will block until
this method returns.
This notification is received regardless of whether the cache had an element matching
the removal key or not. If an element was removed, the element is passed to this method,
otherwise a synthetic element, with only the key set is passed in.
This notification is not called for the following special cases:
- removeAll was called. See notifyRemoveAll
- An element was evicted from the cache.
See CacheEventListener
Parameters: cache the cache emitting the notification element the element just deleted, or a synthetic element with just the key set if
no element was removed.
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
put 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.
Parameters: cache the cache emitting the notification element the element which was just put into the cache.
public void notifyRemoveAll(
Ehcache cache)
Called during
removeAll to indicate that the all
elements have been removed from the cache in a bulk operation. The usual
CacheEventListener
is not called.
This notification exists because clearing a cache is a special case. It is often
not practical to serially process notifications where potentially millions of elements
have been bulk deleted.
Parameters: cache the cache emitting the notification