javax.cache
Interface CacheManager

public interface CacheManager

A CacheManager is used for looking up Caches and controls their lifecycle. It represents a collection of caches.

To the extent that implementations have configuration at the CacheManager level, it is a way for these caches to share common configuration. For example a CacheManager might be clustered so all caches in that CacheManager will participate in the same cluster.

Creation

Concrete implementations can be created in a number of ways:

• Through a ServiceLoader using CacheManagerFactory
• Simple creation with new of a concrete implementation, if supported by an implementation

Lookup

If the CacheManagerFactory was used for creation, the factory will keep track of all CacheManagers created.

The default CacheManager can be obtained using CacheManagerFactory.INSTANCE.getCacheManager(). This is a useful idiom if you only want to use one CacheManager.

Named CacheManagers can be obtained using CacheManagerFactory.INSTANCE.getCacheManager(name).

Since:

1.0

Author:

Greg Luck, Yannis Cosmadopoulos

Method Summary

<K,V> CacheBuilder<K,V>	createCacheBuilder(String cacheName) Creates a new CacheBuilder for the named cache to be managed by this cache manager.
CacheConfiguration	createCacheConfiguration() Create a mutable CacheConfiguration instance.
<K,V> Cache<K,V>	getCache(String cacheName) Looks up a named cache.
Collection<Cache>	getCaches() Returns a collection of caches managed by this CacheManager
String	getName() Get the name of this cache manager
Object	getUserTransaction() This method will return a UserTransaction.
boolean	removeCache(String cacheName) Remove a cache from the CacheManager.
void	shutdown() Shuts down the CacheManager.

Method Detail

getName

String getName()

Get the name of this cache manager

Returns:

the name of this cache manager

createCacheBuilder

<K,V> CacheBuilder<K,V> createCacheBuilder(String cacheName)

Creates a new CacheBuilder for the named cache to be managed by this cache manager.

An example usage which passes in a specific programmatic CacheConfiguration and specifies a CacheLoader is:

    cacheManager.createCacheBuilder("myCache").
      setCacheConfiguration(config).
      setCacheLoader(cl).
      build();
 

An example which creates a cache using default cache configuration is:

    cacheManager.createCacheBuilder("myCache2"). build();
 

The returned CacheBuilder is associated with this CacheManager. The Cache will be created, added to the caches controlled by this CacheManager and started when CacheBuilder.build() is called. If there is an existing Cache of the same name associated with this CacheManager when build is invoked, the old Cache will be stopped.

Parameters:

cacheName - the name of the cache to build

Returns:

the CacheBuilder for the named cache

Throws:

IllegalStateException - if the cache is not CacheStatus.UNINITIALISED before this method is called.

CacheException - if there was an error adding the cache to the CacheManager

getCache

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

Looks up a named cache.

Parameters:

cacheName - the name of the cache to look for

Returns:

the Cache or null if it does exist

Throws:

IllegalStateException - if the Cache is not CacheStatus.STARTED

getCaches

Collection<Cache> getCaches()

Returns a collection of caches managed by this CacheManager

Returns:

the Caches or an empty list if there are none

Throws:

IllegalStateException - if the CacheManager is not CacheStatus.STARTED

removeCache

boolean removeCache(String cacheName)
                    throws IllegalStateException

Remove a cache from the CacheManager. The cache will be stopped.

Parameters:

cacheName - the cache name

Returns:

true if the cache was removed

Throws:

IllegalStateException - if the cache is not CacheStatus.STARTED

createCacheConfiguration

CacheConfiguration createCacheConfiguration()

Create a mutable CacheConfiguration instance. The configuration returned will have the default values defined for the CacheManager .

Returns:

a cache configuration

getUserTransaction

Object getUserTransaction()

This method will return a UserTransaction.

Returns:

the UserTransaction. This should be cast to javax.transaction.UserTransaction.

Throws:

UnsupportedOperationException - is JTA is not supported

shutdown

void shutdown()

Shuts down the CacheManager.

Each cache will be shut down in no guaranteed order. While caches are being shut down their status and the status of CacheManager is CacheStatus.STOPPING. As they are shut down their status is change to CacheStatus.STOPPED. Finally the CacheManager's status is changed to CacheStatus.STOPPED

A IllegalStateException will be thrown if an operation is performed on CacheManager or any contained Cache while they are stopping or are a stopped.

A given CacheManager instance cannot be restarted after it has been stopped. A new one must be created.