Chapter 6. Remotely Creating Data Grid Caches

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

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

Important

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.

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

<cache-container name="default" 1
                 statistics="true"> 2
  <transport cluster="${infinispan.cluster.name:cluster}" 3
             stack="${infinispan.cluster.stack:tcp}" 4
             node-name="${infinispan.node.name:}"/> 5
</cache-container>

1
Creates a Cache Manager named "default".
2
Exports Cache Manager statistics through the metrics endpoint.
3
Adds a JGroups cluster transport that allows Data Grid servers to automatically discover each other and form clusters.
4
Uses the default TCP stack for cluster traffic.
5
Individual name for the node, must be unique across the cluster. Uses a unified hostname by default.

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.

6.3. Creating Caches with the Data Grid Console

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

Prerequisites

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

Procedure

  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.

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

Prerequisites

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

Procedure

  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
      Tip

      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
mycache

  4. Retrieve the cache configuration with the describe command. 

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

Reference

6.5. Creating Caches with Hot Rod Clients

Programmatically create caches on Data Grid Server through the RemoteCacheManager API.

Note

The following procedure demonstrates programmatic cache creation with the Hot Rod Java client. However Hot Rod clients are available in different languages such as Javascript or C++.

Prerequisites

  • Create a user and start at least one Data Grid server instance.
  • Get the Hot Rod Java client.

Procedure

  1. Configure your client with the ConfigurationBuilder class. 

    import org.infinispan.client.hotrod.RemoteCacheManager;
import org.infinispan.client.hotrod.DefaultTemplate;
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;
import org.infinispan.commons.configuration.XMLStringConfiguration;
...

ConfigurationBuilder builder = new ConfigurationBuilder();
builder.addServer()
         .host("127.0.0.1")
         .port(11222)
       .security().authentication()
          .enable()
          .username("username")
          .password("password")
          .realm("default")
          .saslMechanism("DIGEST-MD5");

manager = new RemoteCacheManager(builder.build());
  2. Use the XMLStringConfiguration class to add cache definitions in XML format.

  3. Call the getOrCreateCache() method to add the cache if it already exists or create it if not. 

    private void createCacheWithXMLConfiguration() {
    String cacheName = "CacheWithXMLConfiguration";
    String xml = String.format("<infinispan>" +
                                  "<cache-container>" +
                                  "<distributed-cache name=\"%s\" mode=\"SYNC\"
                                  statistics=\"true\">" +
                                    "<locking isolation=\"READ_COMMITTED\"/>" +
                                    "<transaction mode=\"NON_XA\"/>" +
                                    "<expiration lifespan=\"60000\" interval=\"20000\"/>" +
                                  "</distributed-cache>" +
                                  "</cache-container>" +
                                "</infinispan>"
                                , cacheName);
    manager.administration().getOrCreateCache(cacheName, new XMLStringConfiguration(xml));
    System.out.println("Cache created or already exists.");
}

  4. Create caches with org.infinispan templates as in the following example with the createCache() invocation: 

    private void createCacheWithTemplate() {
    manager.administration().createCache("myCache", "org.infinispan.DIST_SYNC");
    System.out.println("Cache created.");
}

Next Steps

Try some working code examples that show you how to create remote caches with the Hot Rod Java client. Visit the Data Grid Tutorials.

Reference

6.6. Creating Data Grid Caches with HTTP Clients

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

Prerequisites

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

Procedure

  • 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

Reference

6.7. Data Grid Configuration

Data Grid configuration in XML and JSON format.

6.7.1. XML Configuration

Data Grid configuration in XML format must conform to the schema and include:

  • <infinispan> root element.
  • <cache-container> definition.

Example XML Configuration

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

6.7.2. JSON Configuration

Data Grid configuration in JSON format:

  • Requires the cache definition only.

  • Must follow the structure of an XML configuration.

    • XML elements become JSON objects.
    • XML attributes become JSON fields.

Example JSON Configuration

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