001: package javax.cache;
002:
003: import java.util.List;
004: import java.util.Collection;
005:
006: /**
007: * A container for caches.
008: *
009: * The CacheManager maintains all aspects of the Cache lifecycle.
010: *
011: * Caches are not started until they are added to a CacheManager
012: *
013: * Each vendor will implement CacheManager. Multiple CacheManagers can run at the same time, be registered in
014: * JNDI and so on.
015: *
016: *
017: */
018: public interface CacheManager {
019:
020: enum State {
021: STARTING, RUNNING, STOPPING, TERMINATED
022: }
023:
024: /**
025: * Returns a Cache.
026: * @param name the name of the cache
027: * @return
028: */
029: Cache getCache(String name) throws CacheException;
030:
031: /**
032: * Adds a {@link Cache} based on the default cache parameters with the given name.
033: * <p/>
034: * Memory and Disk stores will be configured for it and it will be added
035: * to the map of caches.
036: * <p/>
037: * Also notifies the CacheManagerListener after the cache was initialised and added.
038: * <p/>
039: * It will be created with the defaultCache attributes specified in ehcache.xml
040: *
041: * @param cacheName the name for the cache
042: * @throws CacheException if there was an error creating the cache, for example because the cache already exists
043: */
044: void newCache(String cacheName) throws CacheException;
045:
046: /**
047: * Adds a {@link Cache} to the CacheManager.
048: * <p/>
049: * Memory and Disk stores will be configured for it and it will be added to the map of caches.
050: * Also notifies the CacheManagerEventListener after the cache was initialised and added.
051: *
052: * @param cache
053: * @throws IllegalStateException if the cache is not {@link State#STARTED} before this method is called.
054: * @throws CacheException if there was an error adding the cache to the CacheManager, for example because the Cache already exists in the CacheManager
055: */
056: void registerCache(String name, Cache cache)
057: throws IllegalStateException, CacheException;
058:
059: /**
060: * Checks whether a cache exists.
061: * <p/>
062: *
063: * @param cacheName the cache name to check for
064: * @return true if it exists
065: * @throws IllegalStateException if the cache is not {@link State#STARTED}
066: */
067: boolean cacheExists(String cacheName) throws IllegalStateException;
068:
069: /**
070: * Remove a cache from the CacheManager. The cache is disposed of.
071: *
072: * @param cacheName the cache name
073: * @throws IllegalStateException if the cache is not {@link State#STARTED}
074: */
075: void unregisterCache(String cacheName) throws IllegalStateException;
076:
077: /**
078: * Shuts down the CacheManager.
079: */
080: void shutdown();
081:
082: /**
083: * Returns a list of the current cache names.
084: *
085: * @return an array of {@link String}s
086: * @throws IllegalStateException if the cache is not {@link State#STARTED}
087: */
088: Collection<String> getCacheNames() throws IllegalStateException;
089:
090: /**
091: * Gets the current state of the cache manager
092: *
093: * @return The status value from the State enum class
094: */
095: State getState();
096:
097: /**
098: * Gets the name of the CacheManager. This is useful for distinguishing multiple CacheManagers
099: *
100: * @return the name, or the output of toString() if it is not set.
101: * @see #toString() which uses either the name or Object.toString()
102: */
103: String getName();
104:
105: void addListener(CacheManagerListener cacheManagerListener);
106:
107: void removeListener(CacheManagerListener cacheManagerListener);
108:
109: }
|