ehcache

net.sf.ehcache
Class CacheManager

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

public class CacheManager
extends 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 Caches and Ehcaches and manages their creation and lifecycle.

Version:
$Id: CacheManager.java 8927 2014-04-15 22:06:53Z teck $
Author:
Greg Luck

Field Summary
static List<CacheManager> ALL_CACHE_MANAGERS
          Keeps track of all known CacheManagers.
protected  CacheManagerEventListenerRegistry cacheManagerEventListenerRegistry
          The listener registry
protected  Map<String,CacheManagerPeerListener> cacheManagerPeerListeners
          The map of listeners
protected  Map<String,CacheManagerPeerProvider> cacheManagerPeerProviders
          The map of providers
static String DEFAULT_NAME
          Default name if not specified in the configuration/
static String ENABLE_SHUTDOWN_HOOK_PROPERTY
          System property to enable creation of a shutdown hook for CacheManager.
static double ON_HEAP_THRESHOLD
          Threshold, in percent of the available heap, above which the CacheManager will warn if the configured memory
protected  Thread shutdownHook
          The shutdown hook thread for CacheManager.
protected  Status status
          Status of the Cache 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(InputStream configurationInputStream)
          An ordinary constructor for CacheManager.
CacheManager(String configurationFileName)
          An ordinary constructor for CacheManager.
CacheManager(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(String cacheName)
          Adds a Ehcache based on the defaultCache with the given name.
 Ehcache addCacheIfAbsent(Ehcache cache)
          Only adds the cache to the CacheManager should not one with the same name already be present
 Ehcache addCacheIfAbsent(String cacheName)
          Only creates and adds the cache to the CacheManager should not one with the same name already be present
 void addDecoratedCache(Ehcache decoratedCache)
          Adds a decorated Ehcache to the CacheManager.
 void addDecoratedCacheIfAbsent(Ehcache decoratedCache)
          Same as addDecoratedCache(Ehcache) but does not throw exception if another cache with same name already exists.
 boolean cacheExists(String cacheName)
          Checks whether a cache of type ehcache exists.
protected  void checkStatus()
          Checks the state of the CacheManager for legal operation
 void clearAll()
          Clears the contents of all caches in the CacheManager, but without removing any caches.
 void clearAllStartingWith(String prefix)
          Clears the contents of all caches in the CacheManager with a name starting with the prefix, but without removing them.
static CacheManager create()
          A factory method to create a singleton CacheManager with default config, or return it if it exists.
static CacheManager create(Configuration config)
          A factory method to create a singleton CacheManager from a net.sf.ehcache.config.Configuration.
static CacheManager create(InputStream inputStream)
          A factory method to create a singleton CacheManager from a java.io.InputStream.
static CacheManager create(String configurationFileName)
          A factory method to create a singleton CacheManager with a specified configuration.
static CacheManager create(URL configurationFileURL)
          A factory method to create a singleton CacheManager from an URL.
 CacheEventListener createTerracottaEventReplicator(Ehcache cache)
          Create/access the appropriate clustered cache event replicator for the given cache
 Store createTerracottaStore(Ehcache cache)
          Create/access the appropriate terracotta clustered store for the given cache
 WriteBehind createTerracottaWriteBehind(Ehcache cache)
          Create/access the appropriate clustered write behind queue for the given cache
 String getActiveConfigurationText()
          Returns the active configuration text for this CacheManager
 String getActiveConfigurationText(String cacheName)
          Returns the active configuration text for the input cacheName
 Cache getCache(String name)
          Returns a concrete implementation of Cache, it it is available in the CacheManager.
static CacheManager getCacheManager(String name)
          Checks if a cacheManager already exists for a given name and gets it.
 CacheManagerEventListener getCacheManagerEventListener()
          Returns the composite listener.
 CacheManagerEventListenerRegistry getCacheManagerEventListenerRegistry()
          Gets the CacheManagerEventListenerRegistry.
 CacheManagerPeerProvider getCacheManagerPeerProvider(String scheme)
          Gets the CacheManagerPeerProvider, matching the given scheme For distributed caches, the peer provider finds other cache managers and their caches in the same cluster
 Map<String,CacheManagerPeerProvider> getCacheManagerPeerProviders()
           
 String[] getCacheNames()
          Returns a list of the current cache names.
 CacheManagerPeerListener getCachePeerListener(String scheme)
          When CacheManage is configured as part of a cluster, a CacheManagerPeerListener will be registered in it.
 CacheCluster getCluster(ClusterScheme scheme)
          Returns access to information about the cache cluster.
protected  ClusteredInstanceFactory getClusteredInstanceFactory()
          Return the clustered instance factory for a cache of this cache manager.
 String getClusterUUID()
          Returns unique cluster-wide id for this cache-manager.
 Configuration getConfiguration()
          Get the CacheManager configuration
 DiskStorePathManager getDiskStorePathManager()
          Returns the disk store path manager.
 Ehcache getEhcache(String name)
          Gets an Ehcache

 FeaturesManager getFeaturesManager()
          Get the features manager.
static CacheManager getInstance()
          A factory method to create a singleton CacheManager with default config, or return it if it exists.
 String getName()
          Gets the name of the CacheManager.
 Pool getOnDiskPool()
          Return this cache manager's shared on-disk pool
 Pool getOnHeapPool()
          Return this cache manager's shared on-heap pool
 TransactionIDFactory getOrCreateTransactionIDFactory()
          Get or create a TransactionIDFactory
 String getOriginalConfigurationText()
          Returns the original configuration text for this CacheManager
 String getOriginalConfigurationText(String cacheName)
          Returns the original configuration text for the input cacheName
 Status getStatus()
          Gets the status attribute of the Ehcache
 FailSafeTimer getTimer()
          Returns a FailSafeTimer associated with this CacheManager
 TransactionController getTransactionController()
          Get the TransactionController
protected  void init(Configuration initialConfiguration, String configurationFileName, URL configurationURL, InputStream configurationInputStream)
          initialises the CacheManager
 boolean isNamed()
          Indicate whether the CacheManager is named or not.
static CacheManager newInstance()
          A factory method to create a CacheManager with default config, or return it if it exists.
static CacheManager newInstance(Configuration config)
          A factory method to create a CacheManager from a net.sf.ehcache.config.Configuration.
static CacheManager newInstance(InputStream inputStream)
          A factory method to create a CacheManager from a java.io.InputStream.
static CacheManager newInstance(String configurationFileName)
          A factory method to create a CacheManager with a specified configuration.
static CacheManager newInstance(URL configurationFileURL)
          A factory method to create a CacheManager from an URL.
 void removalAll()
          Deprecated. use removeAllCaches() instead
 void removeAllCaches()
          Removes all caches using removeCache(String) for each cache.
 void removeCache(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 setCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)
          Same as getCacheManagerEventListenerRegistry().registerListener(cacheManagerEventListener); Left for backward compatiblity
 void setName(String name)
          Sets the name of the CacheManager.
 void shutdown()
          Shuts down the CacheManager.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_NAME

public static final String DEFAULT_NAME
Default name if not specified in the configuration/

See Also:
Constant Field Values

ON_HEAP_THRESHOLD

public static final double ON_HEAP_THRESHOLD
Threshold, in percent of the available heap, above which the CacheManager will warn if the configured memory

See Also:
Constant Field Values

ALL_CACHE_MANAGERS

public static final List<CacheManager> 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 String ENABLE_SHUTDOWN_HOOK_PROPERTY
System property to enable creation of a shutdown hook for CacheManager.

See Also:
Constant Field Values

status

protected volatile Status status
Status of the Cache Manager


cacheManagerPeerProviders

protected final Map<String,CacheManagerPeerProvider> cacheManagerPeerProviders
The map of providers


cacheManagerPeerListeners

protected final Map<String,CacheManagerPeerListener> cacheManagerPeerListeners
The map of listeners


cacheManagerEventListenerRegistry

protected final CacheManagerEventListenerRegistry cacheManagerEventListenerRegistry
The listener registry


shutdownHook

protected Thread shutdownHook
The shutdown hook thread for CacheManager. This ensures that the CacheManager and Caches are left in a consistent state on a CTRL-C or kill.

This thread must be unregistered as a shutdown hook, when the CacheManager is disposed. Otherwise the CacheManager is not GC-able.

Of course kill -9 or abrupt termination will not run the shutdown hook. In this case, various sanity checks are made at start up.

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. Since 2.5, every newly created CacheManager is registered with its name (uses a default name if unnamed), and trying to create multiple CacheManager with same names (or multiple unnamed CacheManagers) is not allowed and throws an exception. It is recommended to use one of the newInstance() methods to instantiate new CacheManagers as those methods return the same instance of CacheManager for same names (or unnamed). Shutting down the CacheManager will deregister it and new ones can be created again.

Parameters:
configuration -
Throws:
CacheException

CacheManager

public CacheManager(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. Since 2.5, every newly created CacheManager is registered with its name (uses a default name if unnamed), and trying to create multiple CacheManager with same names (or multiple unnamed CacheManagers) is not allowed and throws an exception. Using any of the newInstance() methods also registers the CacheManager with its name. It is recommended to use one of the newInstance() methods to instantiate new CacheManagers as those methods return the same instance of CacheManager for same names (or unnamed). Shutting down the CacheManager will deregister it and new ones can be created again.

Parameters:
configurationFileName - an xml configuration file available through a file name. The configuration File is created using new File(configurationFileName)
Throws:
CacheException
See Also:
newInstance(String)

CacheManager

public CacheManager(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. Since 2.5, every newly created CacheManager is registered with its name (uses a default name if unnamed), and trying to create multiple CacheManager with same names (or multiple unnamed CacheManagers) is not allowed and throws an exception. Using any of the newInstance() methods also registers the CacheManager with its name. It is recommended to use one of the newInstance() methods to instantiate new CacheManagers as those methods return the same instance of CacheManager for same names (or unnamed). Shutting down the CacheManager will deregister it and new ones can be created again.

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(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:
newInstance(java.net.URL)

CacheManager

public CacheManager(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. Since 2.5, every newly created CacheManager is registered with its name (uses a default name if unnamed), and trying to create multiple CacheManager with same names (or multiple unnamed CacheManagers) is not allowed and throws an exception. Using any of the newInstance() methods also registers the CacheManager with its name. It is recommended to use one of the newInstance() methods to instantiate new CacheManagers as those methods return the same instance of CacheManager for same names (or unnamed). Shutting down the CacheManager will deregister it and new ones can be created again.

Parameters:
configurationInputStream - an xml configuration file available through an inputstream
Throws:
CacheException
See Also:
newInstance(java.io.InputStream)

CacheManager

public CacheManager()
             throws CacheException
Constructor. Since 2.5, every newly created CacheManager is registered with its name (uses a default name if unnamed), and trying to create multiple CacheManager with same names (or multiple unnamed CacheManagers) is not allowed and throws an exception. Using any of the newInstance() methods also registers the CacheManager with its name. It is recommended to use one of the newInstance() methods to instantiate new CacheManagers as those methods return the same instance of CacheManager for same names (or unnamed). Shutting down the CacheManager will deregister it and new ones can be created again.

Throws:
CacheException
Method Detail

init

protected void init(Configuration initialConfiguration,
                    String configurationFileName,
                    URL configurationURL,
                    InputStream configurationInputStream)
initialises the CacheManager


getOnHeapPool

public Pool getOnHeapPool()
Return this cache manager's shared on-heap pool

Returns:
this cache manager's shared on-heap pool

getOnDiskPool

public Pool getOnDiskPool()
Return this cache manager's shared on-disk pool

Returns:
this cache manager's shared on-disk pool

getClusterUUID

public String getClusterUUID()
Returns unique cluster-wide id for this cache-manager. Only applicable when running in "cluster" mode, e.g. when this cache-manager contains caches clustered with Terracotta. Otherwise returns blank string.

Returns:
Returns unique cluster-wide id for this cache-manager when it contains clustered caches (e.g. Terracotta clustered caches). Otherwise returns blank string.

createTerracottaStore

public Store createTerracottaStore(Ehcache cache)
Create/access the appropriate terracotta clustered store for the given cache

Parameters:
cache - The cache for which the Store should be created
Returns:
a new (or existing) clustered store

createTerracottaWriteBehind

public WriteBehind createTerracottaWriteBehind(Ehcache cache)
Create/access the appropriate clustered write behind queue for the given cache

Parameters:
cache - The cache for which the write behind queue should be created
Returns:
a new (or existing) write behind queue

createTerracottaEventReplicator

public CacheEventListener createTerracottaEventReplicator(Ehcache cache)
Create/access the appropriate clustered cache event replicator for the given cache

Parameters:
cache - The cache for which the clustered event replicator should be created
Returns:
a new cache event replicator

getClusteredInstanceFactory

protected ClusteredInstanceFactory getClusteredInstanceFactory()
Return the clustered instance factory for a cache of this cache manager.

Returns:
the clustered instance factory

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

newInstance

public static CacheManager newInstance()
                                throws CacheException
A factory method to create a 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(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

newInstance

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

If the specified configuration has different names for the CacheManager, it will return a new one for each unique name or return already created one.

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

newInstance

public static CacheManager newInstance(URL configurationFileURL)
                                throws CacheException
A factory method to create a 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(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() If the specified configuration has different names for the CacheManager, it will return a new one for each unique name or return already created one.

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

newInstance

public static CacheManager newInstance(InputStream inputStream)
                                throws CacheException
A factory method to create a 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.

If the specified configuration has different names for the CacheManager, it will return a new one for each unique name or return already created one.

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

create

public static CacheManager create(Configuration config)
                           throws CacheException
A factory method to create a singleton CacheManager from a net.sf.ehcache.config.Configuration.

Parameters:
config -
Throws:
CacheException

newInstance

public static CacheManager newInstance(Configuration config)
A factory method to create a CacheManager from a net.sf.ehcache.config.Configuration.

If the specified configuration has different names for the CacheManager, it will return a new one for each unique name or return already created one.

Parameters:
config -

getCacheManager

public static CacheManager getCacheManager(String name)
Checks if a cacheManager already exists for a given name and gets it.

Parameters:
name - the cacheManager name.
Returns:
if a cacheManager exists with given name returns the CacheManager, otherwise returns null. If name is null, returns the default unnamed cacheManager if it has been created already otherwise returns null

getCache

public Cache getCache(String name)
               throws IllegalStateException,
                      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 may also exist. Since version ehcache-core-2.1.0, when an Ehcache decorator is present in the CacheManager, its not necessary that a Cache instance is also present for the same name. Decorators can have different names other than the name of the cache its decorating.

Returns:
a Cache, if an object of that type exists by that name, else null
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
ClassCastException
See Also:
getEhcache(String)

getEhcache

public Ehcache getEhcache(String name)
                   throws IllegalStateException
Gets an Ehcache

Returns:
a Cache, if an object of type Cache exists by that name, else null
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

addCache

public void addCache(String cacheName)
              throws 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.
IllegalStateException

addCache

public void addCache(Cache cache)
              throws 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:
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 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:
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

addDecoratedCache

public void addDecoratedCache(Ehcache decoratedCache)
                       throws ObjectExistsException
Adds a decorated Ehcache to the CacheManager. This method neither creates the memory/disk store nor initializes the cache. It only adds the cache reference to the map of caches held by this cacheManager.

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 either add it to the cacheManager with a different name or substitute the original cache with the decorated one.

This method adds the decorated cache assuming it has a different name. If another cache (decorated or not) with the same name already exists, it will throw ObjectExistsException. For replacing existing cache with another decorated cache having same name, please use replaceCacheWithDecoratedCache(Ehcache, Ehcache)

Note that any overridden Ehcache methods by the decorator 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:
decoratedCache -
Throws:
ObjectExistsException - if another cache with the same name already exists.

addDecoratedCacheIfAbsent

public void addDecoratedCacheIfAbsent(Ehcache decoratedCache)
                               throws ObjectExistsException
Same as addDecoratedCache(Ehcache) but does not throw exception if another cache with same name already exists.

Parameters:
decoratedCache -
Throws:
ObjectExistsException

cacheExists

public boolean cacheExists(String cacheName)
                    throws IllegalStateException
Checks whether a cache of type ehcache exists.

Parameters:
cacheName - the cache name to check for
Returns:
true if it exists
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeAllCaches

public void removeAllCaches()
Removes all caches using removeCache(String) for each cache.


removalAll

@Deprecated
public void removalAll()
Deprecated. use removeAllCaches() instead

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


removeCache

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

Parameters:
cacheName - the cache name
Throws:
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 String[] getCacheNames()
                       throws IllegalStateException
Returns a list of the current cache names.

Returns:
an array of Strings
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

checkStatus

protected void checkStatus()
Checks the state of the CacheManager for legal operation


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

clearAllStartingWith

public void clearAllStartingWith(String prefix)
                          throws CacheException
Clears the contents of all caches in the CacheManager with a name starting with the prefix, but without removing them.

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

Parameters:
prefix - The prefix the cache name should start with
Throws:
CacheException
Since:
1.7.2

getCacheManagerPeerProvider

public CacheManagerPeerProvider getCacheManagerPeerProvider(String scheme)
Gets the CacheManagerPeerProvider, matching the given scheme For distributed caches, the peer provider finds other cache managers and their caches in the same cluster

Parameters:
scheme - the replication scheme to use. Schemes shipped with ehcache are RMI, JGROUPS, JMS
Returns:
the provider, or null if one does not exist

getCacheManagerPeerProviders

public Map<String,CacheManagerPeerProvider> getCacheManagerPeerProviders()
Returns:
Read-only map of the registered CacheManagerPeerProviders keyed by scheme.

getCachePeerListener

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

Parameters:
scheme - the replication scheme to use. Schemes shipped with ehcache are RMI, JGROUPS, JMS
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)
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.


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.

getName

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

isNamed

public boolean isNamed()
Indicate whether the CacheManager is named or not.

Returns:
True if named

setName

public void setName(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 String toString()
Overrides:
toString in class Object
Returns:
either the name of this CacheManager, or if unset, Object.toString()

getDiskStorePathManager

public DiskStorePathManager getDiskStorePathManager()
Returns the disk store path manager. 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 manager.

Returns:
the disk store path manager.

getTimer

public FailSafeTimer getTimer()
Returns a FailSafeTimer associated with this CacheManager

Returns:
The FailSafeTimer associated with this cache manager
Since:
1.7

getCluster

public CacheCluster getCluster(ClusterScheme scheme)
                        throws ClusterSchemeNotAvailableException
Returns access to information about the cache cluster.

Parameters:
scheme - The clustering scheme to retrieve information about (such as "Terracotta")
Returns:
Cluster API (never null, but possibly a simple single node implementation)
Throws:
ClusterSchemeNotAvailableException - If the CacheCluster specified by scheme is not available.
Since:
2.0
See Also:
ClusterScheme

getOriginalConfigurationText

public String getOriginalConfigurationText()
Returns the original configuration text for this CacheManager

Returns:
Returns the original configuration text for this CacheManager

getActiveConfigurationText

public String getActiveConfigurationText()
Returns the active configuration text for this CacheManager

Returns:
Returns the active configuration text for this CacheManager

getOriginalConfigurationText

public String getOriginalConfigurationText(String cacheName)
                                    throws CacheException
Returns the original configuration text for the input cacheName

Parameters:
cacheName -
Returns:
Returns the original configuration text for the input cacheName
Throws:
CacheException - if the cache with cacheName does not exist in the original config

getActiveConfigurationText

public String getActiveConfigurationText(String cacheName)
                                  throws CacheException
Returns the active configuration text for the input cacheName

Parameters:
cacheName -
Returns:
Returns the active configuration text for the input cacheName
Throws:
CacheException - if the cache with cacheName does not exist

getConfiguration

public Configuration getConfiguration()
Get the CacheManager configuration

Returns:
the configuration

addCacheIfAbsent

public Ehcache addCacheIfAbsent(Ehcache cache)
Only adds the cache to the CacheManager should not one with the same name already be present

Parameters:
cache - The Ehcache to be added
Returns:
the instance registered with the CacheManager, the cache instance passed in if it was added; or null if Ehcache is null

addCacheIfAbsent

public Ehcache addCacheIfAbsent(String cacheName)
Only creates and adds the cache to the CacheManager should not one with the same name already be present

Parameters:
cacheName - the name of the Cache to be created
Returns:
the Ehcache instance created and registered; null if cacheName was null or of length 0

getTransactionController

public TransactionController getTransactionController()
Get the TransactionController

Returns:
the TransactionController

getOrCreateTransactionIDFactory

public TransactionIDFactory getOrCreateTransactionIDFactory()
Get or create a TransactionIDFactory

Returns:
a TransactionIDFactory

getFeaturesManager

public FeaturesManager getFeaturesManager()
Get the features manager.

Returns:
the features manager

ehcache

Copyright 2001-2014, Terracotta, Inc.