ehcache

net.sf.ehcache
Class CacheManager

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

public final class CacheManager
extends java.lang.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()
          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(java.lang.String cacheName)
          Adds a Cache based on the defaultCache with the given name.
 boolean cacheExists(java.lang.String cacheName)
          Checks whether a cache exists.
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)
          Gets a Cache
 CacheManagerEventListener getCacheManagerEventListener()
          Gets the CacheManager event listener.
 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
static CacheManager getInstance()
          A factory method to create a singleton CacheManager with default config, or return it if it exists.
 Status getStatus()
          Gets the status attribute of the Cache
 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 setCacheManagerEventListener(CacheManagerEventListener cacheManagerEventListener)
          Sets the CacheManager event listener.
 void shutdown()
          Shuts down the CacheManager.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

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, Caches 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, Caches 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, Caches 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
Gets a Cache

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

cacheExists

public boolean cacheExists(java.lang.String cacheName)
                    throws java.lang.IllegalStateException
Checks whether a cache 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.


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 Cache

Returns:
The status value from the Status enum class

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()
Gets the CacheManager event listener.

Returns:
null if none

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.

ehcache