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.Status;
21
22 /***
23 * Allows implementers to register callback methods that will be executed when a
24 * <code>CacheManager</code> event occurs.
25 *
26 * The lifecycle events are:
27 * <ol>
28 * <li>init
29 * <li>dispose
30 * </ol>
31 *
32 *
33 * CacheManager change events are:
34 * <ol>
35 * <li>adding a <code>Cache</code>
36 * <li>removing a <code>Cache</code>
37 * </ol>
38 *
39 * Note that the caches that are part of the initial configuration are not considered "changes".
40 * It is only caches added or removed beyond the initial config.
41 *
42 * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of
43 * the implementer to safely handle the potential performance and thread safety issues
44 * depending on what their listener is doing.
45 * @author Greg Luck
46 * @version $Id: CacheManagerEventListener.html 13146 2011-08-01 17:12:39Z oletizi $
47 * @since 1.2
48 * @see CacheEventListener
49 */
50 public interface CacheManagerEventListener {
51
52 /***
53 * Call to start the listeners and do any other required initialisation.
54 * init should also handle any work to do with the caches that are part of the initial configuration.
55 * @throws CacheException - all exceptions are wrapped in CacheException
56 */
57 void init() throws CacheException;
58
59
60 /***
61 * Returns the listener status.
62 * @return the status at the point in time the method is called
63 */
64 Status getStatus();
65
66 /***
67 * Stop the listener and free any resources.
68 * @throws CacheException - all exceptions are wrapped in CacheException
69 */
70 void dispose() throws CacheException;
71
72 /***
73 * Called immediately after a cache has been added and activated.
74 * <p/>
75 * Note that the CacheManager calls this method from a synchronized method. Any attempt to
76 * call a synchronized method on CacheManager from this method will cause a deadlock.
77 * <p/>
78 * Note that activation will also cause a CacheEventListener status change notification
79 * from {@link net.sf.ehcache.Status#STATUS_UNINITIALISED} to
80 * {@link net.sf.ehcache.Status#STATUS_ALIVE}. Care should be taken on processing that
81 * notification because:
82 * <ul>
83 * <li>the cache will not yet be accessible from the CacheManager.
84 * <li>the addCaches methods which cause this notification are synchronized on the
85 * CacheManager. An attempt to call {@link net.sf.ehcache.CacheManager#getEhcache(String)}
86 * will cause a deadlock.
87 * </ul>
88 * The calling method will block until this method returns.
89 * <p/>
90 * @param cacheName the name of the <code>Cache</code> the operation relates to
91 * @see CacheEventListener
92 */
93 void notifyCacheAdded(String cacheName);
94
95 /***
96 * Called immediately after a cache has been disposed and removed. The calling method will
97 * block until this method returns.
98 * <p/>
99 * Note that the CacheManager calls this method from a synchronized method. Any attempt to
100 * call a synchronized method on CacheManager from this method will cause a deadlock.
101 * <p/>
102 * Note that a {@link CacheEventListener} status changed will also be triggered. Any
103 * attempt from that notification to access CacheManager will also result in a deadlock.
104 * @param cacheName the name of the <code>Cache</code> the operation relates to
105 */
106 void notifyCacheRemoved(String cacheName);
107
108 }