Class Caching
- java.lang.Object
-
- javax.cache.Caching
-
public final class Caching extends java.lang.Object
TheCaching
class provides a convenient means for an application to acquire an appropriateCachingProvider
implementation.While defined as part of the specification, its use is not required. Applications and/or containers may instead choose to directly instantiate a
CachingProvider
implementation based on implementation specific instructions.When using the
Caching
class,CachingProvider
implementations are automatically discovered when they follow the conventions outlined by the Java Development KitServiceLoader
class.Although automatically discovered, applications that choose to use this class should not make assumptions regarding the order in which implementations are returned by the
getCachingProviders()
orgetCachingProviders(ClassLoader)
methods.For a
CachingProvider
to be automatically discoverable by theCaching
class, the fully qualified class name of theCachingProvider
implementation must be declared in the following file:META-INF/services/javax.cache.spi.CachingProvider
This file must be resolvable via the class path.For example, in the reference implementation the contents of this file are:
org.jsr107.ri.RICachingProvider
Alternatively when the fully qualified class name of a
CachingProvider
implementation is specified using the system propertyjavax.cache.spi.cachingprovider
, that implementation will be used as the defaultCachingProvider
.All
CachingProvider
s that are automatically detected or explicitly declared and loaded by theCaching
class are maintained in an internal registry. Consequently when a previously loadedCachingProvider
is requested, it will be simply returned from the internal registry, without reloading and/or instantiating the said implementation again.As required by some applications and containers, multiple co-existing
CachingProvider
s implementations, from the same or different implementors are permitted at runtime.To iterate through those that are currently registered a developer may use the following methods:
To request a specificCachingProvider
implementation, a developer should use either thegetCachingProvider(String)
orgetCachingProvider(String, ClassLoader)
method.Where multiple
CachingProvider
s are present, theCachingProvider
returned by gettersgetCachingProvider()
andgetCachingProvider(ClassLoader)
is undefined and as a result aCacheException
will be thrown when attempted.- Since:
- 1.0
- See Also:
ServiceLoader
,CachingProvider
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Caching.CachingProviderRegistry
Maintains a registry of loadedCachingProvider
s scoped byClassLoader
.
-
Field Summary
Fields Modifier and Type Field Description private static Caching.CachingProviderRegistry
CACHING_PROVIDERS
TheCaching.CachingProviderRegistry
that tracks theCachingProvider
s.static java.lang.String
JAVAX_CACHE_CACHING_PROVIDER
Thejavax.cache.spi.cachingprovider
constant.
-
Constructor Summary
Constructors Modifier Constructor Description private
Caching()
No public constructor as all methods are static.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <K,V>
Cache<K,V>getCache(java.lang.String cacheName, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
A convenience that method that looks up a managedCache
given its name.static CachingProvider
getCachingProvider()
Obtains the defaultCachingProvider
available via thegetDefaultClassLoader()
.static CachingProvider
getCachingProvider(java.lang.ClassLoader classLoader)
Obtains the singleCachingProvider
visible to the specifiedClassLoader
.static CachingProvider
getCachingProvider(java.lang.String fullyQualifiedClassName)
Obtain theCachingProvider
that is implemented by the specified fully qualified class name using thegetDefaultClassLoader()
.static CachingProvider
getCachingProvider(java.lang.String fullyQualifiedClassName, java.lang.ClassLoader classLoader)
Obtain theCachingProvider
that is implemented by the specified fully qualified class name using the providedClassLoader
.static java.lang.Iterable<CachingProvider>
getCachingProviders()
Obtains theCachingProvider
s that are available via thegetDefaultClassLoader()
.static java.lang.Iterable<CachingProvider>
getCachingProviders(java.lang.ClassLoader classLoader)
Obtains theCachingProvider
s that are available via the specifiedClassLoader
.static java.lang.ClassLoader
getDefaultClassLoader()
Obtains theClassLoader
to use for API methods that don't explicitly require aClassLoader
but internally require one.static void
setDefaultClassLoader(java.lang.ClassLoader classLoader)
Set theClassLoader
to use for API methods that don't explicitly require aClassLoader
, but internally use one.
-
-
-
Field Detail
-
JAVAX_CACHE_CACHING_PROVIDER
public static final java.lang.String JAVAX_CACHE_CACHING_PROVIDER
Thejavax.cache.spi.cachingprovider
constant.- See Also:
- Constant Field Values
-
CACHING_PROVIDERS
private static final Caching.CachingProviderRegistry CACHING_PROVIDERS
TheCaching.CachingProviderRegistry
that tracks theCachingProvider
s.
-
-
Method Detail
-
getDefaultClassLoader
public static java.lang.ClassLoader getDefaultClassLoader()
Obtains theClassLoader
to use for API methods that don't explicitly require aClassLoader
but internally require one.By default this is the
Thread.getContextClassLoader()
.- Returns:
- the default
ClassLoader
-
setDefaultClassLoader
public static void setDefaultClassLoader(java.lang.ClassLoader classLoader)
Set theClassLoader
to use for API methods that don't explicitly require aClassLoader
, but internally use one.- Parameters:
classLoader
- theClassLoader
ornull
if the callingThread.getContextClassLoader()
should be used
-
getCachingProvider
public static CachingProvider getCachingProvider()
Obtains the defaultCachingProvider
available via thegetDefaultClassLoader()
.- Returns:
- the
CachingProvider
- Throws:
CacheException
- should zero, or more than oneCachingProvider
be available on the classpath, or it could not be loadedjava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
getCachingProvider
public static CachingProvider getCachingProvider(java.lang.ClassLoader classLoader)
Obtains the singleCachingProvider
visible to the specifiedClassLoader
.- Parameters:
classLoader
- theClassLoader
to use for loading theCachingProvider
- Returns:
- the
CachingProvider
- Throws:
CacheException
- should zero, or more than oneCachingProvider
be available on the classpath, or it could not be loadedjava.lang.SecurityException
- when the operation could not be performed due to the current security settings- See Also:
getCachingProviders(ClassLoader)
-
getCachingProviders
public static java.lang.Iterable<CachingProvider> getCachingProviders()
Obtains theCachingProvider
s that are available via thegetDefaultClassLoader()
.If a
javax.cache.spi.cachingprovider
system property is defined, only thatCachingProvider
specified by that property is returned. Otherwise allCachingProvider
s that are available via aServiceLoader
forCachingProvider
s using the defaultClassLoader
(including those previously requested viagetCachingProvider(String)
) are returned.- Returns:
- an
Iterable
ofCachingProvider
s loaded by the specifiedClassLoader
-
getCachingProviders
public static java.lang.Iterable<CachingProvider> getCachingProviders(java.lang.ClassLoader classLoader)
Obtains theCachingProvider
s that are available via the specifiedClassLoader
.If a
javax.cache.spi.cachingprovider
system property is defined, only thatCachingProvider
specified by that property is returned. Otherwise allCachingProvider
s that are available via aServiceLoader
forCachingProvider
s using the specifiedClassLoader
(including those previously requested viagetCachingProvider(String, ClassLoader)
) are returned.- Parameters:
classLoader
- theClassLoader
of the returnedCachingProvider
s- Returns:
- an
Iterable
ofCachingProvider
s loaded by the specifiedClassLoader
-
getCachingProvider
public static CachingProvider getCachingProvider(java.lang.String fullyQualifiedClassName)
Obtain theCachingProvider
that is implemented by the specified fully qualified class name using thegetDefaultClassLoader()
. Should thisCachingProvider
already be loaded it is simply returned, otherwise an attempt will be made to load and instantiate the specified class (using a no-args constructor).- Parameters:
fullyQualifiedClassName
- the fully qualified class name of theCachingProvider
- Returns:
- the
CachingProvider
- Throws:
CacheException
- if theCachingProvider
cannot be createdjava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
getCachingProvider
public static CachingProvider getCachingProvider(java.lang.String fullyQualifiedClassName, java.lang.ClassLoader classLoader)
Obtain theCachingProvider
that is implemented by the specified fully qualified class name using the providedClassLoader
. Should thisCachingProvider
already be loaded it is returned, otherwise an attempt will be made to load and instantiate the specified class (using a no-args constructor).- Parameters:
fullyQualifiedClassName
- the fully qualified class name of theCachingProvider
classLoader
- theClassLoader
to load theCachingProvider
- Returns:
- the
CachingProvider
- Throws:
CacheException
- if theCachingProvider
cannot be createdjava.lang.SecurityException
- when the operation could not be performed due to the current security settings
-
getCache
public static <K,V> Cache<K,V> getCache(java.lang.String cacheName, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
A convenience that method that looks up a managedCache
given its name. using the defaultCachingProvider
andCacheManager
. For the full range ofCache
look up methods seeCacheManager
.This method must be used for
Cache
s that were configured with runtime key and value types. UseCacheManager.getCache(String)
forCache
s where these were not specified.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 the CacheManager isCacheManager.isClosed()
java.lang.IllegalArgumentException
- if the specified key and/or value types are incompatible with the configured cache.java.lang.SecurityException
- when the operation could not be performed due to the current security settings- See Also:
CacheManager.getCache(String, Class, Class)
,CacheManager.getCache(String)
-
-