javax.cache

Class Caching

java.lang.Object

javax.cache.Caching

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 and Description
static String	JAVAX_CACHE_CACHING_PROVIDER The javax.cache.spi.cachingprovider constant.

Method Summary

Modifier and Type	Method and 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 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.
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)