View Javadoc

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 }