[[cache_manager]]
== The Embedded CacheManager
The CacheManager is {brandname}'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 {brandname} 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 link:#hotrod_java_client[Hot Rod 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:

[source,java]
----

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 link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#start--[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:

[source,java]
----

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.

include::configuration.adoc[]

=== Obtaining caches
After you configure the `CacheManager`, you can obtain and control caches.

Invoke the link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#getCache--[`getCache()`] method to obtain caches, as follows:

[source,java,options="nowrap"]
----
Cache<String, String> myCache = manager.getCache("myCache");
----

The preceding operation creates a cache named `myCache`, if it does not already exist, and returns it.

Using the `getCache()` method creates the cache only on the node where you invoke the method. In other words, it performs a local operation that must be invoked on each node across the cluster. Typically, applications deployed across multiple nodes obtain caches during initialization to ensure that caches are _symmetric_ and exist on each node.

Invoke the link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManagerAdmin.html#createCache--[`createCache()`] method to create caches dynamically across the entire cluster, as follows:

[source,java]
----
Cache<String, String> myCache = manager.administration().createCache("myCache", "myTemplate");
----

The preceding operation also automatically creates caches on any nodes that subsequently join the cluster.

Caches that you create with the `createCache()` method are ephemeral by default. If the entire cluster shuts down, the cache is not automatically created again when it restarts.

Use the +PERMANENT+ flag to ensure that caches can survive restarts, as follows:

[source,java,options="nowrap"]
----
Cache<String, String> myCache = manager.administration().withFlags(AdminFlag.PERMANENT).createCache("myCache", "myTemplate");
----

For the +PERMANENT+ flag to take effect, you must enable global state and set a configuration storage provider.

For more information about configuration storage providers, see link:{javadocroot}/org/infinispan/configuration/global/GlobalStateConfigurationBuilder.html#configurationStorage-org.infinispan.globalstate.ConfigurationStorage-[GlobalStateConfigurationBuilder#configurationStorage()].

=== 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.

.link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#getMembers--[getMembers()]
The +getMembers()+ method returns all of the nodes in the current cluster.

.link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#getCoordinator--[getCoordinator()]
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 link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#isCoordinator--[isCoordinator()]
method directly to see if the local node is the coordinator as well.

==== Other methods

.link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#getTransport--[getTransport()]
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.

.link:{javadocroot}/org/infinispan/manager/EmbeddedCacheManager.html#getStats--[getStats()]
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.
