Skip to content

Latest commit

 

History

History
130 lines (91 loc) · 5.94 KB

cache_manager.adoc

File metadata and controls

130 lines (91 loc) · 5.94 KB
Raw

The Embedded CacheManager

The CacheManager is Infinispan’s main entry point. You use a CacheManager to

  • configure and obtain caches

  • manage and monitor your nodes

  • execute code across a cluster

  • more…​

Depending on whether you are embedding Infinispan in your application or you are using it remotely, you will be dealing with either an EmbeddedCacheManager or a RemoteCacheManager. While they share some methods and properties, be aware that there are semantic differences between them. The following chapters focus mostly on the embedded implementation. For details on the remote implementation refer to [hotrod:java-client].

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

The simplest way to create a CacheManager is:

EmbeddedCacheManager manager = new DefaultCacheManager();

which starts the most basic, local mode, non-clustered cache manager with no caches. CacheManagers have a lifecycle and the default constructors also call start(). Overloaded versions of the constructors are available, that do not start the CacheManager, although keep 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 require to interact with it via some form of application-wide scope such as JNDI, a ServletContext or via some other mechanism such as an IoC container.

When you are done with a CacheManager, you must stop it so that it can release its resources:

manager.stop();

This will ensure all caches within its scope are properly stopped, thread pools are shutdown. If the CacheManager was clustered it will also leave the cluster gracefully.

Obtaining caches

Once you have configured the CacheManager, the main thing you will want to do is to use it to control and obtain caches. The main way to get to a cache is to just invoke getCache():

Cache<String, String> myCache = manager.getCache("myCache");

The above code will create the cache myCache (if it doesn’t already exist) and return it. One important thing to remember is that using this method, cache creation is only performed on the local node. This means that, in order for the cache to exist on all nodes, this operation must be invoked locally everywhere. In a typical application deployed across multiple nodes, where you obtain caches during initialization, this ensures that the caches are symmetric, i.e. they exist on every node.

If you need to create caches dynamically across the whole cluster, you should invoke the following operation:

Cache<String, String> myCache = manager.administration().createCache("myCache", "myTemplate");

Caches created using the above API will also be automatically created on any new nodes which subsequently join the cluster. The configuration of such caches, however, will be ephemeral: shutting down the entire cluster and restarting it will not automatically recreate them. To make these caches permanent, i.e. ensure that they are recreated after a cluster is shutdown and restarted, use the PERMANENT flag as follows:

Cache<String, String> myCache = manager.administration().withFlags(AdminFlag.PERMANENT).createCache("myCache", "myTemplate");

In order for the above to work, global state must be enabled and a suitable configuration storage selected. The available configuration stores are:

  • VOLATILE: as the name implies, this configuration storage does not support PERMANENT caches.

  • OVERLAY: this stores configurations in the global shared state persistent path in a file named caches.xml.

  • MANAGED: this is only supported in server deployments, and will store PERMANENT caches in the server model.

  • CUSTOM: a custom configuration store.

See .link:{javadocroot}/org/infinispan/configuration/global/GlobalStateConfigurationBuilder.html# for details.

Clustering Information

The EmbeddedCacheManager has quite a few methods to provide information as to how the cluster is operating. The following methods only really make sense when being used in a clustered environment (that is when a Transport is configured).

Member Information

When you are using a cluster it is very important to be able to find information about membership in the cluster including who is the owner of the cluster.

The getMembers() method returns all of the nodes in the current cluster.

The getCoordinator() method will tell you which one of the members is the coordinator of the cluster. For most intents you shouldn’t need to care who the coordinator is. You can use isCoordinator() method directly to see if the local node is the coordinator as well.

Other methods

This method provides you access to the underlying Transport that is used to send messages to other nodes. In most cases a user wouldn’t ever need to go to this level, but if you want to get Transport specific information (in this case JGroups) you can use this mechanism.

The stats provided here are coalesced from all of the active caches in this manager. These stats can be useful to see if there is something wrong going on with your cluster overall.