Menu Close

Chapter 11. Remotely Creating Data Grid Caches

Add caches to Data Grid Server so you can store data.

11.1. Cache Configuration with Data Grid Server

Caches configure the data container on Data Grid Server.

You create caches at run-time by adding definitions based on org.infinispan templates or Data Grid configuration through the console, the Command Line Interface (CLI), the Hot Rod endpoint, or the REST endpoint.


When you create caches at run-time, Data Grid Server replicates your cache definitions across the cluster.

Configuration that you declare directly in infinispan.xml is not automatically synchronized across Data Grid clusters. In this case you should use configuration management tooling, such as Ansible or Chef, to ensure that configuration is propagated to all nodes in your cluster.

11.2. Default Cache Manager

Data Grid Server provides a default Cache Manager configuration. When you start Data Grid Server, it instantiates the Cache Manager so you can remotely create caches at run-time.

Default Cache Manager

<!-- Creates a Cache Manager named "default" and exports metrics. -->
<cache-container name="default"
  <!-- Adds cluster transport that uses the default JGroups TCP stack. -->
  <transport cluster="${}"

Examining the Cache Manager

After you start Data Grid Server and add user credentials, you can access the default Cache Manager through the Command Line Interface (CLI) or REST endpoint as follows:

  • CLI: Use the describe command in the default container.

    [//containers/default]> describe
  • REST: Navigate to <server_hostname>:11222/rest/v2/cache-managers/default/ in any browser.

11.3. Creating Caches with the Data Grid Console

Dynamically add caches from templates or configuration files through the Data Grid console.


Create a user and start at least one Data Grid server instance.


  1. Navigate to <server_hostname>:11222/console/ in any browser.
  2. Log in to the console.
  3. Open the Data Container view.
  4. Select Create Cache and then add a cache from a template or with Data Grid configuration in XML or JSON format.
  5. Return to the Data Container view and verify your Data Grid cache.

11.4. Creating Caches with the Data Grid Command Line Interface (CLI)

Use the Data Grid CLI to add caches from templates or configuration files in XML or JSON format.


Create a user and start at least one Data Grid server instance.


  1. Create a CLI connection to Data Grid.
  2. Add cache definitions with the create cache command.

    • Add a cache definition from an XML or JSON file with the --file option.

      [//containers/default]> create cache --file=configuration.xml mycache
    • Add a cache definition from a template with the --template option.

      [//containers/default]> create cache --template=org.infinispan.DIST_SYNC mycache

      Press the tab key after the --template= argument to list available cache templates.

  3. Verify the cache exists with the ls command.

    [//containers/default]> ls caches
  4. Retrieve the cache configuration with the describe command.

    [//containers/default]> describe caches/mycache

11.5. Creating Remote Caches with Hot Rod Clients

When Hot Rod Java clients attempt to access caches that do not exist, they return null for remoteCacheManager.getCache("myCache") invocations. To avoid this scenario, you can configure Hot Rod clients to create caches on first access using cache configuration.


  • Use the remoteCache() method in the ConfigurationBuilder or use the configuration and configuration_uri properties in


File file = new File("path/to/infinispan.xml")
ConfigurationBuilder builder = new ConfigurationBuilder();
       .configuration("<distributed-cache name=\"another-cache\"/>");

infinispan.client.hotrod.cache.another-cache.configuration=<distributed-cache name=\"another-cache\"/>


When using with cache names that contain the . character, you must enclose the cache name in square brackets as in the preceding example.

You can also create remote caches through the RemoteCacheManager API in other ways, such as the following example that adds a cache configuration with the XMLStringConfiguration() method and then calls the getOrCreateCache() method.

However, Data Grid does not recommend this approach because it can more difficult to ensure XML validity and is generally a more cumbersome way to create caches. If you are creating complex cache configurations, you should save them to separate files in your project and reference them in your Hot Rod client configuration.

String cacheName = "CacheWithXMLConfiguration";
String xml = String.format("<distributed-cache name=\"%s\" mode=\"SYNC\">" +
                              "<encoding media-type=\"application/x-protostream\"/>" +
                              "<locking isolation=\"READ_COMMITTED\"/>" +
                              "<transaction mode=\"NON_XA\"/>" +
                              "<expiration lifespan=\"60000\" interval=\"20000\"/>" +
                           "</distributed-cache>" , cacheName);
remoteCacheManager.administration().getOrCreateCache(cacheName, new XMLStringConfiguration(xml));

Hot Rod code examples

Try some Data Grid code tutorials that show you how to create remote caches in different ways with the Hot Rod Java client.

Visit Data Grid code examples.

11.6. Creating Data Grid Caches with HTTP Clients

Add cache definitions to Data Grid servers through the REST endpoint with any suitable HTTP client.


Create a user and start at least one Data Grid server instance.


  • Create caches with POST requests to /rest/v2/caches/$cacheName.

Use XML or JSON configuration by including it in the request payload.

POST /rest/v2/caches/mycache

Use the ?template= parameter to create caches from org.infinispan templates.

POST /rest/v2/caches/mycache?template=org.infinispan.DIST_SYNC

11.7. Cache Configuration

You can provide cache configuration in XML or JSON format.


<distributed-cache name="myCache" mode="SYNC">
  <encoding media-type="application/x-protostream"/>
  <memory max-count="1000000" when-full="REMOVE"/>


  "distributed-cache": {
    "name": "myCache",
    "mode": "SYNC",
    "encoding": {
      "media-type": "application/x-protostream"
    "memory": {
      "max-count": 1000000,
      "when-full": "REMOVE"

JSON format

Cache configuration in JSON format must follow the structure of an XML configuration. * XML elements become JSON objects. * XML attributes become JSON fields.