1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package net.sf.ehcache.event;
18
19 import net.sf.ehcache.CacheException;
20 import net.sf.ehcache.Ehcache;
21 import net.sf.ehcache.Element;
22
23 /***
24 * Allows implementers to register callback methods that will be executed when a cache event
25 * occurs.
26 * The events include:
27 * <ol>
28 * <li>put Element
29 * <li>update Element
30 * <li>remove Element
31 * <li>evict Element
32 * <li>an Element expires, either because timeToLive or timeToIdle has been reached.
33 * <li>removeAll, which causes all elements to be cleared from the cache
34 * </ol>
35 * <p/>
36 * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of
37 * the implementer to safely handle the potential performance and thread safety issues
38 * depending on what their listener is doing.
39 * <p/>
40 * Cache also has putQuiet and removeQuiet methods which do not notify listeners.
41 *
42 * @author Greg Luck
43 * @version $Id: CacheEventListener.html 13146 2011-08-01 17:12:39Z oletizi $
44 * @see CacheManagerEventListener
45 * @since 1.2
46 */
47 public interface CacheEventListener extends Cloneable {
48
49 /***
50 * Called immediately after an attempt to remove an element. The remove method will block until
51 * this method returns.
52 * <p/>
53 * This notification is received regardless of whether the cache had an element matching
54 * the removal key or not. If an element was removed, the element is passed to this method,
55 * otherwise a synthetic element, with only the key set is passed in.
56 * <p/>
57 * This notification is not called for the following special cases:
58 * <ol>
59 * <li>removeAll was called. See {@link #notifyRemoveAll(net.sf.ehcache.Ehcache)}
60 * <li>An element was evicted from the cache.
61 * See {@link #notifyElementEvicted(net.sf.ehcache.Ehcache, net.sf.ehcache.Element)}
62 * </ol>
63 *
64 * @param cache the cache emitting the notification
65 * @param element the element just deleted, or a synthetic element with just the key set if
66 * no element was removed.
67 */
68 void notifyElementRemoved(final Ehcache cache, final Element element) throws CacheException;
69
70 /***
71 * Called immediately after an element has been put into the cache. The
72 * {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
73 * will block until this method returns.
74 * <p/>
75 * Implementers may wish to have access to the Element's fields, including value, so the
76 * element is provided. Implementers should be careful not to modify the element. The
77 * effect of any modifications is undefined.
78 *
79 * @param cache the cache emitting the notification
80 * @param element the element which was just put into the cache.
81 */
82 void notifyElementPut(final Ehcache cache, final Element element) throws CacheException;
83
84 /***
85 * Called immediately after an element has been put into the cache and the element already
86 * existed in the cache. This is thus an update.
87 * <p/>
88 * The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
89 * will block until this method returns.
90 * <p/>
91 * Implementers may wish to have access to the Element's fields, including value, so the
92 * element is provided. Implementers should be careful not to modify the element. The
93 * effect of any modifications is undefined.
94 *
95 * @param cache the cache emitting the notification
96 * @param element the element which was just put into the cache.
97 */
98 void notifyElementUpdated(final Ehcache cache, final Element element) throws CacheException;
99
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 /***
157 * Give the listener a chance to cleanup and free resources when no longer needed
158 */
159 void dispose();
160
161
162 /***
163 * Creates a clone of this listener. This method will only be called by ehcache before a
164 * cache is initialized.
165 * <p/>
166 * This may not be possible for listeners after they have been initialized. Implementations
167 * should throw CloneNotSupportedException if they do not support clone.
168 *
169 * @return a clone
170 * @throws CloneNotSupportedException if the listener could not be cloned.
171 */
172 public Object clone() throws CloneNotSupportedException;
173
174 }