Package org.infinispan.manager

Interface EmbeddedCacheManager

  • All Superinterfaces:
    java.lang.AutoCloseable, BasicCacheContainer, CacheContainer, java.io.Closeable, Lifecycle, Listenable
    All Known Implementing Classes:
    DefaultCacheManager
    public interface EmbeddedCacheManager
extends CacheContainer, Listenable, java.io.Closeable
    EmbeddedCacheManager is an CacheManager that runs in the same JVM as the client.

    Constructing a EmbeddedCacheManager is done via one of its constructors, which optionally take in a Configuration or a path or URL to a configuration XML file: see DefaultCacheManager.

    Lifecycle - EmbeddedCacheManagers have a lifecycle (it implements Lifecycle) and the default constructors also call Lifecycle.start(). Overloaded versions of the constructors are available, that do not start the CacheManager, although it must be kept in mind that CacheManagers need to be started before they can be used to readWriteMap Cache instances.

    Once constructed, EmbeddedCacheManagers should be made available to any component that requires a Cache, via JNDI or via some other mechanism such as an dependency injection framework.

    Since:
    4.1
    Author:
    Manik Surtani (manik@jboss.org), Galder Zamarreno, Mircea.Markus@jboss.com
    See Also:
    DefaultCacheManager

    • Method Detail

      • defineConfiguration

        Configuration defineConfiguration​(java.lang.String cacheName,
                                  Configuration configuration)
        Defines a named cache's configuration by using the provided configuration

        Unlike previous versions of Infinispan, this method does not build on an existing configuration (default or named). If you want this behavior, then use ConfigurationBuilder.read(org.infinispan.configuration.cache.Configuration).

        The other way to define named cache's configuration is declaratively, in the XML file passed in to the cache manager.

        If this cache was already configured either declaritively or programmatically this method will throw a CacheConfigurationException.

        Parameters:
        cacheName - name of cache whose configuration is being defined
        configuration - configuration overrides to use
        Returns:
        a cloned configuration instance

      • defineConfiguration

        Configuration defineConfiguration​(java.lang.String cacheName,
                                  java.lang.String templateCacheName,
                                  Configuration configurationOverride)
        Defines a named cache's configuration using by first reading the template configuration and then applying the override afterwards to generate a configuration.

        The other way to define named cache's configuration is declaratively, in the XML file passed in to the cache manager.

        If templateName is null or there isn't any named cache with that name, this methods works exactly like defineConfiguration(String, Configuration).

        If this cache was already configured either declaratively or programmatically this method will throw a CacheConfigurationException.

        Parameters:
        cacheName - name of cache whose configuration is being defined
        templateCacheName - name of cache to use as a template before overrides are applied to it
        configurationOverride - configuration overrides to use
        Returns:
        a cloned configuration instance

      • undefineConfiguration

        void undefineConfiguration​(java.lang.String configurationName)
        Removes a configuration from the set of defined configurations. If the configuration is currently in use by one of the caches, an IllegalStateException is thrown. If the named configuration does not exist, nothing happens
        Parameters:
        configurationName - the named configuration

      • getClusterName

        java.lang.String getClusterName()
        Returns:
        the name of the cluster. Null if running in local mode.

      • getMembers

        java.util.List<Address> getMembers()
        Returns:
        the addresses of all the members in the cluster, or null if not connected

      • getAddress

        Address getAddress()
        Warning: the address may be null before the first clustered cache starts and after all the clustered caches have been stopped.
        Returns:
        the address of the local node, or null if not connected

      • getCoordinator

        Address getCoordinator()
        Returns:
        the address of the cluster's coordinator, or null if not connected

      • isCoordinator

        boolean isCoordinator()
        Returns:
        whether the local node is the cluster's coordinator, or null if not connected

      • getStatus

        ComponentStatus getStatus()
        Returns:
        the status of the cache manager

      • getCacheManagerConfiguration

        GlobalConfiguration getCacheManagerConfiguration()
        Returns global configuration for this CacheManager
        Returns:
        the global configuration object associated to this CacheManager

      • getCacheConfiguration

        Configuration getCacheConfiguration​(java.lang.String name)
        Returns the configuration for the given cache.
        Returns:
        the configuration for the given cache or null if no such cache is defined

      • getDefaultCacheConfiguration

        Configuration getDefaultCacheConfiguration()
        Returns default configuration for this CacheManager
        Returns:
        the default configuration associated with this CacheManager

      • getCacheConfigurationNames

        default java.util.Set<java.lang.String> getCacheConfigurationNames()
        This method returns a collection of cache configuration names which contains the cache configurations that have been defined via XML or programmatically, and the cache configurations that have been defined at runtime via this cache manager instance. If no cache configurations are registered or no caches have been created, this method returns an empty set. The default cache is never included in this set of cache names, as well a caches for internal-only use InternalCacheRegistry
        Returns:
        an immutable set of non-default named caches registered or created with this cache manager.
        Since:
        8.2

      • isRunning

        boolean isRunning​(java.lang.String cacheName)
        Tests whether a named cache is running.
        Parameters:
        cacheName - name of cache to test.
        Returns:
        true if the named cache exists and is running; false otherwise.

      • isDefaultRunning

        boolean isDefaultRunning()
        Tests whether the default cache is running.
        Returns:
        true if the default cache is running; false otherwise.

      • cacheExists

        boolean cacheExists​(java.lang.String cacheName)
        A cache is considered to exist if it has been created and started via one of the CacheContainer.getCache() methods and has not yet been removed via removeCache(String).

        In environments when caches are continuously created and removed, this method offers the possibility to find out whether a cache has either, not been started, or if it was started, whether it's been removed already or not.
        Parameters:
        cacheName -
        Returns:
        true if the cache with the given name has not yet been started, or if it was started, whether it's been removed or not.

      • createCache

        <K,​V> Cache<K,​V> createCache​(java.lang.String name,
                                         Configuration configuration)
        Creates a cache on the local node using the supplied configuration. The cache may be clustered, but this method (or an equivalent combination of defineConfiguration(String, Configuration) and getCache(String, boolean)) needs to be invoked on all nodes.
        Type Parameters:
        K - the generic type of the key
        V - the generic type of the value
        Parameters:
        name - the name of the cache
        configuration - the configuration to use.
        Returns:
        the cache

      • getCache

        <K,​V> Cache<K,​V> getCache​(java.lang.String cacheName,
                                      boolean createIfAbsent)
        Retrieves a named cache from the system in the same way that CacheContainer.getCache(String) does except that if offers the possibility for the named cache not to be retrieved if it has not yet been started, or if it's been removed after being started. If a non-template configuration exists with the same name, it will be used to configure the cache.
        Parameters:
        cacheName - name of cache to retrieve
        createIfAbsent - if false, the named cache will not be retrieved if it hasn't been retrieved previously or if it's been removed. If true, this methods works just like CacheContainer.getCache(String)
        Returns:
        null if no named cache exists as per rules set above, otherwise returns a cache instance identified by cacheName

      • getCache

        <K,​V> Cache<K,​V> getCache​(java.lang.String cacheName,
                                      java.lang.String configurationName)
        Deprecated.
        as of 9.0. Use defineConfiguration(String, String, Configuration) and CacheContainer.getCache(String) instead
        Retrieves a named cache from the system in the same way that CacheContainer.getCache(String) does except that if offers the possibility to specify a specific configuration template. Multiple caches can be created using the same configuration.
        Parameters:
        cacheName - name of cache to retrieve
        configurationName - name of the configuration template to use
        Returns:
        null if no configuration exists as per rules set above, otherwise returns a cache instance identified by cacheName

      • getCache

        <K,​V> Cache<K,​V> getCache​(java.lang.String cacheName,
                                      java.lang.String configurationTemplate,
                                      boolean createIfAbsent)
        Deprecated.
        as of 9.0. Use defineConfiguration(String, String, Configuration) and getCache(String, boolean) instead
        Retrieves a named cache from the system in the same way that CacheContainer.getCache(String) does except that if offers the possibility to specify a specific configuration template. Multiple caches can be created using the same configuration. Tihs method also offers the possibility for the named cache not to be retrieved if it has not yet been started, or if it's been removed after being started.
        Parameters:
        cacheName - name of cache to retrieve
        configurationTemplate - name of the configuration template to use
        createIfAbsent - if false, the named cache will not be retrieved if it hasn't been retrieved previously or if it's been removed. If true, this methods works just like getCache(String, String)
        Returns:
        null if no configuration exists as per rules set above, otherwise returns a cache instance identified by cacheName

      • startCaches

        EmbeddedCacheManager startCaches​(java.lang.String... cacheNames)
        Starts a set of caches in parallel. Infinispan supports both symmetric and asymmetric clusters; that is, multiple nodes having the same or different sets of caches running, respectively. Calling this method on application/application server startup with all your cache names will ensure that the cluster is symmetric.
        Parameters:
        cacheNames - the names of the caches to start
        Since:
        5.0

      • removeCache

        @Deprecated
void removeCache​(java.lang.String cacheName)
        Deprecated.
        Since 9.2, obtain a CacheContainerAdmin instance using administration() and invoke the CacheContainerAdmin.removeCache(String) method
        Removes a cache with the given name from the system. This is a cluster wide operation that results not only in stopping the cache with the given name in all nodes in the cluster, but also deletes its contents both in memory and in any backing cache store.
        Parameters:
        cacheName - name of cache to remove

      • getGlobalComponentRegistry

        @Deprecated
GlobalComponentRegistry getGlobalComponentRegistry()
        Deprecated.
        Since 10.0, with no public API replacement

      • addCacheDependency

        void addCacheDependency​(java.lang.String from,
                        java.lang.String to)
        Add a dependency between two caches. The cache manager will make sure that a cache is stopped before any of its dependencies
        Parameters:
        from - cache name
        to - cache name
        Since:
        7.0

      • getStats

        CacheContainerStats getStats()
        Returns statistics for this cache manager since 7.1
        Returns:
        statistics for this cache manager

      • executor

        default ClusterExecutor executor()
        Providess the cache manager based executor. This can be used to execute a given operation upon the cluster or a single node if desired. If this manager is not clustered this will execute locally only.

        Note that not all EmbeddedCacheManager implementations may implement this. Those that don't will throw a UnsupportedOperationException upon invocation.

        Returns:

      • getHealth

        Health getHealth()
        Returns an entry point for a Health Check API.
        Returns:
        Health API for this EmbeddedCacheManager.
        Since:
        9.0