net.sf.ehcache

Class CacheManager

public final class CacheManager extends Object

A container for Caches 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 52 2006-04-24 14:50:03Z gregluck $

Author: Greg Luck

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 Cache based on the defaultCache with the given name.
voidaddCache(Cache cache)
Adds a Cache to the CacheManager.
booleancacheExists(String cacheName)
Checks whether a cache exists.
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)
Gets a Cache
CacheManagerEventListenergetCacheManagerEventListener()
Gets the CacheManager event listener.
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
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 Cache
voidremovalAll()
Removes all caches using CacheManager for each cache.
voidremoveCache(String cacheName)
Remove a cache from the CacheManager.
voidsetCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)
Sets the CacheManager event listener.
voidshutdown()
Shuts down the CacheManager.

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

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

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, Caches 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, Caches 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, Caches 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, Caches created and required stores initialized. When the CacheManager is no longer required, call shutdown to free resources.

getCache

public Cache getCache(String name)
Gets a Cache

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getCacheManagerEventListener

public CacheManagerEventListener getCacheManagerEventListener()
Gets the CacheManager event listener.

Returns: null if none

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

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 Cache

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

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.