net.sf.ehcache
Class CacheManager

java.lang.Object
  net.sf.ehcache.CacheManager

public class CacheManager
extends java.lang.Object

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

CacheManager may be either be a singleton if created with factory methods, or multiple instances may exist, in which case resources required by each must be unique.

A CacheManager holds references to Cache, Ehcache, and JCache objects and manages their creation and lifecycle.

Version:

$Id: CacheManager.java 612 2008-05-07 22:48:26Z gregluck $

Author:

Greg Luck

Field Summary

static java.util.List	ALL_CACHE_MANAGERS Keeps track of all known CacheManagers.
protected java.util.Map	caches Caches managed by this manager.
protected java.util.Map	ehcaches Ehcaches managed by this manager.
static java.lang.String	ENABLE_SHUTDOWN_HOOK_PROPERTY System property to enable creation of a shutdown hook for CacheManager.
protected java.util.Map	jCaches JCaches managed by this manager.

Constructor Summary

CacheManager()
Constructor.

CacheManager(Configuration configuration)
An constructor for CacheManager, which takes a configuration object, rather than one created by parsing an ehcache.xml file.

CacheManager(java.io.InputStream configurationInputStream)
An ordinary constructor for CacheManager.

CacheManager(java.lang.String configurationFileName)
An ordinary constructor for CacheManager.

CacheManager(java.net.URL configurationURL)
An ordinary constructor for CacheManager.

Method Summary

void	addCache(Cache cache) Adds a Cache to the CacheManager.
void	addCache(Ehcache cache) Adds an Ehcache to the CacheManager.
void	addCache(JCache jCache) Adds a Cache to the CacheManager.
void	addCache(java.lang.String cacheName) Adds a Ehcache based on the defaultCache with the given name.
boolean	cacheExists(java.lang.String cacheName) Checks whether a cache of type ehcache exists.
void	clearAll() Clears the contents of all caches in the CacheManager, but without removing any caches.
static CacheManager	create() A factory method to create a singleton CacheManager with default config, or return it if it exists.
static CacheManager	create(java.io.InputStream inputStream) A factory method to create a singleton CacheManager from a java.io.InputStream.
static CacheManager	create(java.lang.String configurationFileName) A factory method to create a singleton CacheManager with a specified configuration.
static CacheManager	create(java.net.URL configurationFileURL) A factory method to create a singleton CacheManager from an URL.
Cache	getCache(java.lang.String name) Returns a concrete implementation of Cache, it it is available in the CacheManager.
CacheManagerEventListener	getCacheManagerEventListener() Returns the composite listener.
CacheManagerEventListenerRegistry	getCacheManagerEventListenerRegistry() Gets the CacheManagerEventListenerRegistry.
CacheManagerPeerProvider	getCacheManagerPeerProvider() Gets the CacheManagerPeerProvider, which can be useful for programmatically adding peers.
java.lang.String[]	getCacheNames() Returns a list of the current cache names.
CacheManagerPeerListener	getCachePeerListener() When CacheManage is configured as part of a cluster, a CacheManagerPeerListener will be registered in it.
CacheManagerPeerProvider	getCachePeerProvider() Gets the CacheManagerPeerProvider For distributed caches, the peer provider finds other cache managers and their caches in the same cluster
java.lang.String	getDiskStorePath() Returns the disk store path.
Ehcache	getEhcache(java.lang.String name) Gets an Ehcache
static CacheManager	getInstance() A factory method to create a singleton CacheManager with default config, or return it if it exists.
JCache	getJCache(java.lang.String name) Gets a draft JSR107 spec JCache.
java.lang.String	getName() Gets the name of the CacheManager.
Status	getStatus() Gets the status attribute of the Ehcache
void	removalAll() Removes all caches using removeCache(java.lang.String) for each cache.
void	removeCache(java.lang.String cacheName) Remove a cache from the CacheManager.
void	replaceCacheWithDecoratedCache(Ehcache ehcache, Ehcache decoratedCache) Replaces in the map of Caches managed by this CacheManager an Ehcache with a decorated version of the same Ehcache.
void	replaceEhcacheWithJCache(Ehcache ehcache, JCache jCache) Replaces in the map of Caches managed by this CacheManager an Ehcache with a JCache decorated version of the same (see Ehcache equals method) Ehcache, in a single synchronized method.
void	setCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener) Deprecated. Use getCacheManagerEventListenerRegistry instead
void	setName(java.lang.String name) Sets the name of the CacheManager.
void	shutdown() Shuts down the CacheManager.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ALL_CACHE_MANAGERS

public static final java.util.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.

ENABLE_SHUTDOWN_HOOK_PROPERTY

public static final java.lang.String ENABLE_SHUTDOWN_HOOK_PROPERTY

System property to enable creation of a shutdown hook for CacheManager.

See Also:

Constant Field Values

ehcaches

protected final java.util.Map ehcaches

Ehcaches managed by this manager.

caches

protected final java.util.Map caches

Caches managed by this manager. A Cache is also an Ehcache. For central managment the cache is also in the ehcaches map.

jCaches

protected final java.util.Map jCaches

JCaches managed by this manager. For each JCache there is a backing ehcache stored in the ehcaches map.

Constructor Detail

CacheManager

public CacheManager(Configuration configuration)
             throws CacheException

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(java.lang.String configurationFileName)
             throws CacheException

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(String)

CacheManager

public CacheManager(java.net.URL configurationURL)
             throws CacheException

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(java.lang.String) 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(java.net.URL)

CacheManager

public CacheManager(java.io.InputStream configurationInputStream)
             throws CacheException

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(java.io.InputStream)

CacheManager

public CacheManager()
             throws CacheException

Constructor.

Throws:

CacheException

Method Detail

create

public static CacheManager create()
                           throws CacheException

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

getInstance

public static CacheManager getInstance()
                                throws CacheException

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

This has the same effect as create()

Same as create()

Returns:

the singleton CacheManager

Throws:

CacheException - if the CacheManager cannot be created

create

public static CacheManager create(java.lang.String configurationFileName)
                           throws CacheException

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.

Throws:

CacheException

create

public static CacheManager create(java.net.URL configurationFileURL)
                           throws CacheException

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(java.lang.String) 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.

Throws:

CacheException

create

public static CacheManager create(java.io.InputStream inputStream)
                           throws CacheException

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.

Throws:

CacheException

getCache

public Cache getCache(java.lang.String name)
               throws java.lang.IllegalStateException,
                      java.lang.ClassCastException

Returns a concrete implementation of Cache, it it is available in the CacheManager. Consider using getEhcache(String name) instead, which will return decorated caches that are registered.

If a decorated ehcache is registered in CacheManager, an undecorated Cache with the same name will also exist.

Returns:

a Cache, if an object of that type exists by that name, else null

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

java.lang.ClassCastException

See Also:

getEhcache(String)

getEhcache

public Ehcache getEhcache(java.lang.String name)
                   throws java.lang.IllegalStateException

Gets an Ehcache

Returns:

a Cache, if an object of type Cache exists by that name, else null

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

getJCache

public JCache getJCache(java.lang.String name)
                 throws java.lang.IllegalStateException

Gets a draft JSR107 spec JCache.

If a JCache does not exist for the name, but an ehcache does, a new JCache will be created dynamically and added to the list of JCaches managed by this CacheManager. Warning: JCache will change as the specification changes, so no guarantee of backward compatibility is made for this method.

Returns:

a JSR 107 Cache, if an object of that type exists by that name, else null

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

addCache

public void addCache(java.lang.String cacheName)
              throws java.lang.IllegalStateException,
                     ObjectExistsException,
                     CacheException

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.

java.lang.IllegalStateException

addCache

public void addCache(Cache cache)
              throws java.lang.IllegalStateException,
                     ObjectExistsException,
                     CacheException

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:

java.lang.IllegalStateException - if the cache is not Status.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(JCache jCache)
              throws java.lang.IllegalStateException,
                     ObjectExistsException,
                     CacheException

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:

jCache -

Throws:

java.lang.IllegalStateException - if the cache is not Status.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)
              throws java.lang.IllegalStateException,
                     ObjectExistsException,
                     CacheException

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:

java.lang.IllegalStateException - if the cache is not Status.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(java.lang.String cacheName)
                    throws java.lang.IllegalStateException

Checks whether a cache of type ehcache exists.

Parameters:

cacheName - the cache name to check for

Returns:

true if it exists

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

removalAll

public void removalAll()

Removes all caches using removeCache(java.lang.String) for each cache.

removeCache

public void removeCache(java.lang.String cacheName)
                 throws java.lang.IllegalStateException

Remove a cache from the CacheManager. The cache is disposed of.

Parameters:

cacheName - the cache name

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

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.

By default there is no shutdown hook (ehcache-1.3-beta2 and higher).

Set the system property net.sf.ehcache.enableShutdownHook=true to turn it on.

getCacheNames

public java.lang.String[] getCacheNames()
                                 throws java.lang.IllegalStateException

Returns a list of the current cache names.

Returns:

an array of Strings

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

getStatus

public Status getStatus()

Gets the status attribute of the Ehcache

Returns:

The status value from the Status enum class

clearAll

public void clearAll()
              throws CacheException

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 Ehcache.removeAll() mehod on each cache is called.

Throws:

CacheException

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

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

getCacheManagerEventListener

public CacheManagerEventListener getCacheManagerEventListener()

Returns the composite listener. A notification sent to this listener will notify all registered listeners.

Returns:

null if none

See Also:

"getCacheManagerEventListenerRegistry"

setCacheManagerEventListener

public void setCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)

Deprecated. Use getCacheManagerEventListenerRegistry instead

Same as getCacheManagerEventListenerRegistry().registerListener(cacheManagerEventListener); Left for backward compatiblity

Parameters:

cacheManagerEventListener - the listener to set.

See Also:

"getCacheManagerEventListenerRegistry"

getCacheManagerEventListenerRegistry

public CacheManagerEventListenerRegistry getCacheManagerEventListenerRegistry()

Gets the CacheManagerEventListenerRegistry. Add and remove listeners here.

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.

replaceCacheWithDecoratedCache

public void replaceCacheWithDecoratedCache(Ehcache ehcache,
                                           Ehcache decoratedCache)
                                    throws CacheException

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.

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:

ehcache -

decoratedCache - An implementation of Ehcache that wraps the original cache.

Throws:

CacheException - if the two caches do not equal each other.

replaceEhcacheWithJCache

public void replaceEhcacheWithJCache(Ehcache ehcache,
                                     JCache jCache)
                              throws CacheException

Replaces in the map of Caches managed by this CacheManager an Ehcache with a JCache decorated version of the same (see Ehcache equals method) Ehcache, in a single synchronized method.

Warning: JCache will change as the specification changes, so no guarantee of backward compatibility is made for this method.

Parameters:

ehcache -

jCache - A JCache that wraps the original cache.

Throws:

CacheException

getName

public java.lang.String getName()

Gets the name of the CacheManager. This is useful for distinguishing multiple CacheManagers

Returns:

the name, or the output of toString() if it is not set.

See Also:

which uses either the name or Object.toString()

setName

public void setName(java.lang.String name)

Sets the name of the CacheManager. This is useful for distinguishing multiple CacheManagers in a monitoring situation.

Parameters:

name - a name with characters legal in a JMX ObjectName

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

either the name of this CacheManager, or if unset, Object.toString()

getDiskStorePath

public java.lang.String getDiskStorePath()

Returns the disk store path. This may be null if no caches need a DiskStore and none was configured. The path cannot be changed after creation of the CacheManager. All caches take the disk store path from this value.

Returns:

the disk store path.