Class Caching
Caching
class provides a convenient means for an application to
acquire an appropriate CachingProvider
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 Kit ServiceLoader
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()
or
getCachingProviders(ClassLoader)
methods.
For a CachingProvider
to be automatically discoverable by the
Caching
class, the fully qualified class name of the
CachingProvider
implementation must be declared in the following
file:
META-INF/services/javax.cache.spi.CachingProviderThis 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 property
javax.cache.spi.cachingprovider
, that implementation will be used
as the default CachingProvider
.
All CachingProvider
s that are automatically detected or explicitly
declared and loaded by the Caching
class are maintained in an
internal registry. Consequently when a previously loaded
CachingProvider
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 the getCachingProvider(String)
or
getCachingProvider(String, ClassLoader)
method.
Where multiple CachingProvider
s are present, the
CachingProvider
returned by getters getCachingProvider()
and
getCachingProvider(ClassLoader)
is undefined and as a result a
CacheException
will be thrown when attempted.
- Since:
- 1.0
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Maintains a registry of loadedCachingProvider
s scoped byClassLoader
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final Caching.CachingProviderRegistry
TheCaching.CachingProviderRegistry
that tracks theCachingProvider
s.static final String
Thejavax.cache.spi.cachingprovider
constant. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <K,
V> Cache <K, V> A convenience that method that looks up a managedCache
given its name.static CachingProvider
Obtains the defaultCachingProvider
available via thegetDefaultClassLoader()
.static CachingProvider
getCachingProvider
(ClassLoader classLoader) Obtains the singleCachingProvider
visible to the specifiedClassLoader
.static CachingProvider
getCachingProvider
(String fullyQualifiedClassName) Obtain theCachingProvider
that is implemented by the specified fully qualified class name using thegetDefaultClassLoader()
.static CachingProvider
getCachingProvider
(String fullyQualifiedClassName, ClassLoader classLoader) Obtain theCachingProvider
that is implemented by the specified fully qualified class name using the providedClassLoader
.static Iterable
<CachingProvider> Obtains theCachingProvider
s that are available via thegetDefaultClassLoader()
.static Iterable
<CachingProvider> getCachingProviders
(ClassLoader classLoader) Obtains theCachingProvider
s that are available via the specifiedClassLoader
.static ClassLoader
Obtains theClassLoader
to use for API methods that don't explicitly require aClassLoader
but internally require one.static void
setDefaultClassLoader
(ClassLoader classLoader) Set theClassLoader
to use for API methods that don't explicitly require aClassLoader
, but internally use one.
-
Field Details
-
JAVAX_CACHE_CACHING_PROVIDER
Thejavax.cache.spi.cachingprovider
constant.- See Also:
-
CACHING_PROVIDERS
TheCaching.CachingProviderRegistry
that tracks theCachingProvider
s.
-
-
Constructor Details
-
Caching
private Caching()No public constructor as all methods are static.
-
-
Method Details
-
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
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
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 loadedSecurityException
- when the operation could not be performed due to the current security settings
-
getCachingProvider
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 loadedSecurityException
- when the operation could not be performed due to the current security settings- See Also:
-
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
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
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 createdSecurityException
- when the operation could not be performed due to the current security settings
-
getCachingProvider
public static CachingProvider getCachingProvider(String fullyQualifiedClassName, 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 createdSecurityException
- when the operation could not be performed due to the current security settings
-
getCache
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:
IllegalStateException
- if the CacheManager isCacheManager.isClosed()
IllegalArgumentException
- if the specified key and/or value types are incompatible with the configured cache.SecurityException
- when the operation could not be performed due to the current security settings- See Also:
-