CacheManager (JSR107 API and SPI 0.7 API)

```
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

Methods
Modifier and Type	Method and Description
`void`	`close()` Closes the CacheManager.
`<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`	`enableManagement(String cacheName, boolean enabled)` Controls whether management is enabled.
`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.
`CachingProvider`	`getCachingProvider()` Obtain the CachingProvider that created and is responsible for this CacheManager.
`Properties`	`getProperties()` Get the Properties that were used to create this CacheManager.
`Status`	`getStatus()` Returns the status of this CacheManager.
`URI`	`getURI()` Get the URI 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.
`<T> T`	`unwrap(Class<T> cls)` Return an object of the specified type to allow access to the provider-specific API.

- Method Detail
  - getCachingProvider
```
CachingProvider getCachingProvider()
```
    Obtain the CachingProvider that created and is responsible for this CacheManager.
    
    Returns:
    the CachingProvider or null if the CacheManager was created without using a CachingProvider
  - getURI
```
URI getURI()
```
    Get the URI of this CacheManager.
    
    Returns:
    the URI of this CacheManager
  - getProperties
```
Properties getProperties()
```
    Get the Properties that were used to create this CacheManager.
    
    Returns:
    the Properties used to create the CacheManager
  - 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.
    Each cache's statistics object must be registered with an ObjectName that is unique and has the following type and attributes:
    Type: javax.cache:type=CacheStatistics
    Required Attributes:
    - CacheManager the name of the CacheManager
    - Cache the name of the Cache
    Parameters:
    cacheName - the name of the cache to register
    enabled - true to enable statistics, false to disable.
    
    Throws:
    
    IllegalStateException - if the cache is not Status.STARTED
    
    NullPointerException - if cacheName is null
  - enableManagement
```
void enableManagement(String cacheName,
                    boolean enabled)
```
    Controls whether management is enabled. If enabled the CacheMXBean for each cache is registered in the platform MBean server. THe platform MBeanServer is obtained using ManagementFactory
    Managment information includes the name and configuration information for the cache. Each cache's management object must be registered with an ObjectName that is unique and has the following type and attributes:
    Type: javax.cache:type=Cache
    Required Attributes:
    - CacheManager the name of the CacheManager
    - Cache the name of the Cache
    Parameters:
    cacheName - the name of the cache to register
    enabled - true to enable management, false to disable.
  - close
```
void close()
```
    Closes 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.

Interface CacheManager

Creation

Lookup

Method Summary

Method Detail

getCachingProvider

getURI

getProperties

getStatus

configureCache

getCache

getCaches

removeCache

getUserTransaction

isSupported

enableStatistics

enableManagement

close

unwrap