Package org.infinispan.manager

Class DefaultCacheManager

java.lang.Object
org.infinispan.manager.impl.InternalCacheManager
org.infinispan.manager.DefaultCacheManager
All Implemented Interfaces:
Closeable, AutoCloseable, BasicCacheContainer, Lifecycle, CacheContainer, EmbeddedCacheManager, Listenable
@MBean(objectName="CacheManager", description="Component that acts as a manager, factory and container for caches in the system.") public class DefaultCacheManager extends InternalCacheManager
A CacheManager is the primary mechanism for retrieving a Cache instance, and is often used as a starting point to using the Cache.

CacheManagers are heavyweight objects, and we foresee no more than one CacheManager being used per JVM (unless specific configuration requirements require more than one; but either way, this would be a minimal and finite number of instances).

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

Lifecycle - CacheManagers have a lifecycle (it implements Lifecycle) and the default constructors also call 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 create Cache instances.

Once constructed, CacheManagers should be made available to any component that requires a Cache, via JNDI or via some other mechanism such as an IoC container.

You obtain Cache instances from the CacheManager by using one of the overloaded getCache(), methods. Note that with getCache(), there is no guarantee that the instance you get is brand-new and empty, since caches are named and shared. Because of this, the CacheManager also acts as a repository of Caches, and is an effective mechanism of looking up or creating Caches on demand.

When the system shuts down, it should call stop() on the CacheManager. This will ensure all caches within its scope are properly stopped as well.

Sample usage: 


    CacheManager manager = CacheManager.getInstance("my-config-file.xml");
    Cache<String, Person> entityCache = manager.getCache("myEntityCache");
    entityCache.put("aPerson", new Person());

    ConfigurationBuilder confBuilder = new ConfigurationBuilder();
    confBuilder.clustering().cacheMode(CacheMode.REPL_SYNC);
    manager.createCache("myReplicatedCache", confBuilder.build());
    Cache<String, String> replicatedCache = manager.getCache("myReplicatedCache");
Since:
4.0
Author:
Manik Surtani, Galder Zamarreño

  • Field Details

  • Constructor Details

    • DefaultCacheManager

      public DefaultCacheManager()
      Constructs and starts a default instance of the CacheManager, using configuration defaults. See Configuration and GlobalConfiguration for details of these defaults.

    • DefaultCacheManager

      public DefaultCacheManager(boolean start)
      Constructs a default instance of the CacheManager, using configuration defaults. See Configuration and GlobalConfiguration for details of these defaults.
      Parameters:
      start - if true, the cache manager is started

    • DefaultCacheManager

      @Deprecated(forRemoval=true, since="11.0") public DefaultCacheManager(Configuration defaultConfiguration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 11.0, please use DefaultCacheManager(ConfigurationBuilderHolder, boolean) instead.
      Constructs and starts a new instance of the CacheManager, using the default configuration passed in. See Configuration and GlobalConfiguration for details of these defaults.
      Parameters:
      defaultConfiguration - configuration to use as a template for all caches created

    • DefaultCacheManager

      @Deprecated(forRemoval=true, since="11.0") public DefaultCacheManager(Configuration defaultConfiguration, boolean start)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 11.0, please use DefaultCacheManager(ConfigurationBuilderHolder, boolean) instead.
      Constructs a new instance of the CacheManager, using the default configuration passed in. See GlobalConfiguration for details of these defaults.
      Parameters:
      defaultConfiguration - configuration file to use as a template for all caches created
      start - if true, the cache manager is started

    • DefaultCacheManager

      public DefaultCacheManager(GlobalConfiguration globalConfiguration)
      Constructs and starts a new instance of the CacheManager, using the global configuration passed in, and system defaults for the default named cache configuration. See Configuration for details of these defaults.
      Parameters:
      globalConfiguration - GlobalConfiguration to use for all caches created

    • DefaultCacheManager

      public DefaultCacheManager(GlobalConfiguration globalConfiguration, boolean start)
      Constructs a new instance of the CacheManager, using the global configuration passed in, and system defaults for the default named cache configuration. See Configuration for details of these defaults.
      Parameters:
      globalConfiguration - GlobalConfiguration to use for all caches created
      start - if true, the cache manager is started.

    • DefaultCacheManager

      @Deprecated(forRemoval=true, since="11.0") public DefaultCacheManager(GlobalConfiguration globalConfiguration, Configuration defaultConfiguration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 11.0, please use DefaultCacheManager(ConfigurationBuilderHolder, boolean) instead.
      Constructs and starts a new instance of the CacheManager, using the global and default configurations passed in. If either of these are null, system defaults are used.
      Parameters:
      globalConfiguration - global configuration to use. If null, a default instance is created.
      defaultConfiguration - default configuration to use. If null, a default instance is created.

    • DefaultCacheManager

      @Deprecated(forRemoval=true, since="11.0") public DefaultCacheManager(GlobalConfiguration globalConfiguration, Configuration defaultConfiguration, boolean start)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Since 11.0, please use DefaultCacheManager(ConfigurationBuilderHolder, boolean) instead.
      Constructs a new instance of the CacheManager, using the global and default configurations passed in. If either of these are null, system defaults are used.
      Parameters:
      globalConfiguration - global configuration to use. If null, a default instance is created.
      defaultConfiguration - default configuration to use. If null, a default instance is created.
      start - if true, the cache manager is started

    • DefaultCacheManager

      public DefaultCacheManager(String configurationFile) throws IOException
      Constructs and starts a new instance of the CacheManager, using the configuration file name passed in. This constructor first searches for the named file on the classpath, and failing that, treats the file name as an absolute path.
      Parameters:
      configurationFile - name of configuration file to use as a template for all caches created
      Throws:
      IOException - if there is a problem with the configuration file.

    • DefaultCacheManager

      public DefaultCacheManager(String configurationFile, boolean start) throws IOException
      Constructs a new instance of the CacheManager, using the configuration file name passed in. This constructor first searches for the named file on the classpath, and failing that, treats the file name as an absolute path.
      Parameters:
      configurationFile - name of configuration file to use as a template for all caches created
      start - if true, the cache manager is started
      Throws:
      IOException - if there is a problem with the configuration file.

    • DefaultCacheManager

      public DefaultCacheManager(InputStream configurationStream) throws IOException
      Constructs and starts a new instance of the CacheManager, using the input stream passed in to read configuration file contents.
      Parameters:
      configurationStream - stream containing configuration file contents, to use as a template for all caches created
      Throws:
      IOException - if there is a problem with the configuration stream.

    • DefaultCacheManager

      public DefaultCacheManager(InputStream configurationStream, boolean start) throws IOException
      Constructs a new instance of the CacheManager, using the input stream passed in to read configuration file contents.
      Parameters:
      configurationStream - stream containing configuration file contents, to use as a template for all caches created
      start - if true, the cache manager is started
      Throws:
      IOException - if there is a problem reading the configuration stream

    • DefaultCacheManager

      public DefaultCacheManager(URL configurationURL, boolean start) throws IOException
      Constructs a new instance of the CacheManager, using the input stream passed in to read configuration file contents.
      Parameters:
      configurationURL - stream containing configuration file contents, to use as a template for all caches created
      start - if true, the cache manager is started
      Throws:
      IOException - if there is a problem reading the configuration stream

    • DefaultCacheManager

      public DefaultCacheManager(ConfigurationBuilderHolder holder, boolean start)
      Constructs a new instance of the CacheManager, using the holder passed in to read configuration settings.
      Parameters:
      holder - holder containing configuration settings, to use as a template for all caches created
      start - if true, the cache manager is started

  • Method Details

    • defineConfiguration

      public Configuration defineConfiguration(String name, Configuration configuration)
      Description copied from interface: EmbeddedCacheManager
      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:
      name - name of the cache configuration
      configuration - the cache configuration
      Returns:
      the cache configuration

    • defineConfiguration

      public Configuration defineConfiguration(String name, String template, Configuration configurationOverride)
      Description copied from interface: EmbeddedCacheManager
      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 EmbeddedCacheManager.defineConfiguration(String, Configuration).

      Parameters:
      name - name of cache whose configuration is being defined
      template - configuration to use as a template
      configurationOverride - configuration overrides on top of the template
      Returns:
      the configuration

    • undefineConfiguration

      public void undefineConfiguration(String configurationName)
      Description copied from interface: EmbeddedCacheManager
      Removes a configuration from the set of defined configurations.

      If the named configuration does not exist, nothing happens.

      Parameters:
      configurationName - the named configuration

    • createCache

      public <K, V> Cache<K,V> createCache(String name, Configuration configuration)
      Description copied from interface: EmbeddedCacheManager
      Creates a cache on the local node using the supplied configuration.

      The cache may be clustered, but this method (or the equivalent combination of EmbeddedCacheManager.defineConfiguration(String, Configuration) and EmbeddedCacheManager.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

      public <K, V> Cache<K,V> getCache()
      Retrieves the default cache associated with this cache manager. Note that the default cache does not need to be explicitly created with createCache(String) (String)} since it is automatically created lazily when first used.

      As such, this method is always guaranteed to return the default cache.

      Returns:
      the default cache.

    • getCache

      public <K, V> Cache<K,V> getCache(String cacheName)
      Retrieves a named cache from the system. 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 will use the configuration passed in to the CacheManager on construction, as a template, and then optionally apply any overrides previously defined for the named cache using the defineConfiguration(String, Configuration) or defineConfiguration(String, String, Configuration) methods, or declared in the configuration file.

      Parameters:
      cacheName - name of cache to retrieve
      Returns:
      a cache instance identified by cacheName

    • cacheExists

      public boolean cacheExists(String cacheName)
      Description copied from interface: EmbeddedCacheManager
      A cache is considered to exist if it has been created and started via one of the EmbeddedCacheManager.getCache() methods and has not yet been removed via CacheContainerAdmin.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

      public <K, V> Cache<K,V> getCache(String cacheName, boolean createIfAbsent)
      Description copied from interface: EmbeddedCacheManager
      Similar to EmbeddedCacheManager.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 EmbeddedCacheManager.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

      public EmbeddedCacheManager startCaches(String... cacheNames)
      Description copied from interface: EmbeddedCacheManager
      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

    • getMembers

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

    • getAddress

      public 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

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

    • getCoordinatorAddress

      @ManagedAttribute(description="The logical address of the cluster\'s coordinator", displayName="Coordinator address") public String getCoordinatorAddress()

    • isCoordinator

      @ManagedAttribute(description="Indicates whether this node is coordinator", displayName="Is coordinator?") public boolean isCoordinator()
      Returns:
      whether the local node is the cluster's coordinator, or null if not connected

    • start

      public void start()
      Description copied from interface: Lifecycle
      Invoked on component start

    • shutdownAllCaches

      public void shutdownAllCaches()

    • stop

      public void stop()
      Description copied from interface: Lifecycle
      Invoked on component stop

    • addListenerAsync

      public CompletionStage<Void> addListenerAsync(Object listener)
      Description copied from interface: Listenable
      Asynchronous version of Listenable.addListener(Object)
      Parameters:
      listener - listener to add, must not be null
      Returns:
      CompletionStage that when complete the listener is fully installed

    • removeListenerAsync

      public CompletionStage<Void> removeListenerAsync(Object listener)
      Description copied from interface: Listenable
      Asynchronous version of Listenable.removeListener(Object)
      Parameters:
      listener - listener to remove, must not be null
      Returns:
      CompletionStage that when complete the listener is fully removed

    • getStatus

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

    • getCacheManagerConfiguration

      public GlobalConfiguration getCacheManagerConfiguration()
      Description copied from interface: EmbeddedCacheManager
      Returns global configuration for this CacheManager
      Returns:
      the global configuration object associated to this CacheManager

    • getDefaultCacheConfiguration

      public Configuration getDefaultCacheConfiguration()
      Returns:
      the default cache's configuration, or null if there is no default cache.

    • getCacheConfiguration

      public Configuration getCacheConfiguration(String name)
      Description copied from interface: EmbeddedCacheManager
      Returns the configuration for the given cache.
      Returns:
      the configuration for the given cache or null if no such cache is defined

    • getCacheNames

      public Set<String> getCacheNames()
      Description copied from interface: BasicCacheContainer
      This method returns a collection of all cache names.

      The configurations may have been defined via XML, in the programmatic configuration, or at runtime.

      Internal-only caches are not included.

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

    • getAccessibleCacheNames

      public Set<String> getAccessibleCacheNames()
      Description copied from interface: EmbeddedCacheManager
      Similar to BasicCacheContainer.getCacheNames() but filters out caches that are not accessible by the current user

    • getCacheConfigurationNames

      public Set<String> getCacheConfigurationNames()
      Description copied from interface: EmbeddedCacheManager
      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 EmbeddedCacheManager.defineConfiguration(String, Configuration).

      Internal caches defined via InternalCacheRegistry are not included.

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

    • isRunning

      public boolean isRunning(String cacheName)
      Description copied from interface: EmbeddedCacheManager
      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

      public boolean isDefaultRunning()
      Description copied from interface: EmbeddedCacheManager
      Tests whether the default cache is running.
      Returns:
      true if the default cache is running; false otherwise.

    • getCacheManagerStatus

      @ManagedAttribute(description="The status of the cache manager instance.", displayName="Cache manager status", dataType=TRAIT) public String getCacheManagerStatus()

    • getDefinedCacheNames

      @ManagedAttribute(description="The defined cache names and their statuses. The default cache is not included in this representation.", displayName="List of defined caches", dataType=TRAIT) public String getDefinedCacheNames()

    • getDefinedCacheConfigurationNames

      @ManagedAttribute(description="The defined cache configuration names.", displayName="List of defined cache configurations", dataType=TRAIT) public String getDefinedCacheConfigurationNames()

    • getDefinedCacheCount

      @ManagedAttribute(description="The total number of defined cache configurations.", displayName="Number of caches defined") public String getDefinedCacheCount()

    • getNumberOfCacheConfigurations

      @ManagedAttribute(description="The total number of defined cache configurations.", displayName="Number of caches defined") public int getNumberOfCacheConfigurations()

    • getCreatedCacheCount

      @ManagedAttribute(description="The total number of created caches, including the default cache.", displayName="Number of caches created") public String getCreatedCacheCount()

    • getNumberOfCreatedCaches

      @ManagedAttribute(description="The total number of created caches, including the default cache.", displayName="Number of caches created") public long getNumberOfCreatedCaches()

    • getRunningCacheCount

      @ManagedAttribute(description="The total number of running caches, including the default cache.", displayName="Number of running caches") public String getRunningCacheCount()

    • getNumberOfRunningCaches

      @ManagedAttribute(description="The total number of running caches, including the default cache.", displayName="Number of running caches") public long getNumberOfRunningCaches()

    • getVersion

      @ManagedAttribute(description="Returns the version of Infinispan", displayName="Infinispan version", dataType=TRAIT) public String getVersion()

    • getName

      @ManagedAttribute(description="The name of this cache manager", displayName="Cache manager name", dataType=TRAIT) public String getName()

    • startCache

      @ManagedOperation(description="Starts the default cache associated with this cache manager", displayName="Starts the default cache") public void startCache()

    • startCache

      @ManagedOperation(description="Starts a named cache from this cache manager", name="startCache", displayName="Starts a cache with the given name") public void startCache(@Parameter(name="cacheName",description="Name of cache to start") String cacheName)

    • getNodeAddress

      @ManagedAttribute(description="The network address associated with this instance", displayName="Network address", dataType=TRAIT) public String getNodeAddress()

    • getPhysicalAddresses

      @ManagedAttribute(description="The physical network addresses associated with this instance", displayName="Physical network addresses", dataType=TRAIT) public String getPhysicalAddresses()

    • getClusterMembers

      @ManagedAttribute(description="List of members in the cluster", displayName="Cluster members", dataType=TRAIT) public String getClusterMembers()

    • getClusterMembersPhysicalAddresses

      @ManagedAttribute(description="List of members in the cluster", displayName="Cluster members", dataType=TRAIT) public String getClusterMembersPhysicalAddresses()

    • getClusterSize

      @ManagedAttribute(description="Size of the cluster in number of nodes", displayName="Cluster size") public int getClusterSize()

    • getClusterName

      @ManagedAttribute(description="Cluster name", displayName="Cluster name", dataType=TRAIT) public String getClusterName()
      Returns:
      the name of the cluster. Null if running in local mode.

    • getSite

      @ManagedAttribute(description="Returns the local site name", displayName="Local site name", dataType=TRAIT) public String getSite()

    • getSiteView

      @ManagedAttribute(description="Lists all online sites", displayName="Online Sites", dataType=TRAIT) public String getSiteView()

    • isRelayNode

      @ManagedAttribute(description="Indicates whether this node is a relay node", displayName="Is relay node?", dataType=TRAIT) public boolean isRelayNode()

    • getRelayNodesAddress

      @ManagedAttribute(description="Lists relay nodes in the local site", displayName="Relay nodes", dataType=TRAIT) public String getRelayNodesAddress()

    • addCacheDependency

      public void addCacheDependency(String from, String to)
      Description copied from interface: EmbeddedCacheManager
      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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getGlobalConfigurationAsProperties

      @ManagedAttribute(description="Global configuration properties", displayName="Global configuration properties", dataType=TRAIT) public Properties getGlobalConfigurationAsProperties()

    • getStats

      public CacheContainerStats getStats()
      Description copied from interface: EmbeddedCacheManager
      Returns statistics for this cache manager
      Returns:
      statistics for this cache manager

    • getHealth

      public Health getHealth()
      Description copied from interface: EmbeddedCacheManager
      Returns an entry point for a Health Check API.
      Returns:
      Health API for this EmbeddedCacheManager.

    • getCacheManagerInfo

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

    • executor

      public ClusterExecutor executor()
      Description copied from interface: EmbeddedCacheManager
      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:

    • close

      public void close() throws IOException
      Throws:
      IOException

    • getClassWhiteList

      public ClassAllowList getClassWhiteList()

    • getClassAllowList

      public ClassAllowList getClassAllowList()

    • administration

      public EmbeddedCacheManagerAdmin administration()
      Description copied from interface: EmbeddedCacheManager
      Provides an EmbeddedCacheManagerAdmin whose methods affect the entire cluster as opposed to a single node.
      Returns:
      a cluster-aware EmbeddedCacheManagerAdmin

    • getSubject

      public Subject getSubject()

    • withSubject

      public EmbeddedCacheManager withSubject(Subject subject)

    • globalComponentRegistry

      protected GlobalComponentRegistry globalComponentRegistry()
      Specified by:
      globalComponentRegistry in class InternalCacheManager