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.

CacheManagers are created by CacheManagerFactory.

Implementations may also support creation directly through CacheManager constructors which may be simpler to use where multiple vendor implementations are present. TODO (yannis): Not clear what this means in a prescriptive sense; implementations may, and indeed always do, support any number of constructors for concrete classes, as well as implement methods beyond the spec. Why do we need to enumerate them.

Since:

1.7

Author:

Greg Luck, Yannis Cosmadopoulos

Method Summary

void	addCache(Cache<?,?> cache) Adds an uninitialised Cache to the CacheManager and starts it.
<K,V> CacheBuilder<K,V>	createCacheBuilder(String cacheName) Creates a new CacheBuilder for the named cache to be managed by this cache manager.
<K,V> Cache<K,V>	getCache(String cacheName) Looks up a named cache.
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.

Example usage

    cacheManager.createCacheBuilder("myCache").
      setCacheConfiguration(config).
      setCacheLoader(cl).
      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 Status.UNITIALISED before this method is called.

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

addCache

void addCache(Cache<?,?> cache)

Adds an uninitialised Cache to the CacheManager and starts it. If a cache with the same name has been previously added that cache will be stopped.

TODO (yannis): Not clear why this is required.

Parameters:

cache - the cache to add

Throws:

IllegalStateException - if the cache is not Status.UNITIALISED 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 Status.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 Status.STARTED

getUserTransaction

Object getUserTransaction()

This method will return a UserTransaction.

Returns:

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

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 Status.STOPPING. As they are shut down their status is change to Status.STOPPED. Finally the CacheManager's status is changed to Status.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.