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 Caching
• Simple creation with new of a concrete implementation, if supported by an implementation

Lookup

If Caching was used for creation, it will keep track of all CacheManagers created.

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

Named CacheManagers can be obtained using Caching.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.
<K,V> Cache<K,V>	getCache(String cacheName) Looks up a named cache.
Iterable<Cache<?,?>>	getCaches() Returns an iterable over the caches managed by this CacheManager.
String	getName() Get the name of this cache manager
Status	getStatus() Returns the status of this CacheManager.
UserTransaction	getUserTransaction() This method will return a UserTransaction.
boolean	isSupported(OptionalFeature optionalFeature) Indicates whether a optional feature is supported by this CacheManager.
boolean	removeCache(String cacheName) Remove a cache from the CacheManager.
void	shutdown() Shuts down the CacheManager.
<T> T	unwrap(Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

getName

String getName()

Get the name of this cache manager

Returns:

the name of this cache manager

getStatus

Status getStatus()

Returns the status of this CacheManager.

Calls to this method will block while the state is changing.

Returns:

one of Status todo RI should block until transition completed and needs internal transitional states

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 which creates a cache using default cache configuration is:

    Cache<Integer, Date> myCache2 = cacheManager.
           <Integer, Date>createCacheBuilder("myCache2").
           build();
 

An example usage which programmatically sets many parameters of CacheConfiguration, specifies a CacheLoader and registrs listeners is:

    Cache<Integer, String> myCache1 = cacheManager.
           <Integer, String>createCacheBuilder("myCache1").
           setCacheLoader(cl).
           setCacheLoader(cl).
           setStoreByValue(true).
           setReadThrough(true).
           setWriteThrough(false).
           setStatisticsEnabled(true).
           setTransactionEnabled(false).
           registerCacheEntryListener(listener1, NotificationScope.LOCAL, false).
           registerCacheEntryListener(listener2, NotificationScope.LOCAL, false).
           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. A cache name must consist of at least one non-whitespace character.

Returns:

the CacheBuilder for the named cache

Throws:

IllegalStateException - if the CacheManager is not in Status.STARTED state.

CacheException - if a cache with that name already exists or there was an error adding the cache to the CacheManager

IllegalArgumentException - if an illegal cache name is specified

NullPointerException - if the cache name is null

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 CacheManager is not Status.STARTED

getCaches

Iterable<Cache<?,?>> getCaches()

Returns an iterable over the caches managed by this CacheManager. This is immutable and independent of the cache manager; if the caches managed by the cache manager change the set is not affected

Returns:

an iterable over the managed Caches

Throws:

UnsupportedOperationException - if an attempt it made to remove an element

removeCache

boolean removeCache(String cacheName)

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

NullPointerException - if cacheName is null

getUserTransaction

UserTransaction getUserTransaction()

This method will return a UserTransaction.

Returns:

the UserTransaction.

Throws:

UnsupportedOperationException - if JTA is not supported

isSupported

boolean isSupported(OptionalFeature optionalFeature)

Indicates whether a optional feature is supported by this CacheManager.

Parameters:

optionalFeature - the feature to check for

Returns:

true if the feature is supported

shutdown

void shutdown()

Shuts down the CacheManager.

For each cache in the cache manager the CacheLifecycle.stop() method will be invoked, in no guaranteed order. If the stop throws an exception, the exception will be consumed silently.

Calls to getStatus() will block until shutdown completes.

During the execution of the method calls to getStatus() will block. On completion the CacheManager's status is changed to Status.STOPPED, and the manager's owned caches will be empty & getCaches() will return an empty collection.

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

Throws:

IllegalStateException - if an operation is performed on CacheManager while stopping or stopped.

unwrap

<T> T unwrap(Class<T> cls)

Return an object of the specified type to allow access to the provider-specific API. If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

Parameters:

cls - the class of the object to be returned. This is normally either the underlying implementation class or an interface that it implements.

Returns:

an instance of the specified class

Throws:

IllegalArgumentException - if the provider doesn't support the specified class.