javax.cache

Class Caching

java.lang.Object

javax.cache.Caching

public final class Caching
extends Object

The bootstrap and helper class for locating and managing CachingProvider implementations.

Automatic Discovery of a CachingProvider via ServiceLoader conventions

Providers may be discovered by following the SPI conventions outlined by the JDK ServiceLoader class. To be automatically discoverable, its fully qualified class name must be declared in the following file:

   META-INF/services/javax.cache.spi.CachingProvider
 

The file must be available on the classpath.

For example, in the reference implementation the contents of this file are: org.jsr107.ri.RICachingProvider

Defining the CachingProvider via a System Property

Alternatively, the fully qualified class name of an implementation's CachingProvider can be defined in the system property javax.cache.CachingProvider, in which case the specified value is used instead to resolve the CachingProvider implementation.

Maintaining a Registry of CachingProviders

Any CachingProviders which have been automatically or explicitly loaded are maintained in a registry. They will be be loaded into the registry:

1. automatically if they follow the ServiceLoader conventions
2. are explicitly loaded with getCachingProvider(String) or getCachingProvider(String, ClassLoader)
3. was specified in the javax.cache.CachingProvider system property

Subsequent calls for previously loaded CachingProviders will simply be returned, without reloading and/or reinstantiating them.

Resolving a particular CachingProvider when there is more than one

Multiple CachingProviders are permitted.

To iterate through those present use:

1. getCachingProviders()
2. getCachingProviders(ClassLoader)

Or to simply return a specific one use getCachingProvider(String) or getCachingProvider(String, ClassLoader).

Where multiple CachingProviders are present the CachingProvider returned by getters getCachingProvider() and getCachingProvider(ClassLoader) is undefined. As a result a CacheException will be thrown.

Bypassing the Caching class

The Caching class is provided for convenience but its use is not mandatory. Applications and/or Containers may instead choose to directly instantiate a CachingProvider.

Author:

Brian Oliver, Greg Luck

See Also:

ServiceLoader, CachingProvider

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Caching.CachingProviderRegistry Maintains a registry of loaded CachingProviders scoped by ClassLoader.

Field Summary

Fields

Modifier and Type	Field and Description
static String	JAVAX_CACHE_CACHING_PROVIDER The javax.cache.CachingProvider constant.

Method Summary

Methods

Modifier and Type	Method and Description
static CachingProvider	getCachingProvider() Obtains the single CachingProvider visible to the default ClassLoader, which is Thread.getContextClassLoader().
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 class name using the getDefaultClassLoader().
static CachingProvider	getCachingProvider(String fullyQualifiedClassName, ClassLoader classLoader) Obtain the CachingProvider that is implemented by the specified class name using the provided ClassLoader.
static Iterable<CachingProvider>	getCachingProviders() Obtains the CachingProviders that are available via the getDefaultClassLoader().
static Iterable<CachingProvider>	getCachingProviders(ClassLoader classLoader) Obtains the CachingProviders 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.

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

getCachingProvider

public static CachingProvider getCachingProvider()

Obtains the single CachingProvider visible to the default ClassLoader, which is Thread.getContextClassLoader().

Returns:

the CachingProvider

Throws:

CacheException - should zero, or more than one CachingProvider be available on the classpath, or it could not be loaded

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

See Also:

getCachingProviders(ClassLoader)

getCachingProviders

public static Iterable<CachingProvider> getCachingProviders()

Obtains the CachingProviders that are available via the getDefaultClassLoader().

If a javax.cache.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 (plus 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.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 (plus 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 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 name (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

getCachingProvider

public static CachingProvider getCachingProvider(String fullyQualifiedClassName,
                                 ClassLoader classLoader)

Obtain the CachingProvider that is implemented by the specified 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 name (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