Package javax.cache

Class Caching

  • public final class Caching
extends java.lang.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
    See Also:
    ServiceLoader, CachingProvider

    • Constructor Detail

      • Caching

        private Caching()
        No public constructor as all methods are static.

    • Method Detail

      • getDefaultClassLoader

        public static java.lang.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​(java.lang.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​(java.lang.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
        java.lang.SecurityException - when the operation could not be performed due to the current security settings

      • getCachingProvider

        public static CachingProvider getCachingProvider​(java.lang.String fullyQualifiedClassName,
                                                 java.lang.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
        java.lang.SecurityException - when the operation could not be performed due to the current security settings

      • getCache

        public static <K,​V> Cache<K,​V> getCache​(java.lang.String cacheName,
                                                    java.lang.Class<K> keyType,
                                                    java.lang.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:
        java.lang.IllegalStateException - if the CacheManager is CacheManager.isClosed()
        java.lang.IllegalArgumentException - if the specified key and/or value types are incompatible with the configured cache.
        java.lang.SecurityException - when the operation could not be performed due to the current security settings
        See Also:
        CacheManager.getCache(String, Class, Class), CacheManager.getCache(String)