JSR107 API and SPI 1.1.1 · javax.cache.CacheManager

Method Summary

Modifier and Type	Method and Description
public void	close() Redeclares java.io.Closeable.close. Closes the `CacheManager`.
public < the type of key K, the type of value V, the type of the Configuration C extends Configuration<K, V>> Cache<K, V>	createCache(String the name of the `Cache`. Names should not use forward slashes(/) or colons(:), or start with java. or javax. These prefixes are reserved. cacheName, C a `Configuration` for the `Cache` configuration) Creates a named `Cache` at runtime.
public void	destroyCache(String the cache to destroy cacheName) Destroys a specifically named and managed `Cache`.
public void	enableManagement(String the name of the cache to register cacheName, boolean true to enable management, false to disable. enabled) Controls whether management is enabled.
public void	enableStatistics(String the name of the cache to register cacheName, boolean true to enable statistics, false to disable. enabled) Enables or disables statistics gathering for a managed `Cache` at runtime.
public < the type of key K, the type of value V> Cache<K, V>	Returns: the Cache or null if it does exist or can't be pre-configured getCache(String the name of the managed `Cache` to acquire cacheName, Class<K> the expected `Class` of the key keyType, Class<V> the expected `Class` of the value valueType) Looks up a managed `Cache` given its name.
public < the type of key K, the type of value V> Cache<K, V>	Returns: the Cache or null if it does exist or can't be pre-configured getCache(String the name of the cache to look for cacheName) Looks up a managed `Cache` given its name.
public Iterable<String>	Returns: an `Iterable` over the names of managed `Cache`s. getCacheNames() Obtains an `Iterable` over the names of `Cache`s managed by the `CacheManager`.
public CachingProvider	Returns: the CachingProvider or `null` if the `CacheManager` was created without using a `CachingProvider` getCachingProvider() Get the `CachingProvider` that created and is responsible for the `CacheManager`.
public ClassLoader	Returns: the `ClassLoader` used by the `CacheManager` getClassLoader() Get the `ClassLoader` used by the `CacheManager`.
public Properties	Returns: the Properties used to create the `CacheManager` getProperties() Get the `Properties` that were used to create this `CacheManager`.
public URI	Returns: the URI of the `CacheManager` getURI() Get the URI of the `CacheManager`.
public boolean	Returns: true if this `CacheManager` instance is closed; false if it is still open isClosed() Determines whether the `CacheManager` instance has been closed.
public < the type of the underlying `CacheManager` T> T	Returns: an instance of the underlying concrete `CacheManager` unwrap(Class<T> the proprietary class or interface of the underlying concrete `CacheManager`. It is this type that is returned. clazz) Provides a standard mechanism to access the underlying concrete caching implementation to provide access to further, proprietary features.

Method Detail

close back to summary

close	back to summary
public void close() Redeclares java.io.Closeable.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. Exceptions SecurityException: when the operation could not be performed due to the current security settings

public void close()

Redeclares java.io.Closeable.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.

Exceptions

SecurityException:: when the operation could not be performed due to the current security settings

createCache back to summary

createCache	back to summary
public <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 `Configuration`s is validated within the context of the `CacheManager` properties and implementation. Implementers should be aware that the `Configuration` may be used to configure other `Cache`s. 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 `Cache`s, 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`. Parameters <K> the type of key <V> the type of value <C> the type of the Configuration cacheName:String the name of the `Cache`. Names should not use forward slashes(/) or colons(:), or start with java. or javax. These prefixes are reserved. configuration:C a `Configuration` for the `Cache` Exceptions IllegalArgumentException: if the configuration is invalid IllegalStateException: if the `CacheManager` `isClosed()` CacheException: if there was an error configuring the `Cache`, which includes trying to create a cache that already exists. 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

public <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.

Parameters

<K>: the type of key
<V>: the type of value
<C>: the type of the Configuration
cacheName:String: the name of the Cache. Names should not use forward slashes(/) or colons(:), or start with java. or javax. These prefixes are reserved.
configuration:C: a Configuration for the Cache

Exceptions

IllegalArgumentException:: if the configuration is invalid
IllegalStateException:: if the CacheManager isClosed()
CacheException:: if there was an error configuring the Cache, which includes trying to create a cache that already exists.
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

destroyCache back to summary

destroyCache	back to summary
public 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: `Cache#clear()` `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:String the cache to destroy Exceptions IllegalStateException: if the `CacheManager` `isClosed()` NullPointerException: if cacheName is null SecurityException: when the operation could not be performed due to the current security settings

public 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:

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:String: the cache to destroy

Exceptions

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 back to summary

enableManagement	back to summary
public 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:String the name of the cache to register enabled:boolean true to enable management, false to disable. Exceptions IllegalStateException: if the `CacheManager` or `Cache` `isClosed()` SecurityException: when the operation could not be performed due to the current security settings

public 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:String: the name of the cache to register
enabled:boolean: true to enable management, false to disable.

Exceptions

IllegalStateException:: if the CacheManager or Cache isClosed()
SecurityException:: when the operation could not be performed due to the current security settings

enableStatistics back to summary

enableStatistics	back to summary
public 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:String the name of the cache to register enabled:boolean true to enable statistics, false to disable. Exceptions 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

public 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:String: the name of the cache to register
enabled:boolean: true to enable statistics, false to disable.

Exceptions

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

getCache back to summary

getCache	back to summary
public <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 `Cache`s may return a pre-configured `Cache` instead of `null`. Parameters <K> the type of key <V> the type of value cacheName:String the name of the managed `Cache` to acquire keyType:Class<K> the expected `Class` of the key valueType:Class<V> the expected `Class` of the value Returns:Cache<K, V> the Cache or null if it does exist or can't be pre-configured Exceptions 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

public <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.

Parameters

<K>: the type of key
<V>: the type of value
cacheName:String: the name of the managed Cache to acquire
keyType:Class<K>: the expected Class of the key
valueType:Class<V>: the expected Class of the value

Returns:Cache<K, V>

the Cache or null if it does exist or can't be pre-configured

Exceptions

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 back to summary

getCache	back to summary
public <K, V> Cache<K, V> getCache(String cacheName) Looks up a managed `Cache` given its name. This method may only be used to acquire `Cache`s 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 `Cache`s with a check that the supplied key and value type parameters match the runtime types. Implementations that support declarative mechanisms for pre-configuring `Cache`s may return a pre-configured `Cache` instead of `null`. Parameters <K> the type of key <V> the type of value cacheName:String the name of the cache to look for Returns:Cache<K, V> the Cache or null if it does exist or can't be pre-configured Exceptions 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)`

public <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.

Parameters

<K>: the type of key
<V>: the type of value
cacheName:String: the name of the cache to look for

Returns:Cache<K, V>

the Cache or null if it does exist or can't be pre-configured

Exceptions

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 back to summary

getCacheNames	back to summary
public Iterable<String> getCacheNames() Obtains an `Iterable` over the names of `Cache`s managed by the `CacheManager`. `java.util.Iterator`s returned by the `Iterable` are immutable. If the `Cache`s managed by the `CacheManager` change, the `Iterable` and associated `java.util.Iterator`s are not affected. `java.util.Iterator`s returned by the `Iterable` may not provide all of the `Cache`s managed by the `CacheManager`. For example: Internally defined or platform specific `Cache`s that may be accessible by a call to `getCache(String)` or `getCache(String, Class, Class)` may not be present in an iteration. Returns:Iterable<String> an `Iterable` over the names of managed `Cache`s. Exceptions IllegalStateException: if the `CacheManager` is `isClosed()` SecurityException: when the operation could not be performed due to the current security settings

public Iterable<String> getCacheNames()

Obtains an Iterable over the names of Caches managed by the CacheManager.

java.util.Iterators returned by the Iterable are immutable. If the Caches managed by the CacheManager change, the Iterable and associated java.util.Iterators are not affected.

java.util.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:Iterable<String>

an Iterable over the names of managed Caches.

Exceptions

IllegalStateException:: if the CacheManager is isClosed()
SecurityException:: when the operation could not be performed due to the current security settings

getCachingProvider back to summary

getCachingProvider	back to summary
public CachingProvider getCachingProvider() Get the `CachingProvider` that created and is responsible for the `CacheManager`. Returns:CachingProvider the CachingProvider or `null` if the `CacheManager` was created without using a `CachingProvider`

public CachingProvider getCachingProvider()

Get the CachingProvider that created and is responsible for the CacheManager.

Returns:CachingProvider: the CachingProvider or null if the CacheManager was created without using a CachingProvider

getClassLoader back to summary

getClassLoader	back to summary
public ClassLoader getClassLoader() Get the `ClassLoader` used by the `CacheManager`. Returns:ClassLoader the `ClassLoader` used by the `CacheManager`

public ClassLoader getClassLoader()

Get the ClassLoader used by the CacheManager.

Returns:ClassLoader: the ClassLoader used by the CacheManager

getProperties back to summary

getProperties	back to summary
public 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:Properties the Properties used to create the `CacheManager`

public 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:Properties: the Properties used to create the CacheManager

getURI back to summary

getURI	back to summary
public URI getURI() Get the URI of the `CacheManager`. Returns:URI the URI of the `CacheManager`

public URI getURI()

Get the URI of the CacheManager.

Returns:URI: the URI of the CacheManager

isClosed back to summary

isClosed	back to summary
public boolean isClosed() Determines whether the `CacheManager` instance has been closed. A `CacheManager` is considered closed if; the `close()` method has been called the associated `getCachingProvider()` has been closed, or 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:boolean true if this `CacheManager` instance is closed; false if it is still open

public boolean isClosed()

Determines whether the CacheManager instance has been closed. A CacheManager is considered closed if;

the close() method has been called
the associated getCachingProvider() has been closed, or
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:boolean: true if this CacheManager instance is closed; false if it is still open

unwrap back to summary

unwrap	back to summary
public <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. Parameters <T> the type of the underlying `CacheManager` clazz:Class<T> the proprietary class or interface of the underlying concrete `CacheManager`. It is this type that is returned. Returns:T an instance of the underlying concrete `CacheManager` Exceptions 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

public <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.

Parameters

<T>: the type of the underlying CacheManager
clazz:Class<T>: the proprietary class or interface of the underlying concrete CacheManager. It is this type that is returned.

Returns:T

an instance of the underlying concrete CacheManager

Exceptions

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

public Interface CacheManager

Method Summary

Method Detail