001: /**
002: * Copyright 2003-2007 Luck Consulting Pty Ltd
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package net.sf.ehcache.event;
016:
017: import net.sf.ehcache.CacheException;
018: import net.sf.ehcache.Status;
019:
020: /**
021: * Allows implementers to register callback methods that will be executed when a
022: * <code>CacheManager</code> event occurs.
023: *
024: * The lifecycle events are:
025: * <ol>
026: * <li>init
027: * <li>dispose
028: * </ol>
029: *
030: *
031: * CacheManager change events are:
032: * <ol>
033: * <li>adding a <code>Cache</code>
034: * <li>removing a <code>Cache</code>
035: * </ol>
036: *
037: * Note that the caches that are part of the initial configuration are not considered "changes".
038: * It is only caches added or removed beyond the initial config.
039: *
040: * Callbacks to these methods are synchronous and unsynchronized. It is the responsibility of
041: * the implementer to safely handle the potential performance and thread safety issues
042: * depending on what their listener is doing.
043: * @author Greg Luck
044: * @version $Id: CacheManagerEventListener.java 519 2007-07-27 07:11:45Z gregluck $
045: * @since 1.2
046: * @see CacheEventListener
047: */
048: public interface CacheManagerEventListener {
049:
050: /**
051: * Call to start the listeners and do any other required initialisation.
052: * init should also handle any work to do with the caches that are part of the initial configuration.
053: * @throws CacheException - all exceptions are wrapped in CacheException
054: */
055: void init() throws CacheException;
056:
057: /**
058: * Returns the listener status.
059: * @return the status at the point in time the method is called
060: */
061: Status getStatus();
062:
063: /**
064: * Stop the listener and free any resources.
065: * @throws CacheException - all exceptions are wrapped in CacheException
066: */
067: void dispose() throws CacheException;
068:
069: /**
070: * Called immediately after a cache has been added and activated.
071: * <p/>
072: * Note that the CacheManager calls this method from a synchronized method. Any attempt to
073: * call a synchronized method on CacheManager from this method will cause a deadlock.
074: * <p/>
075: * Note that activation will also cause a CacheEventListener status change notification
076: * from {@link net.sf.ehcache.Status#STATUS_UNINITIALISED} to
077: * {@link net.sf.ehcache.Status#STATUS_ALIVE}. Care should be taken on processing that
078: * notification because:
079: * <ul>
080: * <li>the cache will not yet be accessible from the CacheManager.
081: * <li>the addCaches methods which cause this notification are synchronized on the
082: * CacheManager. An attempt to call {@link net.sf.ehcache.CacheManager#getEhcache(String)}
083: * will cause a deadlock.
084: * </ul>
085: * The calling method will block until this method returns.
086: * <p/>
087: * @param cacheName the name of the <code>Cache</code> the operation relates to
088: * @see CacheEventListener
089: */
090: void notifyCacheAdded(String cacheName);
091:
092: /**
093: * Called immediately after a cache has been disposed and removed. The calling method will
094: * block until this method returns.
095: * <p/>
096: * Note that the CacheManager calls this method from a synchronized method. Any attempt to
097: * call a synchronized method on CacheManager from this method will cause a deadlock.
098: * <p/>
099: * Note that a {@link CacheEventListener} status changed will also be triggered. Any
100: * attempt from that notification to access CacheManager will also result in a deadlock.
101: * @param cacheName the name of the <code>Cache</code> the operation relates to
102: */
103: void notifyCacheRemoved(String cacheName);
104:
105: }
|