net.sf.ehcache

Class CacheManager

public class CacheManager extends Object

A container for Ehcaches that maintain all aspects of their lifecycle.

CacheManager is meant to have one singleton per virtual machine. Its creational methods are implemented so as to make it a singleton. The design reasons for one CacheManager per VM are:

  1. The CacheManager will by default look for a resource named ehcache.xml, or failing that ehcache-failsafe.xml
  2. Persistent stores write files to a directory
  3. Event listeners are given cache names as arguments. They are assured the cache is referenceable through a single CacheManager.

Version: $Id: CacheManager.java 191 2006-09-03 22:41:48Z gregluck $

Author: Greg Luck

Field Summary
static ListALL_CACHE_MANAGERS
Keeps track of all known CacheManagers.
protected Mapcaches
Caches managed by this manager.
Constructor Summary
CacheManager(Configuration configuration)
An constructor for CacheManager, which takes a configuration object, rather than one created by parsing an ehcache.xml file.
CacheManager(String configurationFileName)
An ordinary constructor for CacheManager.
CacheManager(URL configurationURL)
An ordinary constructor for CacheManager.
CacheManager(InputStream configurationInputStream)
An ordinary constructor for CacheManager.
CacheManager()
Constructor.
Method Summary
voidaddCache(String cacheName)
Adds a Ehcache based on the defaultCache with the given name.
voidaddCache(Cache cache)
Adds a Cache to the CacheManager.
voidaddCache(Ehcache cache)
Adds an Ehcache to the CacheManager.
booleancacheExists(String cacheName)
Checks whether a cache exists.
voidclearAll()
Clears the contents of all caches in the CacheManager, but without removing any caches.
static CacheManagercreate()
A factory method to create a singleton CacheManager with default config, or return it if it exists.
static CacheManagercreate(String configurationFileName)
A factory method to create a singleton CacheManager with a specified configuration.
static CacheManagercreate(URL configurationFileURL)
A factory method to create a singleton CacheManager from an URL.
static CacheManagercreate(InputStream inputStream)
A factory method to create a singleton CacheManager from a java.io.InputStream.
CachegetCache(String name)
Returns a concrete implementation of Cache.
CacheManagerEventListenergetCacheManagerEventListener()
Gets the CacheManager event listener.
CacheManagerPeerProvidergetCacheManagerPeerProvider()
Gets the CacheManagerPeerProvider, which can be useful for programmatically adding peers.
String[]getCacheNames()
Returns a list of the current cache names.
CacheManagerPeerListenergetCachePeerListener()
When CacheManage is configured as part of a cluster, a CacheManagerPeerListener will be registered in it.
CacheManagerPeerProvidergetCachePeerProvider()
Gets the CacheManagerPeerProvider For distributed caches, the peer provider finds other cache managers and their caches in the same cluster
EhcachegetEhcache(String name)
Gets an Ehcache
static CacheManagergetInstance()
A factory method to create a singleton CacheManager with default config, or return it if it exists.
StatusgetStatus()
Gets the status attribute of the Ehcache
voidremovalAll()
Removes all caches using CacheManager for each cache.
voidremoveCache(String cacheName)
Remove a cache from the CacheManager.
voidreplaceCacheWithDecoratedCache(Ehcache cache, Ehcache decoratedCache)
Replaces in the map of Caches managed by this CacheManager an Ehcache with a decorated version of the same Ehcache.
voidsetCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)
Sets the CacheManager event listener.
voidshutdown()
Shuts down the CacheManager.

Field Detail

ALL_CACHE_MANAGERS

public static final List ALL_CACHE_MANAGERS
Keeps track of all known CacheManagers. Used to check on conflicts. CacheManagers should remove themselves from this list during shut down.

caches

protected final Map caches
Caches managed by this manager.

Constructor Detail

CacheManager

public CacheManager(Configuration configuration)
An constructor for CacheManager, which takes a configuration object, rather than one created by parsing an ehcache.xml file. This constructor gives complete control over the creation of the CacheManager.

Care should be taken to ensure that, if multiple CacheManages are created, they do now overwrite each others disk store files, as would happend if two were created which used the same diskStore path.

This method does not act as a singleton. Callers must maintain their own reference to it.

Note that if one of the create methods are called, a new singleton instance will be created, separate from any instances created in this method.

Parameters: configuration

Throws: CacheException

CacheManager

public CacheManager(String configurationFileName)
An ordinary constructor for CacheManager. This method does not act as a singleton. Callers must maintain a reference to it. Note that if one of the create methods are called, a new singleton will be created, separate from any instances created in this method.

Parameters: configurationFileName an xml configuration file available through a file name. The configuration File is created using new File(configurationFileName)

Throws: CacheException

See Also: create

CacheManager

public CacheManager(URL configurationURL)
An ordinary constructor for CacheManager. This method does not act as a singleton. Callers must maintain a reference to it. Note that if one of the create methods are called, a new singleton will be created, separate from any instances created in this method.

This method can be used to specify a configuration resource in the classpath other than the default of \"/ehcache.xml\":

 URL url = this.getClass().getResource("/ehcache-2.xml");
 
Note that Class#getResource will look for resources in the same package unless a leading "/" is used, in which case it will look in the root of the classpath.

You can also load a resource using other class loaders. e.g. Thread#getContextClassLoader()

Parameters: configurationURL an xml configuration available through a URL.

Throws: CacheException

Since: 1.2

See Also: create

CacheManager

public CacheManager(InputStream configurationInputStream)
An ordinary constructor for CacheManager. This method does not act as a singleton. Callers must maintain a reference to it. Note that if one of the create methods are called, a new singleton will be created, separate from any instances created in this method.

Parameters: configurationInputStream an xml configuration file available through an inputstream

Throws: CacheException

See Also: create

CacheManager

public CacheManager()
Constructor.

Throws: CacheException

Method Detail

addCache

public void addCache(String cacheName)
Adds a Ehcache based on the defaultCache with the given name.

Memory and Disk stores will be configured for it and it will be added to the map of caches.

Also notifies the CacheManagerEventListener after the cache was initialised and added.

It will be created with the defaultCache attributes specified in ehcache.xml

Parameters: cacheName the name for the cache

Throws: ObjectExistsException if the cache already exists CacheException if there was an error creating the cache.

addCache

public void addCache(Cache cache)
Adds a Cache to the CacheManager.

Memory and Disk stores will be configured for it and it will be added to the map of caches. Also notifies the CacheManagerEventListener after the cache was initialised and added.

Parameters: cache

Throws: IllegalStateException if the cache is not STATUS_UNINITIALISED before this method is called. ObjectExistsException if the cache already exists in the CacheManager CacheException if there was an error adding the cache to the CacheManager

addCache

public void addCache(Ehcache cache)
Adds an Ehcache to the CacheManager.

Memory and Disk stores will be configured for it and it will be added to the map of caches. Also notifies the CacheManagerEventListener after the cache was initialised and added.

Parameters: cache

Throws: IllegalStateException if the cache is not STATUS_UNINITIALISED before this method is called. ObjectExistsException if the cache already exists in the CacheManager CacheException if there was an error adding the cache to the CacheManager

cacheExists

public boolean cacheExists(String cacheName)
Checks whether a cache exists.

Parameters: cacheName the cache name to check for

Returns: true if it exists

Throws: IllegalStateException if the cache is not STATUS_ALIVE

clearAll

public void clearAll()
Clears the contents of all caches in the CacheManager, but without removing any caches.

This method is not synchronized. It only guarantees to clear those elements in a cache at the time that the removeAll mehod on each cache is called.

create

public static CacheManager create()
A factory method to create a singleton CacheManager with default config, or return it if it exists.

The configuration will be read, Ehcaches created and required stores initialized. When the CacheManager is no longer required, call shutdown to free resources.

Returns: the singleton CacheManager

Throws: CacheException if the CacheManager cannot be created

create

public static CacheManager create(String configurationFileName)
A factory method to create a singleton CacheManager with a specified configuration.

Parameters: configurationFileName an xml file compliant with the ehcache.xsd schema

The configuration will be read, Ehcaches created and required stores initialized. When the CacheManager is no longer required, call shutdown to free resources.

create

public static CacheManager create(URL configurationFileURL)
A factory method to create a singleton CacheManager from an URL.

This method can be used to specify a configuration resource in the classpath other than the default of \"/ehcache.xml\": This method can be used to specify a configuration resource in the classpath other than the default of \"/ehcache.xml\":

 URL url = this.getClass().getResource("/ehcache-2.xml");
 
Note that Class#getResource will look for resources in the same package unless a leading "/" is used, in which case it will look in the root of the classpath.

You can also load a resource using other class loaders. e.g. Thread#getContextClassLoader()

Parameters: configurationFileURL an URL to an xml file compliant with the ehcache.xsd schema

The configuration will be read, Ehcaches created and required stores initialized. When the CacheManager is no longer required, call shutdown to free resources.

create

public static CacheManager create(InputStream inputStream)
A factory method to create a singleton CacheManager from a java.io.InputStream.

This method makes it possible to use an inputstream for configuration. Note: it is the clients responsibility to close the inputstream.

Parameters: inputStream InputStream of xml compliant with the ehcache.xsd schema

The configuration will be read, Ehcaches created and required stores initialized. When the CacheManager is no longer required, call shutdown to free resources.

getCache

public Cache getCache(String name)
Returns a concrete implementation of Cache. Consider using the getEhcache method which returns an interface

Throws: IllegalStateException if the cache is not STATUS_ALIVE ClassCastException is the Ehcache found is not a Cache

See Also:

getCacheManagerEventListener

public CacheManagerEventListener getCacheManagerEventListener()
Gets the CacheManager event listener.

Returns: null if none

getCacheManagerPeerProvider

public CacheManagerPeerProvider getCacheManagerPeerProvider()
Gets the CacheManagerPeerProvider, which can be useful for programmatically adding peers. Adding peers will only be useful if the peer providers are manually provided rather than automatically discovered, otherwise they will go stale.

Returns: the CacheManagerPeerProvider, or null if there is not one.

getCacheNames

public String[] getCacheNames()
Returns a list of the current cache names.

Returns: an array of Strings

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getCachePeerListener

public CacheManagerPeerListener getCachePeerListener()
When CacheManage is configured as part of a cluster, a CacheManagerPeerListener will be registered in it. Use this to access the individual cache listeners

Returns: the listener, or null if one does not exist

getCachePeerProvider

public CacheManagerPeerProvider getCachePeerProvider()
Gets the CacheManagerPeerProvider For distributed caches, the peer provider finds other cache managers and their caches in the same cluster

Returns: the provider, or null if one does not exist

getEhcache

public Ehcache getEhcache(String name)
Gets an Ehcache

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getInstance

public static CacheManager getInstance()
A factory method to create a singleton CacheManager with default config, or return it if it exists.

This has the same effect as CacheManager

Same as create

Returns: the singleton CacheManager

Throws: CacheException if the CacheManager cannot be created

getStatus

public Status getStatus()
Gets the status attribute of the Ehcache

Returns: The status value from the Status enum class

removalAll

public void removalAll()
Removes all caches using CacheManager for each cache.

removeCache

public void removeCache(String cacheName)
Remove a cache from the CacheManager. The cache is disposed of.

Parameters: cacheName the cache name

Throws: IllegalStateException if the cache is not STATUS_ALIVE

replaceCacheWithDecoratedCache

public void replaceCacheWithDecoratedCache(Ehcache cache, Ehcache decoratedCache)
Replaces in the map of Caches managed by this CacheManager an Ehcache with a decorated version of the same Ehcache. CacheManager can operate fully with a decorated Ehcache.

Decorators can be used to obtain different behaviour from an Ehcache in a very flexible way. Some examples in ehcache are:

  1. BlockingCache - A cache that blocks other threads from getting a null element until the first thread has placed a value in it.
  2. SelfPopulatingCache - A BlockingCache that has the additional property of knowing how to load its own entries.
Many other kinds are possible.

It is generally required that a decorated cache, once constructed, is made available to other execution threads. The simplest way of doing this is to substitute the original cache for the decorated one here.

Note that any overwritten Ehcache methods will take on new behaviours without casting. Casting is only required for new methods that the decorator introduces. For more information see the well known Gang of Four Decorator pattern.

Parameters: cache decoratedCache An implementation of Ehcache that wraps the original cache.

Throws: CacheException if the two caches do not equal each other.

setCacheManagerEventListener

public void setCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)
Sets the CacheManager event listener. Any existing listener is disposed and removed first.

Parameters: cacheManagerEventListener the listener to set.

shutdown

public void shutdown()
Shuts down the CacheManager.

If the shutdown occurs on the singleton, then the singleton is removed, so that if a singleton access method is called, a new singleton will be created.