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 }