javax.cache.spi

Interface CachingProvider

All Superinterfaces:

AutoCloseable, Closeable

public interface CachingProvider
extends Closeable

Provides mechanisms to create, request and later manage the life-cycle of configured CacheManagers, identified by URIs and scoped by ClassLoaders.

The meaning and semantics of the URI used to identify a CacheManager is implementation dependent. For applications to remain implementation independent, they should avoid attempting to create URIs and instead use those returned by getDefaultURI().

Since:

1.0

Author:

Brian Oliver, Greg Luck

Method Summary

Modifier and Type	Method and Description
void	close() Closes all of the CacheManager instances and associated resources created and maintained by the CachingProvider across all ClassLoaders.
void	close(ClassLoader classLoader) Closes all CacheManager instances and associated resources created by the CachingProvider using the specified ClassLoader.
void	close(URI uri, ClassLoader classLoader) Closes all CacheManager instances and associated resources created by the CachingProvider for the specified URI and ClassLoader.
CacheManager	getCacheManager() Requests a CacheManager configured according to the getDefaultURI() and getDefaultProperties() be made available that using the getDefaultClassLoader() for loading underlying classes.
CacheManager	getCacheManager(URI uri, ClassLoader classLoader) Requests a CacheManager configured according to the implementation specific URI that uses the provided ClassLoader for loading underlying classes.
CacheManager	getCacheManager(URI uri, ClassLoader classLoader, Properties properties) Requests a CacheManager configured according to the implementation specific URI be made available that uses the provided ClassLoader for loading underlying classes.
ClassLoader	getDefaultClassLoader() Obtains the default ClassLoader that will be used by the CachingProvider.
Properties	getDefaultProperties() Obtains the default Properties for the CachingProvider.
URI	getDefaultURI() Obtains the default URI for the CachingProvider.
boolean	isSupported(OptionalFeature optionalFeature) Determines whether an optional feature is supported by the CachingProvider.

Method Detail

getCacheManager

CacheManager getCacheManager(URI uri,
                             ClassLoader classLoader,
                             Properties properties)

Requests a CacheManager configured according to the implementation specific URI be made available that uses the provided ClassLoader for loading underlying classes.

Multiple calls to this method with the same URI and ClassLoader must return the same CacheManager instance, except if a previously returned CacheManager has been closed.

Properties are used in construction of a CacheManager and do not form part of the identity of the CacheManager. i.e. if a second call is made to with the same URI and ClassLoader but different properties, the CacheManager created in the first call is returned.

Properties names follow the same scheme as package names. The prefixes java and javax are reserved. Properties are passed through and can be retrieved via CacheManager.getProperties(). Properties within the package scope of a caching implementation may be used for additional configuration.

Parameters:

uri - an implementation specific URI for the CacheManager (null means use getDefaultURI())

classLoader - the ClassLoader to use for the CacheManager (null means use getDefaultClassLoader())

properties - the Properties for the CachingProvider to create the CacheManager (null means no implementation specific Properties are required)

Throws:

CacheException - when a CacheManager for the specified arguments could not be produced

SecurityException - when the operation could not be performed due to the current security settings

getDefaultClassLoader

ClassLoader getDefaultClassLoader()

Obtains the default ClassLoader that will be used by the CachingProvider.

Returns:

the default ClassLoader used by the CachingProvider

getDefaultURI

URI getDefaultURI()

Obtains the default URI for the CachingProvider.

Use this method to obtain a suitable URI for the CachingProvider.

Returns:

the default URI for the CachingProvider

getDefaultProperties

Properties getDefaultProperties()

Obtains the default Properties for the CachingProvider.

Use this method to obtain suitable Properties for the CachingProvider.

Returns:

the default Properties for the CachingProvider

getCacheManager

CacheManager getCacheManager(URI uri,
                             ClassLoader classLoader)

Requests a CacheManager configured according to the implementation specific URI that uses the provided ClassLoader for loading underlying classes.

Multiple calls to this method with the same URI and ClassLoader must return the same CacheManager instance, except if a previously returned CacheManager has been closed.

Parameters:

uri - an implementation specific URI for the CacheManager (null means use getDefaultURI())

classLoader - the ClassLoader to use for the CacheManager (null means use getDefaultClassLoader())

Throws:

CacheException - when a CacheManager for the specified arguments could not be produced

SecurityException - when the operation could not be performed due to the current security settings

getCacheManager

CacheManager getCacheManager()

Requests a CacheManager configured according to the getDefaultURI() and getDefaultProperties() be made available that using the getDefaultClassLoader() for loading underlying classes.

Multiple calls to this method must return the same CacheManager instance, except if a previously returned CacheManager has been closed.

Throws:

SecurityException - when the operation could not be performed due to the current security settings

close

void close()

Closes all of the CacheManager instances and associated resources created and maintained by the CachingProvider across all ClassLoaders.

After closing the CachingProvider will still be operational. It may still be used for acquiring CacheManager instances, though those will now be new.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

SecurityException - when the operation could not be performed due to the current security settings

close

void close(ClassLoader classLoader)

Closes all CacheManager instances and associated resources created by the CachingProvider using the specified ClassLoader.

After closing the CachingProvider will still be operational. It may still be used for acquiring CacheManager instances, though those will now be new for the specified ClassLoader .

Parameters:

classLoader - the ClassLoader to release

Throws:

SecurityException - when the operation could not be performed due to the current security settings

close

void close(URI uri,
           ClassLoader classLoader)

Closes all CacheManager instances and associated resources created by the CachingProvider for the specified URI and ClassLoader.

Parameters:

uri - the URI to release

classLoader - the ClassLoader to release

Throws:

SecurityException - when the operation could not be performed due to the current security settings

isSupported

boolean isSupported(OptionalFeature optionalFeature)

Determines whether an optional feature is supported by the CachingProvider.

Parameters:

optionalFeature - the feature to check for

Returns:

true if the feature is supported