Package javax.cache

Class Caching

java.lang.Object

javax.cache.Caching

public final class Caching
extends Object

A factory for creating CacheManagers using the SPI conventions in the JDK's ServiceLoader

For a provider to be discovered, its jar must contain a resource called:

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

containing the class name implementing CachingProvider

For example, in the reference implementation the contents are:

"javax.cache.implementation.RIServiceFactory"

If more than one CachingProvider is found, getCacheManagerFactory will throw an exception

Also keeps track of all CacheManagers created by the factory. Subsequent calls to getCacheManager() return the same CacheManager.

Since:

1.0

Author:

Yannis Cosmadopoulos

See Also:

ServiceLoader, CachingProvider

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_CACHE_MANAGER_NAME	The name of the default cache manager.

Method Summary

Modifier and Type	Method	Description
static void	close()	Reclaims all resources obtained from this factory.
static boolean	close(ClassLoader classLoader)	Reclaims all resources for a ClassLoader from this factory.
static boolean	close(ClassLoader classLoader, String name)	Reclaims all resources for a ClassLoader from this factory.
static CacheManager	getCacheManager()	Get the default cache manager with the default classloader.
static CacheManager	getCacheManager(ClassLoader classLoader)	Get the default cache manager.
static CacheManager	getCacheManager(ClassLoader classLoader, String name)	Get a named cache manager.
static CacheManager	getCacheManager(String name)	Get a named cache manager using the default cache loader as specified by the implementation.
static CacheManagerFactory	getCacheManagerFactory()	Get the singleton CacheManagerFactory
static boolean	isAnnotationsSupported()	Indicates whether annotations are supported
static boolean	isSupported(OptionalFeature optionalFeature)	Indicates whether a optional feature is supported by this implementation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CACHE_MANAGER_NAME

public static final String DEFAULT_CACHE_MANAGER_NAME

The name of the default cache manager. This is the name of the CacheManager returned when getCacheManager() is invoked. The default CacheManager is always created.

See Also:

Constant Field Values

Method Detail

getCacheManagerFactory

public static CacheManagerFactory getCacheManagerFactory()

Get the singleton CacheManagerFactory

Returns:

the cache manager factory

Throws:

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

getCacheManager

public static CacheManager getCacheManager()

Get the default cache manager with the default classloader. The default cache manager is named DEFAULT_CACHE_MANAGER_NAME

Returns:

the default cache manager

Throws:

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

getCacheManager

public static CacheManager getCacheManager(ClassLoader classLoader)

Get the default cache manager. The default cache manager is named DEFAULT_CACHE_MANAGER_NAME

Parameters:

classLoader - the ClassLoader that should be used in converting values into Java Objects. May be null.

Returns:

the default cache manager

Throws:

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

getCacheManager

public static CacheManager getCacheManager(String name)

Get a named cache manager using the default cache loader as specified by the implementation.

Parameters:

name - the name of the cache manager

Returns:

the named cache manager

Throws:

NullPointerException - if name is null

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

getCacheManager

public static CacheManager getCacheManager(ClassLoader classLoader,
                                           String name)

Get a named cache manager.

The first time a name is used, a new CacheManager is created. Subsequent calls will return the same cache manager.

During creation, the name of the CacheManager is passed through to CachingProvider so that an implementation it to concrete implementations may use it to point to a specific configuration used to configure the CacheManager. This allows CacheManagers to have different configurations. For example, one CacheManager might be configured for standalone operation and another might be configured to participate in a cluster.

Generally, It makes sense that a CacheManager is associated with a ClassLoader. I.e. all caches emanating from the CacheManager, all code including key and value classes must be present in that ClassLoader.

Secondly, the Caching may be in a different ClassLoader than the CacheManager (i.e. the Caching may be shared in an application server setting).

For this purpose a ClassLoader may be specified. If specified it will be used for all conversion between values and Java Objects. While Java's in-built serialization may be used other schemes may also be used. Either way the specified ClassLoader will be used.

The name parameter may be used to associate a configuration with this CacheManager instance.

Parameters:

classLoader - the ClassLoader that should be used in converting values into Java Objects.

name - the name of this cache manager

Returns:

the new cache manager

Throws:

NullPointerException - if classLoader or name is null

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

close

public static void close()
                  throws CachingShutdownException

Reclaims all resources obtained from this factory.

All cache managers obtained from the factory are shutdown.

Subsequent requests from this factory will return different cache managers than would have been obtained before shutdown. So for example

  CacheManager cacheManager = CacheFactory.getCacheManager();
  assertSame(cacheManager, CacheFactory.getCacheManager());
  CacheFactory.close();
  assertNotSame(cacheManager, CacheFactory.getCacheManager());
 

Throws:

CachingShutdownException - if any of the individual shutdowns failed

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

close

public static boolean close(ClassLoader classLoader)
                     throws CachingShutdownException

Reclaims all resources for a ClassLoader from this factory.

All cache managers linked to the specified CacheLoader obtained from the factory are shutdown.

Parameters:

classLoader - the class loader for which managers will be shut down

Returns:

true if found, false otherwise

Throws:

CachingShutdownException - if any of the individual shutdowns failed

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

close

public static boolean close(ClassLoader classLoader,
                            String name)
                     throws CachingShutdownException

Reclaims all resources for a ClassLoader from this factory.

the named cache manager obtained from the factory is closed.

Parameters:

classLoader - the class loader for which managers will be shut down

name - the name of the cache manager

Returns:

true if found, false otherwise

Throws:

CachingShutdownException - if any of the individual shutdowns failed

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

isSupported

public static boolean isSupported(OptionalFeature optionalFeature)

Indicates whether a optional feature is supported by this implementation

Parameters:

optionalFeature - the feature to check for

Returns:

true if the feature is supported

Throws:

IllegalStateException - if no CachingProvider is found or if more than one CachingProvider is found

isAnnotationsSupported

public static boolean isAnnotationsSupported()

Indicates whether annotations are supported

Returns:

true if annotations are supported