```
public final class Caching
extends Object
```
The 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.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 property javax.cache.spi.cachingprovider, that implementation will be used as the default CachingProvider.
All CachingProviders 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 CachingProviders 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:
1. getCachingProviders()
2. getCachingProviders(ClassLoader)
To request a specific CachingProvider implementation, a developer should use either the getCachingProvider(String) or getCachingProvider(String, ClassLoader) method.
Where multiple CachingProviders 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

Author:

Brian Oliver, Greg Luck, Yannis Cosmadopoulos

See Also:

ServiceLoader, CachingProvider

Field Summary

Fields
Modifier and Type Field Description

static String JAVAX_CACHE_CACHING_PROVIDER
The javax.cache.spi.cachingprovider constant.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static <K,V> Cache<K,V>`	`getCache(String cacheName, Class<K> keyType, Class<V> valueType)`	A convenience that method that looks up a managed `Cache` given its name.
`static CachingProvider`	`getCachingProvider()`	Obtains the default `CachingProvider` available via the `getDefaultClassLoader()`.
`static CachingProvider`	`getCachingProvider(ClassLoader classLoader)`	Obtains the single `CachingProvider` visible to the specified `ClassLoader`.
`static CachingProvider`	`getCachingProvider(String fullyQualifiedClassName)`	Obtain the `CachingProvider` that is implemented by the specified fully qualified class name using the `getDefaultClassLoader()`.
`static CachingProvider`	`getCachingProvider(String fullyQualifiedClassName, ClassLoader classLoader)`	Obtain the `CachingProvider` that is implemented by the specified fully qualified class name using the provided `ClassLoader`.
`static Iterable<CachingProvider>`	`getCachingProviders()`	Obtains the `CachingProvider`s that are available via the `getDefaultClassLoader()`.
`static Iterable<CachingProvider>`	`getCachingProviders(ClassLoader classLoader)`	Obtains the `CachingProvider`s that are available via the specified `ClassLoader`.
`static ClassLoader`	`getDefaultClassLoader()`	Obtains the `ClassLoader` to use for API methods that don't explicitly require a `ClassLoader` but internally require one.
`static void`	`setDefaultClassLoader(ClassLoader classLoader)`	Set the `ClassLoader` to use for API methods that don't explicitly require a `ClassLoader`, but internally use one.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - JAVAX_CACHE_CACHING_PROVIDER
```
public static final String JAVAX_CACHE_CACHING_PROVIDER
```
    The javax.cache.spi.cachingprovider constant.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getDefaultClassLoader
```
public static ClassLoader getDefaultClassLoader()
```
    Obtains the ClassLoader to use for API methods that don't explicitly require a ClassLoader but internally require one.
    By default this is the Thread.getContextClassLoader().
    
    Returns:
    
    the default ClassLoader
  - setDefaultClassLoader
```
public static void setDefaultClassLoader(ClassLoader classLoader)
```
    Set the ClassLoader to use for API methods that don't explicitly require a ClassLoader, but internally use one.
    
    Parameters:
    
    classLoader - the ClassLoader or null if the calling Thread.getContextClassLoader() should be used
  - getCachingProvider
```
public static CachingProvider getCachingProvider()
```
    Obtains the default CachingProvider available via the getDefaultClassLoader().
    
    Returns:
    
    the CachingProvider
    
    Throws:
    
    CacheException - should zero, or more than one CachingProvider be available on the classpath, or it could not be loaded
    
    SecurityException - when the operation could not be performed due to the current security settings
  - getCachingProvider
```
public static CachingProvider getCachingProvider(ClassLoader classLoader)
```
    Obtains the single CachingProvider visible to the specified ClassLoader.
    
    Parameters:
    
    classLoader - the ClassLoader to use for loading the CachingProvider
    
    Returns:
    
    the CachingProvider
    
    Throws:
    
    CacheException - should zero, or more than one CachingProvider be available on the classpath, or it could not be loaded
    
    SecurityException - when the operation could not be performed due to the current security settings
    
    See Also:
    
    getCachingProviders(ClassLoader)
  - getCachingProviders
```
public static Iterable<CachingProvider> getCachingProviders()
```
    Obtains the CachingProviders that are available via the getDefaultClassLoader().
    If a javax.cache.spi.cachingprovider system property is defined, only that CachingProvider specified by that property is returned. Otherwise all CachingProviders that are available via a ServiceLoader for CachingProviders using the default ClassLoader (including those previously requested via getCachingProvider(String)) are returned.
    
    Returns:
    
    an Iterable of CachingProviders loaded by the specified ClassLoader
  - getCachingProviders
```
public static Iterable<CachingProvider> getCachingProviders(ClassLoader classLoader)
```
    Obtains the CachingProviders that are available via the specified ClassLoader.
    If a javax.cache.spi.cachingprovider system property is defined, only that CachingProvider specified by that property is returned. Otherwise all CachingProviders that are available via a ServiceLoader for CachingProviders using the specified ClassLoader (including those previously requested via getCachingProvider(String, ClassLoader)) are returned.
    
    Parameters:
    
    classLoader - the ClassLoader of the returned CachingProviders
    
    Returns:
    
    an Iterable of CachingProviders loaded by the specified ClassLoader
  - getCachingProvider
```
public static CachingProvider getCachingProvider(String fullyQualifiedClassName)
```
    Obtain the CachingProvider that is implemented by the specified fully qualified class name using the getDefaultClassLoader(). Should this CachingProvider 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 the CachingProvider
    
    Returns:
    
    the CachingProvider
    
    Throws:
    
    CacheException - if the CachingProvider cannot be created
    
    SecurityException - when the operation could not be performed due to the current security settings
  - getCachingProvider
```
public static CachingProvider getCachingProvider(String fullyQualifiedClassName,
                                                 ClassLoader classLoader)
```
    Obtain the CachingProvider that is implemented by the specified fully qualified class name using the provided ClassLoader. Should this CachingProvider 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 the CachingProvider
    
    classLoader - the ClassLoader to load the CachingProvider
    
    Returns:
    
    the CachingProvider
    
    Throws:
    
    CacheException - if the CachingProvider cannot be created
    
    SecurityException - when the operation could not be performed due to the current security settings
  - getCache
```
public static <K,V> Cache<K,V> getCache(String cacheName,
                                                    Class<K> keyType,
                                                    Class<V> valueType)
```
    A convenience that method that looks up a managed Cache given its name. using the default CachingProvider and CacheManager. For the full range of Cache look up methods see CacheManager.
    This method must be used for Caches that were configured with runtime key and value types. Use CacheManager.getCache(String) for Caches 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 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 CacheManager.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:
    
    CacheManager.getCache(String, Class, Class), CacheManager.getCache(String)

Class Caching

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JAVAX_CACHE_CACHING_PROVIDER

Method Detail

getDefaultClassLoader

setDefaultClassLoader

getCachingProvider

getCachingProvider

getCachingProviders

getCachingProviders

getCachingProvider

getCachingProvider

getCache