1 /**
2 * Copyright 2003-2006 Greg Luck
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.Cache;
20 import net.sf.ehcache.Element;
21 import net.sf.ehcache.CacheException;
22
23 /**
24 * Allows implementers to register callback methods that will be executed when a cache event occurs.
25 * The events include:
26 * <ol>
27 * <li>put Element
28 * <li>update Element
29 * <li>remove Element
30 * <li>an Element expires, either because timeToLive or timeToIdle has been reached.
31 * </ol>
32 * <p/>
33 * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of the implementer
34 * to safely handle the potential performance and thread safety issues depending on what their listener is doing.
35 * <p/>
36 * Events are guaranteed to be notified in the order in which they occurred.
37 * <p/>
38 * Cache also has putQuiet and removeQuiet methods which do not notify listeners.
39 *
40 * @author Greg Luck
41 * @version $Id: CacheEventListener.java 28 2006-04-15 05:12:32Z gregluck $
42 * @see CacheManagerEventListener
43 * @since 1.2
44 */
45 public interface CacheEventListener {
46
47 /**
48 * Called immediately after an element has been removed. The remove method will block until
49 * this method returns.
50 * <p/>
51 * Ehcache does not chech for
52 * <p/>
53 * As the {@link net.sf.ehcache.Element} has been removed, only what was the key of the element is known.
54 * <p/>
55 *
56 * @param cache the cache emitting the notification
57 * @param element just deleted
58 */
59 void notifyElementRemoved(final Cache cache, final Element element) throws CacheException;
60
61 /**
62 * Called immediately after an element has been put into the cache. The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
63 * will block until this method returns.
64 * <p/>
65 * Implementers may wish to have access to the Element's fields, including value, so the element is provided.
66 * Implementers should be careful not to modify the element. The effect of any modifications is undefined.
67 *
68 * @param cache the cache emitting the notification
69 * @param element the element which was just put into the cache.
70 */
71 void notifyElementPut(final Cache cache, final Element element) throws CacheException;
72
73 /**
74 * Called immediately after an element has been put into the cache and the element already
75 * existed in the cache. This is thus an update.
76 * <p/>
77 * The {@link net.sf.ehcache.Cache#put(net.sf.ehcache.Element)} method
78 * will block until this method returns.
79 * <p/>
80 * Implementers may wish to have access to the Element's fields, including value, so the element is provided.
81 * Implementers should be careful not to modify the element. The effect of any modifications is undefined.
82 *
83 * @param cache the cache emitting the notification
84 * @param element the element which was just put into the cache.
85 */
86 void notifyElementUpdated(final Cache cache, final Element element) throws CacheException;
87
88
89 /**
90 * Called immediately after an element is <i>found</i> to be expired. The
91 * {@link net.sf.ehcache.Cache#remove(Object)} method will block until this method returns.
92 * <p/>
93 * As the {@link Element} has been expired, only what was the key of the element is known.
94 * <p/>
95 * Elements are checked for expiry in ehcache at the following times:
96 * <ul>
97 * <li>When a get request is made
98 * <li>When an element is spooled to the diskStore in accordance with a MemoryStore eviction policy
99 * <li>In the DiskStore when the expiry thread runs, which by default is
100 * {@link net.sf.ehcache.Cache#DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS}
101 * </ul>
102 * If an element is found to be expired, it is deleted and this method is notified.
103 *
104 * @param cache the cache emitting the notification
105 * @param element the element that has just expired
106 * <p/>
107 * Deadlock Warning: expiry will often come from the <code>DiskStore</code> expiry thread. It holds a lock to the
108 * DiskStorea the time the notification is sent. If the implementation of this method calls into a
109 * synchronized <code>Cache</code> method and that subsequently calls into DiskStore a deadlock will result.
110 * Accordingly implementers of this method should not call back into Cache.
111 */
112 void notifyElementExpired(final Cache cache, final Element element);
113
114
115 /**
116 * Give the replicator a chance to cleanup and free resources when no longer needed
117 */
118 void dispose();
119 }