Chapter 3. Migrating Data Grid configuration

When you create remote caches you should configure the MediaType for keys and values. Configuring the MediaType guarantees the storage format for your data.

To encode caches, you specify the MediaType in your configuration. Unless you have others requirements, you should use ProtoStream, which stores your data in a language-neutral, backwards compatible format.

<encoding media-type="application/x-protostream"/>

<infinispan>
    <cache-container>
        <distributed-cache name="myCache" mode="SYNC">
          <encoding media-type="application/x-protostream"/>
           ...
        </distributed-cache>
    </cache-container>
</infinispan>

<infinispan>
    <cache-container>
        <distributed-cache name="myCache" mode="SYNC">
          <encoding media-type="application/x-protostream"/>
           ...
        </distributed-cache>
    </cache-container>
</infinispan>

If you do not encode remote caches, Data Grid Server logs the following message:

WARN  (main) [org.infinispan.encoding.impl.StorageConfigurationManager] ISPN000599: Configuration for cache 'mycache' does not define the encoding for keys or values. If you use operations that require data conversion or queries, you should configure the cache with a specific MediaType for keys or values.

WARN  (main) [org.infinispan.encoding.impl.StorageConfigurationManager] ISPN000599: Configuration for cache 'mycache' does not define the encoding for keys or values. If you use operations that require data conversion or queries, you should configure the cache with a specific MediaType for keys or values.

In a future version, cache encoding will be required for operations where data conversion takes place; for example, cache indexing and searching the data container, remote task execution, reading and writing data in different formats from the Hot Rod and REST endpoints, as well as using remote filters, converters, and listeners.

Data Grid 7.x includes a Health Check API that returns health status of the cluster as well as caches within it.

Data Grid 8 also provides a Health API. For embedded and server installations, you can access the Health API via JMX with the following MBean:

org.infinispan:type=CacheManager,name="default",component=CacheContainerHealth

org.infinispan:type=CacheManager,name="default",component=CacheContainerHealth

Data Grid Server also exposes the Health API through the REST endpoint and the Data Grid Console.

This topic lists changes to the Data Grid configuration schema between 8.0 and 8.1.

New and modified elements and attributes

Deprecated elements and attributes

The following elements and attributes are now deprecated:

Removed elements and attributes

The following elements and attributes were deprecated in a previous release and are now removed:

This topic lists changes to the Data Grid configuration schema between 8.1 and 8.2.

Modified elements and attributes

New elements and attributes

Deprecated elements and attributes

No elements or attributes are deprecated in Data Grid 8.2.

Removed elements and attributes

No elements or attributes are removed in Data Grid 8.2.

This topic lists changes to the Data Grid configuration schema between 8.2 and 8.3.

Schema changes

Modified elements and attributes

New elements and attributes

Deprecated elements and attributes

The following elements and attributes are now deprecated:

Removed elements and attributes

The following elements and attributes are no longer available in the Data Grid schema:

This topic lists changes to the Data Grid configuration schema between 8.3 and 8.4.

Schema changes

New elements and attributes

Deprecated elements and attributes

The following elements and attributes are now deprecated:

Removed elements and attributes

The following elements and attributes are no longer available in the Data Grid schema:

Data Grid lets you control how to store entries in memory, with the following options:

Changes in Data Grid 8

In previous 7.x versions, and 8.0, you use object, binary, and off-heap elements to configure the storage type.

Starting with Data Grid 8.1, you use a storage attribute to store objects in JVM heap memory or as bytes in off-heap memory.

To store bytes in JVM heap memory, you use the encoding element to specify a binary storage format for your data.

Object storage in Data Grid 8

By default, Data Grid 8.1 uses object storage (JVM heap):

<distributed-cache>
   <memory />
</distributed-cache>

<distributed-cache>
   <memory />
</distributed-cache>

You can also configure storage="HEAP" explicitly to store data as objects in JVM heap memory:

<distributed-cache>
   <memory storage="HEAP" />
</distributed-cache>

<distributed-cache>
   <memory storage="HEAP" />
</distributed-cache>

Off-heap storage in Data Grid 8

Set "OFF_HEAP" as the value of the storage attribute to store data as bytes in native memory:

<distributed-cache>
   <memory storage="OFF_HEAP" />
</distributed-cache>

<distributed-cache>
   <memory storage="OFF_HEAP" />
</distributed-cache>

Off-heap address count

In previous versions, the address-count attribute for offheap lets you specify the number of pointers that are available in the hash map to avoid collisions. With Data Grid 8.1, address-count is no longer used and off-heap memory is dynamically re-sized to avoid collisions.

Binary storage in Data Grid 8

Specify a binary storage format for cache entries with the encoding element:

<distributed-cache>
   <!--Configure MediaType for entries with binary formats.-->
   <encoding media-type="application/x-protostream"/>
   <memory ... />
</distributed-cache>

<distributed-cache>
   <!--Configure MediaType for entries with binary formats.-->
   <encoding media-type="application/x-protostream"/>
   <memory ... />
</distributed-cache>

Eviction lets Data Grid control the size of the data container by removing entries when the container becomes larger than a configured threshold.

In Data Grid 7.x and 8.0, you specify two eviction types that define the maximum limit for entries in the cache:

Depending on the configuration you set, when either the count or the total amount of memory exceeds the maximum, Data Grid removes unused entries.

Data Grid 7.x and 8.0 also use the size attribute that defines the size of the data container as a long. Depending on the storage type you configure, eviction occurs either when the number of entries or amount of memory exceeds the value of the size attribute.

With Data Grid 8.1, the size attribute is deprecated along with COUNT and MEMORY. Instead, you configure the maximum size of the data container in one of two ways:

Eviction based on total number of entries

<distributed-cache>
   <memory max-count="..." />
</distributed-cache>

<distributed-cache>
   <memory max-count="..." />
</distributed-cache>

Eviction based on maximum amount of memory

<distributed-cache>
   <memory max-size="..." />
</distributed-cache>

<distributed-cache>
   <memory max-size="..." />
</distributed-cache>

Eviction strategies control how Data Grid performs eviction.

Data Grid 7.x and 8.0 let you set one of the following eviction strategies with the strategy attribute:

With Data Grid 8.1, you can use the same strategies as in previous versions. However, the strategy attribute is replaced with the when-full attribute.

<distributed-cache>
   <memory when-full="<eviction_strategy>" />
</distributed-cache>

<distributed-cache>
   <memory when-full="<eviction_strategy>" />
</distributed-cache>

Eviction algorithms

With Data Grid 7.2, the ability to configure eviction algorithms was deprecated along with the Low Inter-Reference Recency Set (LIRS).

From version 7.2 onwards, Data Grid includes the Caffeine caching library that implements a variation of the Least Frequently Used (LFU) cache replacement algorithm known as TinyLFU. For off-heap storage, Data Grid uses a custom implementation of the Least Recently Used (LRU) algorithm.

Compare eviction configuration between different Data Grid versions.

Object storage and evict on number of entries

7.2 to 8.0

<memory>
  <object size="1000000" eviction="COUNT" strategy="REMOVE"/>
</memory>

<memory>
  <object size="1000000" eviction="COUNT" strategy="REMOVE"/>
</memory>

8.1

<memory max-count="1MB" when-full="REMOVE"/>

<memory max-count="1MB" when-full="REMOVE"/>

Object storage and evict on amount of memory

7.2 to 8.0

<memory>
  <object size="1000000" eviction="MEMORY" strategy="MANUAL"/>
</memory>

<memory>
  <object size="1000000" eviction="MEMORY" strategy="MANUAL"/>
</memory>

8.1

<memory max-size="1MB" when-full="MANUAL"/>

<memory max-size="1MB" when-full="MANUAL"/>

Binary storage and evict on number of entries

7.2 to 8.0

<memory>
  <binary size="500000000" eviction="MEMORY" strategy="EXCEPTION"/>
</memory>

<memory>
  <binary size="500000000" eviction="MEMORY" strategy="EXCEPTION"/>
</memory>

8.1

<cache>
   <encoding media-type="application/x-protostream"/>
   <memory max-size="500 MB" when-full="EXCEPTION"/>
</cache>

<cache>
   <encoding media-type="application/x-protostream"/>
   <memory max-size="500 MB" when-full="EXCEPTION"/>
</cache>

Binary storage and evict on amount of memory

7.2 to 8.0

<memory>
  <binary size="500000000" eviction="COUNT" strategy="MANUAL"/>
</memory>

<memory>
  <binary size="500000000" eviction="COUNT" strategy="MANUAL"/>
</memory>

8.1

<memory max-count="500 MB" when-full="MANUAL"/>

<memory max-count="500 MB" when-full="MANUAL"/>

Off-heap storage and evict on number of entries

7.2 to 8.0

<memory>
  <off-heap size="10000000" eviction="COUNT"/>
</memory>

<memory>
  <off-heap size="10000000" eviction="COUNT"/>
</memory>

8.1

<memory storage="OFF_HEAP" max-count="10MB"/>

<memory storage="OFF_HEAP" max-count="10MB"/>

Off-heap storage and evict on amount of memory

7.2 to 8.0

<memory>
  <off-heap size="1000000000" eviction="MEMORY"/>
</memory>

<memory>
  <off-heap size="1000000000" eviction="MEMORY"/>
</memory>

8.1

<memory storage="OFF_HEAP" max-size="1GB"/>

<memory storage="OFF_HEAP" max-size="1GB"/>

Including file-store persistence in cache configuration now creates a soft index file-based cache store, SoftIndexFileStore, instead of a single-file cache store, SingleFileStore. In Data Grid 8.2 and earlier, SingleFileStore was the default for file-based cache stores.

If you are migrating or upgrading to Data Grid 8.3, any file-store configuration is automatically converted to a SoftIndexFileStore at server startup. When your configuration is converted to SoftIndexFileStore, it is not possible to revert back to SingleFileStore without modifying the configuration to ensure compatibility with the new store.

<persistence>
  <soft-index-file-store xmlns="urn:infinispan:config:soft-index:12.1">
    <index path="testCache/index" />
    <data path="testCache/data" />
  </soft-index-file-store>
</persistence>

<persistence>
  <soft-index-file-store xmlns="urn:infinispan:config:soft-index:12.1">
    <index path="testCache/index" />
    <data path="testCache/data" />
  </soft-index-file-store>
</persistence>

<persistence>
  <file-store>
    <index path="testCache/index" />
    <data path="testCache/data" />
  </file-store>
</persistence>

<persistence>
  <file-store>
    <index path="testCache/index" />
    <data path="testCache/data" />
  </file-store>
</persistence>

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addStore(SoftIndexFileStoreConfigurationBuilder.class)
        .indexLocation("testCache/index");
        .dataLocation("testCache/data")

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addStore(SoftIndexFileStoreConfigurationBuilder.class)
        .indexLocation("testCache/index");
        .dataLocation("testCache/data")

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSoftIndexFileStore()
        .indexLocation("testCache/index")
        .dataLocation("testCache/data");

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSoftIndexFileStore()
        .indexLocation("testCache/index")
        .dataLocation("testCache/data");

<persistence passivation="false">
  <single-file-store shared="false"
                     preload="true"
                     fetch-state="true"
                     read-only="false"/>
</persistence>

<persistence passivation="false">
  <single-file-store shared="false"
                     preload="true"
                     fetch-state="true"
                     read-only="false"/>
</persistence>

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSingleFileStore();

ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSingleFileStore();

As in previous versions, Data Grid 8 uses the JGroups SYM_ENCRYPT and ASYM_ENCRYPT protocols to encrypt cluster communication.

As of Data Grid you can also use a security realm that includes a keystore and trust store as a TLS server identity to secure cluster transport, for example:

<cache-container>
  <transport server:security-realm="tls-transport"/>
</cache-container>

<cache-container>
  <transport server:security-realm="tls-transport"/>
</cache-container>

As of Data Grid 8, it is not possible to configure node authentication against security realms. Likewise Data Grid 8 does not recommend using the JGroups AUTH protocol for authenticating clustered nodes.

However, with embedded Data Grid installations, JGroups cluster transport includes a SASL configuration as part of the jgroups element. As in previous versions, the SASL configuration relies on JAAS notions, such as CallbackHandlers, to obtain certain information necessary for node authentication.

Data Grid 8.2 changes the configuration for retransmission requests for the UNICAST3 and NAKACK2 protocols in the default JGroups stacks, as follows:

As part of your migration to Data Grid 8 you should adapt any custom JGroups stack configuration to use these recommended settings.