Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Performing Cache Operations with the Data Grid CLI

Use the command line interface (CLI) to perform operations on remote caches such as creating caches, manipulating data, and rebalancing.

2.1. Creating remote caches with the Data Grid CLI
Copy link

Use the Data Grid Command Line Interface (CLI) to add remote caches on Data Grid Server.

Prerequisites

  • Create a Data Grid user with admin permissions.
  • Start at least one Data Grid Server instance.
  • Have a Data Grid cache configuration.

Procedure

  1. Start the CLI. 

    bin/cli.sh
    Copy to Clipboard Toggle word wrap
  2. Run the connect command and enter your username and password when prompted.

  3. Use the create cache command to create remote caches.

    For example, create a cache named "mycache" from a file named mycache.xml as follows: 

    create cache --file=mycache.xml mycache
    Copy to Clipboard Toggle word wrap

Verification

  1. List all remote caches with the ls command. 

    ls caches
mycache
    Copy to Clipboard Toggle word wrap

  2. View cache configuration with the describe command. 

    describe caches/mycache
    Copy to Clipboard Toggle word wrap

2.1.1. Cache configuration
Copy link

You can create declarative cache configuration in XML, JSON, and YAML format.

All declarative caches must conform to the Data Grid schema. Configuration in JSON format must follow the structure of an XML configuration, elements correspond to objects and attributes correspond to fields.

Important

Data Grid restricts characters to a maximum of 255 for a cache name or a cache template name. If you exceed this character limit, Data Grid throws an exception. Write succinct cache names and cache template names.

Important

A file system might set a limitation for the length of a file name, so ensure that a cache’s name does not exceed this limitation. If a cache name exceeds a file system’s naming limitation, general operations or initialing operations towards that cache might fail. Write succinct file names.

Distributed caches

XML

<distributed-cache owners="2"
                   segments="256"
                   capacity-factor="1.0"
                   l1-lifespan="5000"
                   mode="SYNC"
                   statistics="true">
  <encoding media-type="application/x-protostream"/>
  <locking isolation="REPEATABLE_READ"/>
  <transaction mode="FULL_XA"
               locking="OPTIMISTIC"/>
  <expiration lifespan="5000"
              max-idle="1000" />
  <memory max-count="1000000"
          when-full="REMOVE"/>
  <indexing enabled="true"
            storage="local-heap">
    <index-reader refresh-interval="1000"/>
    <indexed-entities>
      <indexed-entity>org.infinispan.Person</indexed-entity>
    </indexed-entities>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</distributed-cache>
Copy to Clipboard Toggle word wrap

JSON

{
  "distributed-cache": {
    "mode": "SYNC",
    "owners": "2",
    "segments": "256",
    "capacity-factor": "1.0",
    "l1-lifespan": "5000",
    "statistics": "true",
    "encoding": {
      "media-type": "application/x-protostream"
    },
    "locking": {
      "isolation": "REPEATABLE_READ"
    },
    "transaction": {
      "mode": "FULL_XA",
      "locking": "OPTIMISTIC"
    },
    "expiration" : {
      "lifespan" : "5000",
      "max-idle" : "1000"
    },
    "memory": {
      "max-count": "1000000",
      "when-full": "REMOVE"
    },
    "indexing" : {
          "enabled" : true,
          "storage" : "local-heap",
          "index-reader" : {
            "refresh-interval" : "1000"
          },
          "indexed-entities": [
            "org.infinispan.Person"
          ]
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

YAML

distributedCache:
  mode: "SYNC"
  owners: "2"
  segments: "256"
  capacityFactor: "1.0"
  l1Lifespan: "5000"
  statistics: "true"
  encoding:
    mediaType: "application/x-protostream"
  locking:
    isolation: "REPEATABLE_READ"
  transaction:
    mode: "FULL_XA"
    locking: "OPTIMISTIC"
  expiration:
    lifespan: "5000"
    maxIdle: "1000"
  memory:
    maxCount: "1000000"
    whenFull: "REMOVE"
  indexing:
    enabled: "true"
    storage: "local-heap"
    indexReader:
      refreshInterval: "1000"
    indexedEntities:
      - "org.infinispan.Person"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

Replicated caches

XML

<replicated-cache segments="256"
                  mode="SYNC"
                  statistics="true">
  <encoding media-type="application/x-protostream"/>
  <locking isolation="REPEATABLE_READ"/>
  <transaction mode="FULL_XA"
               locking="OPTIMISTIC"/>
  <expiration lifespan="5000"
              max-idle="1000" />
  <memory max-count="1000000"
          when-full="REMOVE"/>
  <indexing enabled="true"
            storage="local-heap">
    <index-reader refresh-interval="1000"/>
    <indexed-entities>
      <indexed-entity>org.infinispan.Person</indexed-entity>
    </indexed-entities>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</replicated-cache>
Copy to Clipboard Toggle word wrap

JSON

{
  "replicated-cache": {
    "mode": "SYNC",
    "segments": "256",
    "statistics": "true",
    "encoding": {
      "media-type": "application/x-protostream"
    },
    "locking": {
      "isolation": "REPEATABLE_READ"
    },
    "transaction": {
      "mode": "FULL_XA",
      "locking": "OPTIMISTIC"
    },
    "expiration" : {
      "lifespan" : "5000",
      "max-idle" : "1000"
    },
    "memory": {
      "max-count": "1000000",
      "when-full": "REMOVE"
    },
    "indexing" : {
      "enabled" : true,
      "storage" : "local-heap",
      "index-reader" : {
        "refresh-interval" : "1000"
        },
      "indexed-entities": [
        "org.infinispan.Person"
      ]
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

YAML

replicatedCache:
  mode: "SYNC"
  segments: "256"
  statistics: "true"
  encoding:
    mediaType: "application/x-protostream"
  locking:
    isolation: "REPEATABLE_READ"
  transaction:
    mode: "FULL_XA"
    locking: "OPTIMISTIC"
  expiration:
    lifespan: "5000"
    maxIdle: "1000"
  memory:
    maxCount: "1000000"
    whenFull: "REMOVE"
  indexing:
    enabled: "true"
    storage: "local-heap"
    indexReader:
      refreshInterval: "1000"
    indexedEntities:
      - "org.infinispan.Person"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

Multiple caches

XML

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:14.0 https://infinispan.org/schemas/infinispan-config-14.0.xsd
                          urn:infinispan:server:14.0 https://infinispan.org/schemas/infinispan-server-14.0.xsd"
      xmlns="urn:infinispan:config:14.0"
      xmlns:server="urn:infinispan:server:14.0">
  <cache-container name="default"
                   statistics="true">
    <distributed-cache name="mycacheone"
                       mode="ASYNC"
                       statistics="true">
      <encoding media-type="application/x-protostream"/>
      <expiration lifespan="300000"/>
      <memory max-size="400MB"
              when-full="REMOVE"/>
    </distributed-cache>
    <distributed-cache name="mycachetwo"
                       mode="SYNC"
                       statistics="true">
      <encoding media-type="application/x-protostream"/>
      <expiration lifespan="300000"/>
      <memory max-size="400MB"
              when-full="REMOVE"/>
    </distributed-cache>
  </cache-container>
</infinispan>
Copy to Clipboard Toggle word wrap

JSON

{
  "infinispan" : {
    "cache-container" : {
      "name" : "default",
      "statistics" : "true",
      "caches" : {
        "mycacheone" : {
          "distributed-cache" : {
            "mode": "ASYNC",
            "statistics": "true",
            "encoding": {
              "media-type": "application/x-protostream"
            },
            "expiration" : {
              "lifespan" : "300000"
            },
            "memory": {
              "max-size": "400MB",
              "when-full": "REMOVE"
            }
          }
        },
        "mycachetwo" : {
          "distributed-cache" : {
            "mode": "SYNC",
            "statistics": "true",
            "encoding": {
              "media-type": "application/x-protostream"
            },
            "expiration" : {
              "lifespan" : "300000"
            },
            "memory": {
              "max-size": "400MB",
              "when-full": "REMOVE"
            }
          }
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

YAML

infinispan:
  cacheContainer:
    name: "default"
    statistics: "true"
    caches:
      mycacheone:
       distributedCache:
          mode: "ASYNC"
          statistics: "true"
          encoding:
            mediaType: "application/x-protostream"
          expiration:
            lifespan: "300000"
          memory:
            maxSize: "400MB"
            whenFull: "REMOVE"
      mycachetwo:
        distributedCache:
          mode: "SYNC"
          statistics: "true"
          encoding:
            mediaType: "application/x-protostream"
          expiration:
            lifespan: "300000"
          memory:
            maxSize: "400MB"
            whenFull: "REMOVE"
Copy to Clipboard Toggle word wrap

2.2. Modifying Data Grid cache configuration
Copy link

Make changes to your remote cache configuration with the Data Grid CLI. You can modify attributes in your cache configuration either one at a time or provide a cache configuration in XML, JSON or YAML format to modify several attributes at once.

Prerequisites

  • Create at least one remote cache on your Data Grid cluster.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Modify the cache configuration with the alter command in one of the following ways:

    • Use the --file option to specify a configuration file with one or more attribute modifications.

    • Use the --attribute and --value option to modify a specific configuration attribute.

      Tip

      For more information and examples, run the help alter command.

  3. Verify your changes with the describe command, for example: 

    describe caches/mycache
    Copy to Clipboard Toggle word wrap

2.3. Adding Cache Entries
Copy link

Create key:value pair entries in the data container.

Prerequisites

Create a Data Grid cache that can store your data.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Add entries into your cache as follows:

    • Use the --cache= with the put command: 

      put --cache=mycache hello world
      Copy to Clipboard Toggle word wrap

    • Use the put command from the context of a cache: 

      [//containers/default/caches/mycache]> put hello world
      Copy to Clipboard Toggle word wrap

  3. Use the get command to verify entries. 

    [//containers/default/caches/mycache]> get hello
world
    Copy to Clipboard Toggle word wrap

2.4. Clearing Caches and Deleting Entries
Copy link

Remove data from caches with the Data Grid CLI.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Do one of the following:

    • Delete all entries with the clearcache command. 

      clearcache mycache
      Copy to Clipboard Toggle word wrap

    • Remove specific entries with the remove command. 

      remove --cache=mycache hello
      Copy to Clipboard Toggle word wrap

2.5. Deleting Caches
Copy link

Drop caches to remove them and delete all data they contain.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Remove caches with the drop command. 

    drop cache mycache
    Copy to Clipboard Toggle word wrap

2.6. Configuring Automatic Cache Rebalancing
Copy link

By default, Data Grid automatically rebalances caches as nodes join and leave the cluster. You can configure automatic cache rebalancing by disabling or enabling it at the Cache Manager level or on a per-cache basis.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Disable automatic rebalancing for all caches with the rebalance disable command. 

    rebalance disable
    Copy to Clipboard Toggle word wrap

  3. Enable automatic rebalancing for a specific cache with the rebalance enable command.

    The following example enables rebalancing for the cache named "mycache" only. 

    rebalance enable caches/mycache
    Copy to Clipboard Toggle word wrap

  4. Re-enable automatic rebalancing for all caches. 

    rebalance enable
    Copy to Clipboard Toggle word wrap

For more information about the rebalance command, run help rebalance.

2.7. Set a Stable Topology
Copy link

By default, after a cluster shutdown, Data Grid waits for all nodes to join the cluster and restore the topology. However, we offer a CLI command to mark the current topology stable for a specific cache.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Do one of the following:

    • Set the current topology as stable for the given cache. 

      topology set-stable cacheName
      Copy to Clipboard Toggle word wrap

    • If the current topology is missing more nodes than the number of owners, the force flag is necessary to confirm the operation. 

      topology set-stable cacheName -f
      Copy to Clipboard Toggle word wrap

For more information about the topology set-stable command, run topology set-stable -h.

Important

Manually installing a topology can lead to data loss, only perform this operation if the initial topology cannot be recreated.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat