org.infinispan.manager
Interface CacheManager

All Superinterfaces:

Lifecycle, Listenable

All Known Implementing Classes:

DefaultCacheManager

public interface CacheManager
extends Lifecycle, Listenable

A CacheManager is the primary mechanism for retrieving a Cache instance, and is often used as a starting point to using the Cache.

CacheManagers are heavyweight objects, and we foresee no more than one CacheManager being used per JVM (unless specific configuration requirements require more than one; but either way, this would be a minimal and finite number of instances).

Constructing a CacheManager is done via one of its constructors, which optionally take in a Configuration or a path or URL to a configuration XML file.

Lifecycle - CacheManagers have a lifecycle (it implements Lifecycle) and the default constructors also call Lifecycle.start(). Overloaded versions of the constructors are available, that do not start the CacheManager, although it must be kept in mind that CacheManagers need to be started before they can be used to create Cache instances.

Once constructed, CacheManagers should be made available to any component that requires a Cache, via JNDI or via some other mechanism such as an dependency injection framework.

You obtain Cache instances from the CacheManager by using one of the overloaded getCache(), methods. Note that with getCache(), there is no guarantee that the instance you get is brand-new and empty, since caches are named and shared. Because of this, the CacheManager also acts as a repository of Caches, and is an effective mechanism of looking up or creating Caches on demand.

When the system shuts down, it should call Lifecycle.stop() on the CacheManager. This will ensure all caches within its scope are properly stopped as well.

NB: Shared caches are supported (and in fact encouraged) but if they are used it's the users responsibility to ensure that at least one but only one caller calls stop() on the cache, and it does so with the awareness that others may be using the cache.

Sample usage: CacheManager manager = new DefaultCacheManager("my-config-file.xml"); Cache entityCache = manager.getCache("myEntityCache"); entityCache.put("aPerson", new Person());

Configuration myNewConfiguration = new Configuration(); myNewConfiguration.setCacheMode(Configuration.CacheMode.LOCAL); manager.defineConfiguration("myLocalCache", myNewConfiguration); Cache localCache = manager.getCache("myLocalCache");

Since:

4.0

Author:

Manik Surtani (manik@jboss.org), Galder Zamarreño

Method Summary

Configuration	defineConfiguration(String cacheName, Configuration configurationOverride) Defines a named cache's configuration using the following algorithm: If cache name hasn't been defined before, this method creates a clone of the default cache's configuration, applies a clone of the configuration overrides passed in and returns this configuration instance.
Configuration	defineConfiguration(String cacheName, String templateCacheName, Configuration configurationOverride) Defines a named cache's configuration using the following algorithm: Regardless of whether the cache name has been defined or not, this method creates a clone of the configuration of the cache whose name matches the given template cache name, then applies a clone of the configuration overrides passed in and finally returns this configuration instance.
Address	getAddress()
<K,V> Cache<K,V>	getCache() Retrieves the default cache associated with this cache manager.
<K,V> Cache<K,V>	getCache(String cacheName) Retrieves a named cache from the system.
Set<String>	getCacheNames() If no named caches are registered, this method returns an empty set.
String	getClusterName()
Configuration	getDefaultConfiguration() Returns default configuration for this CacheManager
GlobalConfiguration	getGlobalConfiguration() Returns global configuration for this CacheManager
List<Address>	getMembers()
ComponentStatus	getStatus()
boolean	isCoordinator()

Methods inherited from interface org.infinispan.lifecycle.Lifecycle

start, stop

Methods inherited from interface org.infinispan.notifications.Listenable

addListener, getListeners, removeListener

Method Detail

defineConfiguration

Configuration defineConfiguration(String cacheName,
                                  Configuration configurationOverride)

Defines a named cache's configuration using the following algorithm:

If cache name hasn't been defined before, this method creates a clone of the default cache's configuration, applies a clone of the configuration overrides passed in and returns this configuration instance.

If cache name has been previously defined, this method creates a clone of this cache's existing configuration, applies a clone of the configuration overrides passed in and returns the configuration instance.

The other way to define named cache's configuration is declaratively, in the XML file passed in to the cache manager. This method enables you to override certain properties that have previously been defined via XML.

Passing a brand new Configuration instance as configuration override without having called any of its setters will effectively return the named cache's configuration since no overrides where passed to it.

Parameters:

cacheName - name of cache whose configuration is being defined

configurationOverride - configuration overrides to use

Returns:

a cloned configuration instance

defineConfiguration

Configuration defineConfiguration(String cacheName,
                                  String templateCacheName,
                                  Configuration configurationOverride)

Defines a named cache's configuration using the following algorithm:

Regardless of whether the cache name has been defined or not, this method creates a clone of the configuration of the cache whose name matches the given template cache name, then applies a clone of the configuration overrides passed in and finally returns this configuration instance.

The other way to define named cache's configuration is declaratively, in the XML file passed in to the cache manager. This method enables you to override certain properties that have previously been defined via XML.

Passing a brand new Configuration instance as configuration override without having called any of its setters will effectively return the named cache's configuration since no overrides where passed to it.

If templateName is null or there isn't any named cache with that name, this methods works exactly like defineConfiguration(String, Configuration) in the sense that the base configuration used is the default cache configuration.

Parameters:

cacheName - name of cache whose configuration is being defined

templateCacheName - name of cache to which to which apply overrides if cache name has not been previously defined

configurationOverride - configuration overrides to use

Returns:

a cloned configuration instance

getCache

<K,V> Cache<K,V> getCache()

Retrieves the default cache associated with this cache manager.

As such, this method is always guaranteed to return the default cache.

NB: Shared caches are supported (and in fact encouraged) but if they are used it's the users responsibility to ensure that at least one but only one caller calls stop() on the cache, and it does so with the awareness that others may be using the cache.

Returns:

the default cache.

getCache

<K,V> Cache<K,V> getCache(String cacheName)

Retrieves a named cache from the system. If the cache has been previously created with the same name, the running cache instance is returned. Otherwise, this method attempts to create the cache first.

When creating a new cache, this method will use the configuration passed in to the CacheManager on construction, as a template, and then optionally apply any overrides previously defined for the named cache using the defineConfiguration(String, Configuration) or defineConfiguration(String, String, Configuration) methods, or declared in the configuration file.

NB: Shared caches are supported (and in fact encouraged) but if they are used it's the users responsibility to ensure that at least one but only one caller calls stop() on the cache, and it does so with the awareness that others may be using the cache.

Parameters:

cacheName - name of cache to retrieve

Returns:

a cache instance identified by cacheName

getClusterName

String getClusterName()

Returns:

the name of the cluster. Null if running in local mode.

getMembers

List<Address> getMembers()

getAddress

Address getAddress()

isCoordinator

boolean isCoordinator()

getStatus

ComponentStatus getStatus()

getGlobalConfiguration

GlobalConfiguration getGlobalConfiguration()

Returns global configuration for this CacheManager

Returns:

the global configuration object associated to this CacheManager

getDefaultConfiguration

Configuration getDefaultConfiguration()

Returns default configuration for this CacheManager

Returns:

the default configuration associated with this CacheManager

getCacheNames

Set<String> getCacheNames()

If no named caches are registered, this method returns an empty set. The default cache is never included in this set of cache names.

Returns:

an immutable set of non-default named caches registered with this cache manager.