Package javax.cache

Interface CacheManager

  • All Known Implementing Classes:
    CarbonCacheManager
    public interface CacheManager
    A CacheManager is used for looking up Caches and controls their lifecycle. It represents a collection of caches.

    To the extent that implementations have configuration at the CacheManager level, it is a way for these caches to share common configuration. For example a CacheManager might be clustered so all caches in that CacheManager will participate in the same cluster.

    Creation

    Concrete implementations can be created in a number of ways:
    • Through a ServiceLoader using Caching
    • Simple creation with new of a concrete implementation, if supported by an implementation

    Lookup

    If Caching was used for creation, it will keep track of all CacheManagers created.

    The default CacheManager can be obtained using Caching.getCacheManager(). This is a useful idiom if you only want to use one CacheManager.

    Named CacheManagers can be obtained using Caching.getCacheManager(name).

    Since:
    1.0
    Author:
    Greg Luck, Yannis Cosmadopoulos

    • Method Detail

      • getName

        String getName()
        Get the name of this cache manager
        Returns:
        the name of this cache manager

      • getStatus

        Status getStatus()
        Returns the status of this CacheManager.

        Calls to this method will block while the state is changing.

        Returns:
        one of Status

      • createCacheBuilder

        <K,​V> CacheBuilder<K,​V> createCacheBuilder​(String cacheName)
        Creates a new CacheBuilder for the named cache to be managed by this cache manager.

        An example which creates a cache using default cache configuration is: 

            Cache<Integer, Date> myCache2 = cacheManager.
           <Integer, Date>createCacheBuilder("myCache2").
           build();

        An example usage which programmatically sets many parameters of CacheConfiguration, specifies a CacheLoader and registrs listeners is: 

            Cache<Integer, String> myCache1 = cacheManager.
           <Integer, String>createCacheBuilder("myCache1").
           setCacheLoader(cl).
           setStoreByValue(true).
           setReadThrough(true).
           setWriteThrough(false).
           setStatisticsEnabled(true).
           setTransactionEnabled(false).
           registerCacheEntryListener(listener1, NotificationScope.LOCAL, false).
           registerCacheEntryListener(listener2, NotificationScope.LOCAL, false).
           build();

        The returned CacheBuilder is associated with this CacheManager. The Cache will be created, added to the caches controlled by this CacheManager and started when CacheBuilder.build() is called. If there is an existing Cache of the same name associated with this CacheManager when build is invoked, an exception is thrown.

        Parameters:
        cacheName - the name of the cache to build. A cache name must consist of at least one non-whitespace character.
        Returns:
        the CacheBuilder for the named cache
        Throws:
        IllegalStateException - if the CacheManager is not in Status.STARTED state.
        CacheException - if a cache with that name already exists or there was an error adding the cache to the CacheManager
        IllegalArgumentException - if an illegal cache name is specified
        NullPointerException - if the cache name is null

      • getCache

        <K,​V> Cache<K,​V> getCache​(String cacheName)
        Looks up a named cache.
        Parameters:
        cacheName - the name of the cache to look for
        Returns:
        the Cache or null if it does exist
        Throws:
        IllegalStateException - if the CacheManager is not Status.STARTED

      • getCaches

        Iterable<Cache<?,​?>> getCaches()
        Returns an Iterable over the caches managed by this CacheManager. The Iterable is immutable (iterator.remove will throw an IllegalStateException) and independent of the cache manager; if the caches managed by the cache manager change the Iterable is not affected
        Returns:
        an Iterable over the managed Caches
        Throws:
        UnsupportedOperationException - if an attempt it made to remove an element

      • removeCache

        boolean removeCache​(String cacheName)
        Remove a cache from the CacheManager. The cache will be stopped.
        Parameters:
        cacheName - the cache name
        Returns:
        true if the cache was removed
        Throws:
        IllegalStateException - if the cache is not Status.STARTED
        NullPointerException - if cacheName is null

      • isSupported

        boolean isSupported​(OptionalFeature optionalFeature)
        Indicates whether a optional feature is supported by this CacheManager.
        Parameters:
        optionalFeature - the feature to check for
        Returns:
        true if the feature is supported

      • shutdown

        void shutdown()
        Shuts down the CacheManager.

        For each cache in the cache manager the CacheLifecycle.stop() method will be invoked, in no guaranteed order. If the stop throws an exception, the exception is ignored.

        Calls to getStatus() will block until shutdown completes.

        On completion the CacheManager's status is changed to Status.STOPPED, and the manager's owned caches will be empty and getCaches() will return an empty collection.

        A given CacheManager instance cannot be restarted after it has been stopped. A new one must be created.

        Throws:
        IllegalStateException - if an operation is performed on CacheManager while stopping or stopped.

      • unwrap

        <T> T unwrap​(Class<T> cls)
        Return an object of the specified type to allow access to the provider-specific API. If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.
        Parameters:
        cls - the class of the object to be returned. This is normally either the underlying implementation class or an interface that it implements.
        Returns:
        an instance of the specified class
        Throws:
        IllegalArgumentException - if the provider doesn't support the specified class.