CacheManager (JSR107 API and SPI 1.1.0 API)

All Superinterfaces:

AutoCloseable, Closeable
```
public interface CacheManager
extends Closeable
```
A CacheManager provides a means of establishing, configuring, acquiring, closing and destroying uniquely named Caches.
Caches produced and owned by a CacheManager typically share common infrastructure, for example, a common ClassLoader and implementation specific Properties.
Implementations of CacheManager may additionally provide and share external resources between the Caches being managed, for example, the content of the managed Caches may be stored in the same cluster.
By default CacheManager instances are typically acquired through the use of a CachingProvider. Implementations however may additionally provide other mechanisms to create, acquire, manage and configure CacheManagers, including:
- making use of ServiceLoaders,
- permitting the use of the new operator to create a concrete implementation,
- providing the construction through the use of one or more builders, and
- through the use of dependency injection.
The default CacheManager however can always be acquired using the default configured CachingProvider obtained by the Caching class. For example:
```
 CachingProvider provider = Caching.getCachingProvider();
 CacheManager manager = provider.getCacheManager();
 
```
Within a Java process CacheManagers and the Caches they manage are scoped and uniquely identified by a URI, the meaning of which is implementation specific. To obtain the default URI, ClassLoader and Properties for an implementation, consult the CachingProvider class.
Since:

1.0

Author:

Greg Luck, Yannis Cosmadopoulos, Brian Oliver

See Also:

Caching, CachingProvider, Cache

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`close()`	Closes the `CacheManager`.
`<K,V,C extends Configuration<K,V>> Cache<K,V>`	`createCache(String cacheName, C configuration)`	Creates a named `Cache` at runtime.
`void`	`destroyCache(String cacheName)`	Destroys a specifically named and managed `Cache`.
`void`	`enableManagement(String cacheName, boolean enabled)`	Controls whether management is enabled.
`void`	`enableStatistics(String cacheName, boolean enabled)`	Enables or disables statistics gathering for a managed `Cache` at runtime.
`<K,V> Cache<K,V>`	`getCache(String cacheName)`	Looks up a managed `Cache` given its name.
`<K,V> Cache<K,V>`	`getCache(String cacheName, Class<K> keyType, Class<V> valueType)`	Looks up a managed `Cache` given its name.
`Iterable<String>`	`getCacheNames()`	Obtains an `Iterable` over the names of `Cache`s managed by the `CacheManager`.
`CachingProvider`	`getCachingProvider()`	Get the `CachingProvider` that created and is responsible for the `CacheManager`.
`ClassLoader`	`getClassLoader()`	Get the `ClassLoader` used by the `CacheManager`.
`Properties`	`getProperties()`	Get the `Properties` that were used to create this `CacheManager`.
`URI`	`getURI()`	Get the URI of the `CacheManager`.
`boolean`	`isClosed()`	Determines whether the `CacheManager` instance has been closed.
`<T> T`	`unwrap(Class<T> clazz)`	Provides a standard mechanism to access the underlying concrete caching implementation to provide access to further, proprietary features.

- Method Detail
  - getCachingProvider
```
CachingProvider getCachingProvider()
```
    Get the CachingProvider that created and is responsible for the CacheManager.
    
    Returns:
    
    the CachingProvider or null if the CacheManager was created without using a CachingProvider
  - getURI
```
URI getURI()
```
    Get the URI of the CacheManager.
    
    Returns:
    
    the URI of the CacheManager
  - getClassLoader
```
ClassLoader getClassLoader()
```
    Get the ClassLoader used by the CacheManager.
    
    Returns:
    
    the ClassLoader used by the CacheManager
  - getProperties
```
Properties getProperties()
```
    Get the Properties that were used to create this CacheManager.
    Implementations are not required to re-configure the CacheManager should modifications to the returned Properties be made.
    
    Returns:
    
    the Properties used to create the CacheManager
  - createCache
```
<K,V,C extends Configuration<K,V>> Cache<K,V> createCache(String cacheName,
                                                          C configuration)
                                                   throws IllegalArgumentException
```
    Creates a named Cache at runtime.
    If a Cache with the specified name is known to the CacheManager, a CacheException is thrown.
    If a Cache with the specified name is unknown the CacheManager, one is created according to the provided Configuration after which it becomes managed by the CacheManager.
    Prior to a Cache being created, the provided Configurations is validated within the context of the CacheManager properties and implementation.
    Implementers should be aware that the Configuration may be used to configure other Caches.
    There's no requirement on the part of a developer to call this method for each Cache an application may use. Implementations may support the use of declarative mechanisms to pre-configure Caches, thus removing the requirement to configure them in an application. In such circumstances a developer may simply call either the getCache(String) or getCache(String, Class, Class) methods to acquire a previously established or pre-configured Cache.
    
    Type Parameters:
    
    K - the type of key
    
    V - the type of value
    
    C - the type of the Configuration
    
    Parameters:
    
    cacheName - the name of the Cache. Names should not use forward slashes(/) or colons(:), or start with java. or javax. These prefixes are reserved.
    
    configuration - a Configuration for the Cache
    
    Throws:
    
    IllegalStateException - if the CacheManager isClosed()
    
    CacheException - if there was an error configuring the Cache, which includes trying to create a cache that already exists.
    
    IllegalArgumentException - if the configuration is invalid
    
    UnsupportedOperationException - if the configuration specifies an unsupported feature
    
    NullPointerException - if the cache configuration or name is null
    
    SecurityException - when the operation could not be performed due to the current security settings
  - getCache
```
<K,V> Cache<K,V> getCache(String cacheName,
                          Class<K> keyType,
                          Class<V> valueType)
```
    Looks up a managed Cache given its name.
    Use this method to check runtime key and value types.
    Use getCache(String) where this check is not required.
    Implementations must ensure that the key and value types are the same as those configured for the Cache prior to returning from this method.
    Implementations may further perform type checking on mutative cache operations and throw a ClassCastException if these checks fail.
    Implementations that support declarative mechanisms for pre-configuring Caches may return a pre-configured Cache instead of null.
    
    Type Parameters:
    
    K - the type of key
    
    V - the type of value
    
    Parameters:
    
    cacheName - the name of the managed Cache to acquire
    
    keyType - the expected Class of the key
    
    valueType - the expected Class of the value
    
    Returns:
    
    the Cache or null if it does exist or can't be pre-configured
    
    Throws:
    
    IllegalStateException - if the CacheManager is isClosed()
    
    ClassCastException - if the specified key and/or value types are incompatible with the configured cache.
    
    NullPointerException - if either keyType or classType is null.
    
    SecurityException - when the operation could not be performed due to the current security settings
  - getCache
```
<K,V> Cache<K,V> getCache(String cacheName)
```
    Looks up a managed Cache given its name.
    This method may only be used to acquire Caches that were configured without runtime key and value types, or were configured to use Object.class key and value types.
    Use the getCache(String, Class, Class) method to acquire Caches with a check that the supplied key and value type parameters match the runtime types.
    Implementations that support declarative mechanisms for pre-configuring Caches may return a pre-configured Cache instead of null.
    
    Type Parameters:
    
    K - the type of key
    
    V - the type of value
    
    Parameters:
    
    cacheName - the name of the cache to look for
    
    Returns:
    
    the Cache or null if it does exist or can't be pre-configured
    
    Throws:
    
    IllegalStateException - if the CacheManager is isClosed()
    
    SecurityException - when the operation could not be performed due to the current security settings
    
    See Also:
    
    getCache(String, Class, Class)
  - getCacheNames
```
Iterable<String> getCacheNames()
```
    Obtains an Iterable over the names of Caches managed by the CacheManager.
    Iterators returned by the Iterable are immutable. If the Caches managed by the CacheManager change, the Iterable and associated Iterators are not affected.
    Iterators returned by the Iterable may not provide all of the Caches managed by the CacheManager. For example: Internally defined or platform specific Caches that may be accessible by a call to getCache(String) or getCache(String, Class, Class) may not be present in an iteration.
    
    Returns:
    
    an Iterable over the names of managed Caches.
    
    Throws:
    
    IllegalStateException - if the CacheManager is isClosed()
    
    SecurityException - when the operation could not be performed due to the current security settings
  - destroyCache
```
void destroyCache(String cacheName)
```
    Destroys a specifically named and managed Cache. Once destroyed a new Cache of the same name but with a different Configuration may be configured.
    This is equivalent to the following sequence of method calls:
    1. Cache.clear()
    2. Cache.close()
    followed by allowing the name of the Cache to be used for other Cache configurations.
    From the time this method is called, the specified Cache is not available for operational use. An attempt to call an operational method on the Cache will throw an IllegalStateException.
    Parameters:
    
    cacheName - the cache to destroy
    
    Throws:
    
    IllegalStateException - if the CacheManager isClosed()
    
    NullPointerException - if cacheName is null
    
    SecurityException - when the operation could not be performed due to the current security settings
  - 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.getPlatformMBeanServer().
    Management 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=CacheConfiguration
    Required Attributes:
    - CacheManager the URI 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.
    
    Throws:
    
    IllegalStateException - if the CacheManager or Cache isClosed()
    
    SecurityException - when the operation could not be performed due to the current security settings
  - enableStatistics
```
void enableStatistics(String cacheName,
                      boolean enabled)
```
    Enables or disables statistics gathering for a managed 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 URI 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 CacheManager or Cache isClosed()
    
    NullPointerException - if cacheName is null
    
    SecurityException - when the operation could not be performed due to the current security settings
  - close
```
void close()
```
    Closes the CacheManager.
    For each Cache managed by the CacheManager, the Cache.close() method will be invoked, in no guaranteed order.
    If a Cache.close() call throws an exception, the exception will be ignored.
    After executing this method, the isClosed() method will return true.
    All attempts to close a previously closed CacheManager will be ignored. Closing a CacheManager does not necessarily destroy the contents of the Caches in the CacheManager.
    It simply signals that the CacheManager is no longer required by the application and that future uses of a specific CacheManager instance should not be permitted.
    Depending on the implementation and Cache topology, (e.g. a storage-backed or distributed cache), the contents of closed Caches previously referenced by the CacheManager, may still be available and accessible by other applications.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
    
    Throws:
    
    SecurityException - when the operation could not be performed due to the current security settings
  - isClosed
```
boolean isClosed()
```
    Determines whether the CacheManager instance has been closed. A CacheManager is considered closed if;
    1. the close() method has been called
    2. the associated getCachingProvider() has been closed, or
    3. the CacheManager has been closed using the associated getCachingProvider()
    This method generally cannot be called to determine whether the CacheManager is valid or invalid. A typical client can determine that a CacheManager is invalid by catching any exceptions that might be thrown when an operation is attempted.
    Returns:
    
    true if this CacheManager instance is closed; false if it is still open
  - unwrap
```
<T> T unwrap(Class<T> clazz)
```
    Provides a standard mechanism to access the underlying concrete caching implementation to provide access to further, proprietary features.
    If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.
    
    Type Parameters:
    
    T - the type of the underlying CacheManager
    
    Parameters:
    
    clazz - the proprietary class or interface of the underlying concrete CacheManager. It is this type that is returned.
    
    Returns:
    
    an instance of the underlying concrete CacheManager
    
    Throws:
    
    IllegalArgumentException - if the caching provider doesn't support the specified class.
    
    SecurityException - when the operation could not be performed due to the current security settings

Interface CacheManager

Method Summary

Method Detail

getCachingProvider

getURI

getClassLoader

getProperties

createCache

getCache

getCache

getCacheNames

destroyCache

enableManagement

enableStatistics

close

isClosed

unwrap