javax.cache
Interface CacheManager

public interface CacheManager

A CacheManager is used for establishing, looking up and managing the lifecycle of zero or more 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, Brian Oliver

Method Summary

<K,V> Cache<K,V>	configureCache(String cacheName, Configuration<K,V> configuration) Ensures that a Cache conforming to the specified Configuration is being managed by the CacheManager.
void	enableStatistics(String cacheName, boolean enabled) Enables or disables statistics gathering for a cache at runtime.
<K,V> Cache<K,V>	getCache(String cacheName) Looks up a Cache given it's name.
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

configureCache

<K,V> Cache<K,V> configureCache(String cacheName,
                                Configuration<K,V> configuration)

Ensures that a Cache conforming to the specified Configuration is being managed by the CacheManager. If such a Cache is unknown to the CacheManager, one is created and configured according to the provided configuration, after which it becomes managed by the said CacheManager. If such a Cache already exists, it is simply returned.

Importantly Configurations provided to this method are always validated with in the context of the CacheManager implementation. For example: Attempting use a Configuration requiring transactional support with an implementation that does not support transactions will result in an UnsupportedOperationException.

Note 1: Implementors of this method are required to make a copy of the provided Configuration so that it may be further used to configure and ensure other Caches without causing side-effects.

Note 2: There's no requirement on the part of a developer to call this method for each Cache than an application may use. This is simply because when instantiated a CacheManager may be pre-configured with one or more Caches, thus meaning there's no requirement to "configure" them in an application. In such circumstances a developer may simply call getCache(String) to retrieve a pre-configured Cache.

Parameters:

cacheName - the name of the cache

configuration - the Configuration

Returns:

a configured Cache

Throws:

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

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

InvalidConfigurationException - when the Configuration is invalid

UnsupportedOperationException - when the Configuration attempts to use an unsupported feature

NullPointerException - if the cache configuration is null

getCache

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

Looks up a Cache given it's name.

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. The Iterable is immutable (iterator.remove will throw an IllegalStateException) and independent of the cache manager; if the caches managed by the cache manager change the Iterable 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

enableStatistics

void enableStatistics(String cacheName,
                      boolean enabled)

Enables or disables statistics gathering for a cache at runtime.

Parameters:

cacheName - the name of the cache to look for

enabled - true to enable statistics, false to disable.

Throws:

IllegalStateException - if the cache is not Status.STARTED

NullPointerException - if cacheName is null

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

Calls to getStatus() will block until shutdown completes.

On completion the CacheManager's status is changed to Status.STOPPED, and the manager's owned caches will be empty and 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.