Package org.infinispan.manager

Interface EmbeddedCacheManager

All Superinterfaces:
AutoCloseable, BasicCacheContainer, CacheContainer, Closeable, Lifecycle, Listenable
All Known Implementing Classes:
AbstractDelegatingEmbeddedCacheManager, DefaultCacheManager
public interface EmbeddedCacheManager extends CacheContainer, Listenable, 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:

  • Method Details

    • defineConfiguration

      Configuration defineConfiguration(String cacheName, Configuration configuration)
      Register a cache configuration in the cache manager.

      The configuration will be automatically used when creating a cache with the same name, unless it is a template. If it is a template and it contains wildcards (`*` or `?`), it will be automatically used when creating caches that match the template.

      In order to extend an existing configuration, use ConfigurationBuilder.read(org.infinispan.configuration.cache.Configuration).

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

      Parameters:
      cacheName - name of the cache configuration
      configuration - the cache configuration
      Returns:
      the cache configuration
      Throws:
      CacheConfigurationException - if a configuration with the same name already exists.

    • defineConfiguration

      Configuration defineConfiguration(String cacheName, String templateCacheName, Configuration configurationOverride)
      Defines a cache configuration by first reading the template configuration and then applying the override.

      The configuration will be automatically used when creating a cache with the same name, unless it is a template. If it is a template and it contains wildcards (`*` or `?`), it will be automatically used when creating caches that match the template.

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

      If templateName is null, this method works exactly like defineConfiguration(String, Configuration).

      Parameters:
      cacheName - name of cache whose configuration is being defined
      templateCacheName - configuration to use as a template
      configurationOverride - configuration overrides on top of the template
      Returns:
      the configuration
      Throws:
      CacheConfigurationException - if a configuration with the same name already exists.

    • undefineConfiguration

      void undefineConfiguration(String configurationName)
      Removes a configuration from the set of defined configurations.

      If the named configuration does not exist, nothing happens.

      Parameters:
      configurationName - the named configuration
      Throws:
      IllegalStateException - if the configuration is in use

    • getClusterName

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

    • getMembers

      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(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:
      the default cache's configuration, or null if there is no default cache.

    • getCacheConfigurationNames

      default Set<String> getCacheConfigurationNames()
      This method returns a collection of all cache configuration names.

      The configurations may have been defined via XML, programmatically via ConfigurationBuilderHolder, or at runtime via defineConfiguration(String, Configuration).

      Internal caches defined via InternalCacheRegistry are not included.

      Returns:
      an immutable set of configuration names registered in this cache manager.
      Since:
      8.2

    • getAccessibleCacheNames

      Set<String> getAccessibleCacheNames()
      Similar to BasicCacheContainer.getCacheNames() but filters out caches that are not accessible by the current user

    • isRunning

      boolean isRunning(String cacheName)
      Tests whether a cache is running.
      Parameters:
      cacheName - name of cache to test.
      Returns:
      true if the 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(String cacheName)
      A cache is considered to exist if it has been created and started via one of the 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 - cache to check
      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.

    • getCache

      <K, V> Cache<K,V> getCache()
      Retrieves the default cache associated with this cache container.
      Specified by:
      getCache in interface BasicCacheContainer
      Specified by:
      getCache in interface CacheContainer
      Returns:
      the default cache.
      Throws:
      CacheConfigurationException - if a default cache does not exist.

    • getCache

      <K, V> Cache<K,V> getCache(String cacheName)
      Retrieves a cache by name.

      If the cache has been previously created with the same name, the running cache instance is returned. Otherwise, this method attempts to create the cache first.

      When creating a new cache, this method requires a defined configuration that either has exactly the same name, or is a template with wildcards and matches the cache name.

      Specified by:
      getCache in interface BasicCacheContainer
      Specified by:
      getCache in interface CacheContainer
      Parameters:
      cacheName - name of cache to retrieve
      Returns:
      a cache instance identified by cacheName

    • createCache

      <K, V> Cache<K,V> createCache(String name, Configuration configuration)
      Creates a cache on the local node using the supplied configuration.

      The cache may be clustered, but this method (or the 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(String cacheName, boolean createIfAbsent)
      Similar to getCache(String), except if has the option to not create the cache if it is not already running.
      Parameters:
      cacheName - name of cache to retrieve
      createIfAbsent - If true, this methods works just like getCache(String). If false, return the already running cache or null.
      Returns:
      null if the cache does not exist and createIfAbsent == false, otherwise a cache instance identified by cacheName

    • startCaches

      EmbeddedCacheManager startCaches(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(forRemoval=true) void removeCache(String cacheName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

    • getTransport

      @Deprecated(forRemoval=true) Transport getTransport()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 10.0, please use getAddress(), getMembers(), getCoordinator()

    • getGlobalComponentRegistry

      @Deprecated(forRemoval=true) GlobalComponentRegistry getGlobalComponentRegistry()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 10.0, with no public API replacement

    • addCacheDependency

      void addCacheDependency(String from, 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

      @Deprecated(forRemoval=true) CacheContainerStats getStats()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 10.1.3. This mixes statistics across unrelated caches so the reported numbers don't have too much relevance.
      Returns statistics for this cache manager
      Returns:
      statistics for this cache manager
      Since:
      7.1

    • 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

    • getCacheManagerInfo

      CacheManagerInfo getCacheManagerInfo()
      Returns:
      an instance of CacheManagerInfo used to get basic info about the cache manager.

    • administration

      default EmbeddedCacheManagerAdmin administration()
      Provides an EmbeddedCacheManagerAdmin whose methods affect the entire cluster as opposed to a single node.
      Specified by:
      administration in interface CacheContainer
      Returns:
      a cluster-aware EmbeddedCacheManagerAdmin
      Since:
      9.2

    • getClassWhiteList

      @Deprecated(forRemoval=true) ClassAllowList getClassWhiteList()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getClassAllowList

      ClassAllowList getClassAllowList()

    • getSubject

      Subject getSubject()

    • withSubject

      EmbeddedCacheManager withSubject(Subject subject)