001: /**
002: * Copyright 2003-2007 Luck Consulting Pty Ltd
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package net.sf.ehcache.event;
016:
017: import net.sf.ehcache.CacheException;
018: import net.sf.ehcache.Ehcache;
019: import net.sf.ehcache.Element;
020:
021: /**
022: * Allows implementers to register callback methods that will be executed when a cache event
023: * occurs.
024: * The events include:
025: * <ol>
026: * <li>put Element
027: * <li>update Element
028: * <li>remove Element
029: * <li>evict Element
030: * <li>an Element expires, either because timeToLive or timeToIdle has been reached.
031: * <li>removeAll, which causes all elements to be cleared from the cache
032: * </ol>
033: * <p/>
034: * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of
035: * the implementer to safely handle the potential performance and thread safety issues
036: * depending on what their listener is doing.
037: * <p/>
038: * Cache also has putQuiet and removeQuiet methods which do not notify listeners.
039: *
040: * @author Greg Luck
041: * @version $Id: CacheEventListener.java 519 2007-07-27 07:11:45Z gregluck $
042: * @see CacheManagerEventListener
043: * @since 1.2
044: */
045: public interface CacheEventListener extends Cloneable {
046:
047: /**
048: * Called immediately after an attempt to remove an element. The remove method will block until
049: * this method returns.
050: * <p/>
051: * This notification is received regardless of whether the cache had an element matching
052: * the removal key or not. If an element was removed, the element is passed to this method,
053: * otherwise a synthetic element, with only the key set is passed in.
054: * <p/>
055: * This notification is not called for the following special cases:
056: * <ol>
057: * <li>removeAll was called. See {@link #notifyRemoveAll(net.sf.ehcache.Ehcache)}
058: * <li>An element was evicted from the cache.
059: * See {@link #notifyElementEvicted(net.sf.ehcache.Ehcache, net.sf.ehcache.Element)}
060: * </ol>
061: *
062: * @param cache the cache emitting the notification
063: * @param element the element just deleted, or a synthetic element with just the key set if
064: * no element was removed.
065: */
066: void notifyElementRemoved(final Ehcache cache, final Element element)
067: throws CacheException;
068:
069: /**
070: * Called immediately after an element has been put into the cache. The
071: * {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
072: * will block until this method returns.
073: * <p/>
074: * Implementers may wish to have access to the Element's fields, including value, so the
075: * element is provided. Implementers should be careful not to modify the element. The
076: * effect of any modifications is undefined.
077: *
078: * @param cache the cache emitting the notification
079: * @param element the element which was just put into the cache.
080: */
081: void notifyElementPut(final Ehcache cache, final Element element)
082: throws CacheException;
083:
084: /**
085: * Called immediately after an element has been put into the cache and the element already
086: * existed in the cache. This is thus an update.
087: * <p/>
088: * The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
089: * will block until this method returns.
090: * <p/>
091: * Implementers may wish to have access to the Element's fields, including value, so the
092: * element is provided. Implementers should be careful not to modify the element. The
093: * effect of any modifications is undefined.
094: *
095: * @param cache the cache emitting the notification
096: * @param element the element which was just put into the cache.
097: */
098: void notifyElementUpdated(final Ehcache cache, final Element element)
099: throws CacheException;
100:
101: /**
102: * Called immediately after an element is <i>found</i> to be expired. The
103: * {@link net.sf.ehcache.Cache#remove(Object)} method will block until this method returns.
104: * <p/>
105: * As the {@link Element} has been expired, only what was the key of the element is known.
106: * <p/>
107: * Elements are checked for expiry in ehcache at the following times:
108: * <ul>
109: * <li>When a get request is made
110: * <li>When an element is spooled to the diskStore in accordance with a MemoryStore
111: * eviction policy
112: * <li>In the DiskStore when the expiry thread runs, which by default is
113: * {@link net.sf.ehcache.Cache#DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS}
114: * </ul>
115: * If an element is found to be expired, it is deleted and this method is notified.
116: *
117: * @param cache the cache emitting the notification
118: * @param element the element that has just expired
119: * <p/>
120: * Deadlock Warning: expiry will often come from the <code>DiskStore</code>
121: * expiry thread. It holds a lock to the DiskStorea the time the
122: * notification is sent. If the implementation of this method calls into a
123: * synchronized <code>Cache</code> method and that subsequently calls into
124: * DiskStore a deadlock will result. Accordingly implementers of this method
125: * should not call back into Cache.
126: */
127: void notifyElementExpired(final Ehcache cache, final Element element);
128:
129: /**
130: * Called immediately after an element is evicted from the cache. Evicted in this sense
131: * means evicted from one store and not moved to another, so that it exists nowhere in the
132: * local cache.
133: * <p/>
134: * In a sense the Element has been <i>removed</i> from the cache, but it is different,
135: * thus the separate notification.
136: *
137: * @param cache the cache emitting the notification
138: * @param element the element that has just been evicted
139: */
140: void notifyElementEvicted(final Ehcache cache, final Element element);
141:
142: /**
143: * Called during {@link net.sf.ehcache.Ehcache#removeAll()} to indicate that the all
144: * elements have been removed from the cache in a bulk operation. The usual
145: * {@link #notifyElementRemoved(net.sf.ehcache.Ehcache, net.sf.ehcache.Element)}
146: * is not called.
147: * <p/>
148: * This notification exists because clearing a cache is a special case. It is often
149: * not practical to serially process notifications where potentially millions of elements
150: * have been bulk deleted.
151: * @param cache the cache emitting the notification
152: */
153: void notifyRemoveAll(final Ehcache cache);
154:
155: /**
156: * Give the listener a chance to cleanup and free resources when no longer needed
157: */
158: void dispose();
159:
160: /**
161: * Creates a clone of this listener. This method will only be called by ehcache before a
162: * cache is initialized.
163: * <p/>
164: * This may not be possible for listeners after they have been initialized. Implementations
165: * should throw CloneNotSupportedException if they do not support clone.
166: *
167: * @return a clone
168: * @throws CloneNotSupportedException if the listener could not be cloned.
169: */
170: public Object clone() throws CloneNotSupportedException;
171:
172: }
|