Interface CacheManager
-
- All Superinterfaces:
java.lang.AutoCloseable
,java.io.Closeable
public interface CacheManager extends java.io.Closeable
ACacheManager
provides a means of establishing, configuring, acquiring, closing and destroying uniquely namedCache
s.Cache
s produced and owned by aCacheManager
typically share common infrastructure, for example, a commonClassLoader
and implementation specificProperties
.Implementations of
CacheManager
may additionally provide and share external resources between theCache
s being managed, for example, the content of the managedCache
s may be stored in the same cluster.By default
CacheManager
instances are typically acquired through the use of aCachingProvider
. Implementations however may additionally provide other mechanisms to create, acquire, manage and configureCacheManager
s, including:- making use of
ServiceLoader
s, - 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 configuredCachingProvider
obtained by theCaching
class. For example:CachingProvider provider = Caching.getCachingProvider(); CacheManager manager = provider.getCacheManager();
Within a Java process
CacheManager
s and theCache
s they manage are scoped and uniquely identified by aURI
, the meaning of which is implementation specific. To obtain the defaultURI
,ClassLoader
andProperties
for an implementation, consult theCachingProvider
class.- Since:
- 1.0
- See Also:
Caching
,CachingProvider
,Cache
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Closes theCacheManager
.<K,V,C extends Configuration<K,V>>
Cache<K,V>createCache(java.lang.String cacheName, C configuration)
Creates a namedCache
at runtime.void
destroyCache(java.lang.String cacheName)
Destroys a specifically named and managedCache
.void
enableManagement(java.lang.String cacheName, boolean enabled)
Controls whether management is enabled.void
enableStatistics(java.lang.String cacheName, boolean enabled)
Enables or disables statistics gathering for a managedCache
at runtime.<K,V>
Cache<K,V>getCache(java.lang.String cacheName)
Looks up a managedCache
given its name.<K,V>
Cache<K,V>getCache(java.lang.String cacheName, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
Looks up a managedCache
given its name.java.lang.Iterable<java.lang.String>
getCacheNames()
CachingProvider
getCachingProvider()
Get theCachingProvider
that created and is responsible for theCacheManager
.java.lang.ClassLoader
getClassLoader()
Get theClassLoader
used by theCacheManager
.java.util.Properties
getProperties()
Get theProperties
that were used to create thisCacheManager
.java.net.URI
getURI()
Get the URI of theCacheManager
.boolean
isClosed()
Determines whether theCacheManager
instance has been closed.<T> T
unwrap(java.lang.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 theCachingProvider
that created and is responsible for theCacheManager
.- Returns:
- the CachingProvider or
null
if theCacheManager
was created without using aCachingProvider
-
getURI
java.net.URI getURI()
Get the URI of theCacheManager
.- Returns:
- the URI of the
CacheManager
-
getClassLoader
java.lang.ClassLoader getClassLoader()
Get theClassLoader
used by theCacheManager
.- Returns:
- the
ClassLoader
used by theCacheManager
-
getProperties
java.util.Properties getProperties()
Get theProperties
that were used to create thisCacheManager
.Implementations are not required to re-configure the
CacheManager
should modifications to the returnedProperties
be made.- Returns:
- the Properties used to create the
CacheManager
-
createCache
<K,V,C extends Configuration<K,V>> Cache<K,V> createCache(java.lang.String cacheName, C configuration) throws java.lang.IllegalArgumentException
Creates a namedCache
at runtime.If a
Cache
with the specified name is known to theCacheManager
, a CacheException is thrown.If a
Cache
with the specified name is unknown theCacheManager
, one is created according to the providedConfiguration
after which it becomes managed by theCacheManager
.Prior to a
Cache
being created, the providedConfiguration
s is validated within the context of theCacheManager
properties and implementation.Implementers should be aware that the
Configuration
may be used to configure otherCache
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-configureCache
s, thus removing the requirement to configure them in an application. In such circumstances a developer may simply call either thegetCache(String)
orgetCache(String, Class, Class)
methods to acquire a previously established or pre-configuredCache
.- Type Parameters:
K
- the type of keyV
- the type of valueC
- the type of the Configuration- Parameters:
cacheName
- the name of theCache
. Names should not use forward slashes(/) or colons(:), or start with java. or javax. These prefixes are reserved.configuration
- aConfiguration
for theCache
- Throws:
java.lang.IllegalStateException
- if theCacheManager
isClosed()
CacheException
- if there was an error configuring theCache
, which includes trying to create a cache that already exists.java.lang.IllegalArgumentException
- if the configuration is invalidjava.lang.UnsupportedOperationException
- if the configuration specifies an unsupported featurejava.lang.NullPointerException
- if the cache configuration or name is nulljava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
getCache
<K,V> Cache<K,V> getCache(java.lang.String cacheName, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
Looks up a managedCache
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-configuredCache
instead ofnull
.- Type Parameters:
K
- the type of keyV
- the type of value- Parameters:
cacheName
- the name of the managedCache
to acquirekeyType
- the expectedClass
of the keyvalueType
- the expectedClass
of the value- Returns:
- the Cache or null if it does exist or can't be pre-configured
- Throws:
java.lang.IllegalStateException
- if theCacheManager
isisClosed()
java.lang.ClassCastException
- if the specified key and/or value types are incompatible with the configured cache.java.lang.NullPointerException
- if either keyType or classType is null.java.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
getCache
<K,V> Cache<K,V> getCache(java.lang.String cacheName)
Looks up a managedCache
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 acquireCache
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-configuredCache
instead ofnull
.- Type Parameters:
K
- the type of keyV
- 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:
java.lang.IllegalStateException
- if the CacheManager isisClosed()
java.lang.SecurityException
- when the operation could not be performed due to the current security settings- See Also:
getCache(String, Class, Class)
-
getCacheNames
java.lang.Iterable<java.lang.String> getCacheNames()
Obtains anIterable
over the names ofCache
s managed by theCacheManager
.Iterator
s returned by theIterable
are immutable. If theCache
s managed by theCacheManager
change, theIterable
and associatedIterator
s are not affected.Iterator
s returned by theIterable
may not provide all of theCache
s managed by theCacheManager
. For example: Internally defined or platform specificCache
s that may be accessible by a call togetCache(String)
orgetCache(String, Class, Class)
may not be present in an iteration.- Returns:
- an
Iterable
over the names of managedCache
s. - Throws:
java.lang.IllegalStateException
- if theCacheManager
isisClosed()
java.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
destroyCache
void destroyCache(java.lang.String cacheName)
Destroys a specifically named and managedCache
. Once destroyed a newCache
of the same name but with a differentConfiguration
may be configured.This is equivalent to the following sequence of method calls:
followed by allowing the name of theCache
to be used for otherCache
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 theCache
will throw anIllegalStateException
.- Parameters:
cacheName
- the cache to destroy- Throws:
java.lang.IllegalStateException
- if theCacheManager
isClosed()
java.lang.NullPointerException
- if cacheName is nulljava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
enableManagement
void enableManagement(java.lang.String cacheName, boolean enabled)
Controls whether management is enabled. If enabled theCacheMXBean
for each cache is registered in the platform MBean server. The platform MBeanServer is obtained usingManagementFactory.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 registerenabled
- true to enable management, false to disable.- Throws:
java.lang.IllegalStateException
- if theCacheManager
orCache
isClosed()
java.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
enableStatistics
void enableStatistics(java.lang.String cacheName, boolean enabled)
Enables or disables statistics gathering for a managedCache
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 registerenabled
- true to enable statistics, false to disable.- Throws:
java.lang.IllegalStateException
- if theCacheManager
orCache
isClosed()
java.lang.NullPointerException
- if cacheName is nulljava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
close
void close()
Closes theCacheManager
.For each
Cache
managed by theCacheManager
, theCache.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 returntrue
.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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
java.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
isClosed
boolean isClosed()
Determines whether theCacheManager
instance has been closed. ACacheManager
is considered closed if;- the
close()
method has been called - the associated
getCachingProvider()
has been closed, or - the
CacheManager
has been closed using the associatedgetCachingProvider()
This method generally cannot be called to determine whether the
CacheManager
is valid or invalid. A typical client can determine that aCacheManager
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
- the
-
unwrap
<T> T unwrap(java.lang.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 underlyingCacheManager
- Parameters:
clazz
- the proprietary class or interface of the underlying concreteCacheManager
. It is this type that is returned.- Returns:
- an instance of the underlying concrete
CacheManager
- Throws:
java.lang.IllegalArgumentException
- if the caching provider doesn't support the specified class.java.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
-