Migration Guide

Red Hat JBoss Data Grid 7.2

For Use with JBoss Data Grid 7.2

Red Hat Customer Content Services

Abstract

This guide presents information about migrating to Red Hat JBoss Data Grid 7.2.

Chapter 1. Introduction

1.1. Red Hat JBoss Data Grid

Red Hat JBoss Data Grid is a distributed in-memory data grid, which provides the following capabilities:

  • Schemaless key-value store – JBoss Data Grid is a NoSQL database that provides the flexibility to store different objects without a fixed data model.
  • Grid-based data storage – JBoss Data Grid is designed to easily replicate data across multiple nodes.
  • Elastic scaling – Adding and removing nodes is simple and non-disruptive.
  • Multiple access protocols – It is easy to access the data grid using REST, Memcached, Hot Rod, or simple map-like API.

1.2. About the Migration Guide

The purpose of this guide is to document the changes that are required to successfully run and deploy Red Hat JBoss Data Grid applications on subsequent versions of Red Hat JBoss Data Grid. It provides information on how to resolve deployment and runtime problems and to how prevent changes in application behavior. This is the first step in moving to the new platform. Once the application is successfully deployed and running, plans can be made to upgrade individual components to use the new functions and features of Red Hat JBoss Data Grid 7.2.

Chapter 2. Migrating to JBoss Data Grid 7.2

2.1. Migrating to JBoss Data Grid 7.2

When migrating to JBoss Data Grid 7.2 from JBoss Data Grid 6.6 or earlier, first follow the steps in Migrating to JBoss Data Grid 7.0 and then perform the steps in this section.

2.1.1. Product Changes

Review changes to JBoss Data Grid that impact functionality or configuration between releases.

2.1.1.1. Update Configuration for Partition Handling

In releases of JBoss Data Grid earlier than 7.2, the configuration for network partition handling was as follows:

<partition-handling enabled="true|false">

As of JBoss Data Grid 7.2 the following configuration takes effect:

<partition-handling when-split="ALLOW_READ_WRITES" merge-policy="NONE"/>

Before migrating to JBoss Data Grid 7.2, you should review the documentation to understand the different partition handling strategies and merge policies that JBoss Data Grid can use to resolve conflicts.

See the following sections of the Administration and Configuration Guide for more information:

2.1.1.2. Eviction Strategy Deprecation

JBoss Data Grid 7.2 improves the data container by deprecating the eviction configuration and adding a memory configuration. You should review these changes before migrating from an earlier release. For more information, see Set Up JVM Memory Management in the Administration and Configuration Guide.

Chapter 3. Migrating to JBoss Data Grid 7.1

3.1. Migrating to JBoss Data Grid 7.1

When migrating to JBoss Data Grid 7.1 from JBoss Data Grid 6.6 or earlier, first follow the steps in Migrating to JBoss Data Grid 7.0 and then perform the steps in this section.

3.2. Product Changes

3.2.1. Remote Client-Server Configuration Changes

The configuration files for remote client-server mode have been updated in JBoss Data Grid 7.1, and there have been numerous changes to the included configuration files. It is strongly recommended to use the base configurations included in JBoss Data Grid 7.1, and then apply any modifications to these base files. The new configurations result in increased performance, and provide a baseline for further tunings.

In addition, it is no longer required to define a mode for clustered caches. Starting in JBoss Data Grid 7.1 the mode defaults to SYNC.

Chapter 4. Migrating to JBoss Data Grid 7.0

4.1. Product Changes

4.1.1. Library Mode Configuration Update

The XML schema for Library mode configurations has been changed to be more consistent with the remote client-server schema. This results in several changes that must be made to the configuration file.

To assist in these configurations a tool is provided in the library distribution. The following steps discuss using this tool to automatically convert existing infinispan configuration files to the latest supported schema.

Procedure: Windows Instructions for Using the Library Mode Configuration Converter

  1. Open a command prompt.
  2. Navigate to the bin\ directory of the library distribution:

    cd C:\path\to\jboss-datagrid-${jdg-version}-library\bin\
  3. If any custom classes were referenced in the original configuration then the .jar files containing these classes must be placed in the C:\path\to\jboss-datagrid-${jdg-version}-library\ directory. If no custom classes were referenced then this step may be skipped.
  4. Execute the config-converter.bat utility, passing in the name of the existing infinispan_6.0.xml configuration file and the destination as arguments:

    config-converter C:\path\to\infinispan_6.0.xml C:\path\to\infinispan-new.xml
  5. Ensure that infinispan-new.xml has been created with the new Library mode configurations. This file may now be used in Library mode applications with JBoss Data Grid 7.0.

Procedure: Linux Instructions for Using the Library Mode Configuration Converter.

  1. Open a console to execute the following commands.
  2. Navigate to the bin/ directory of the library distribution:

    cd /path/to/jboss-datagrid-${jdg-version}-library/bin/
  3. If any custom classes were referenced in the original configuration then the .jar files containing these classes must be placed in the /path/to/jboss-datagrid-${jdg-version}-library/ directory. If no custom classes were referenced then this step may be skipped.
  4. Execute the config-converter.sh utility, passing in the name of the existing infinispan_6.0.xml configuration file and the destination as arguments:

    ./config-converter.sh /path/to/infinispan_6.0.xml /path/to/infinispan-new.xml
  5. Ensure that infinispan-new.xml has been created with the new Library mode configurations. This file may now be used in Library mode applications with JBoss Data Grid 7.0.
Note

If no destination file is specified, such as infinispan-new.xml in the above examples, the utility will instead display the converted xml to the console.

4.1.2. CLI Commands

The following CLI commands have been changed for JBoss Data Grid 7.0:

  • clear - This command has been replaced by clearcache.
  • help $COMMAND - Instead of executing help per command, each command now has a built in --help flag that is used instead.

4.1.3. Server Managment

The default JBoss Data Grid server management port has been changed to 9990.

4.1.4. JGroups ENCRYPT Protocol Deprecated

The JGroups ENCRYPT protocol has been deprecated, and should be replaced with either the SYM_ENCRYPT or ASYM_ENCRYPT protocols. Both of these protocols must be placed directly under NAKACK2. Configuration details are provided in the Administration and Configuration Guide ; however, example configurations for each protocol are shown below:

SYM_ENCRYPT Configuration Example

<SYM_ENCRYPT sym_algorithm="AES"
            encrypt_entire_message="true"
            keystore_name="defaultStore.keystore"
            store_password="changeit"
            alias="myKey"/>

ASYM_ENCRYPT Configuration Example

<ASYM_ENCRYPT encrypt_entire_message="true"
             sym_keylength="128"
             sym_algorithm="AES/ECB/PKCS5Padding"
             asym_keylength="512"
             asym_algorithm="RSA"/>

4.1.5. JBoss EAP Maven Repository Dependencies

Red Hat JBoss Data Grid 7.0 and later depends on the JBoss EAP Maven repository. In addition to the artifacts in the JBoss Data Grid Maven repository, you should also install the artifacts from the JBoss EAP 7.0.0 Maven repository.

4.2. Application Changes

4.2.1. NotifyingFuture replaced by CompletableFuture

The NotifyingFuture interface has been removed in JBoss Data Grid 7.0 and replaced with CompletableFuture. This class was replaced due to CompletableFuture being included as a standard class in Java 8, allowing for additional features such as chaining, implementing constructs such as conditionals, and timeouts to be utilized without introducing additional custom code.

Due to this change any applications utilizing NotifyingFuture will need to be replaced with CompletableFuture to function correctly with JBoss Data Grid 7.0.

4.2.2. JBoss Modules CDI Dependency

JBoss Modules CDI Dependencies

The package containing the CDI classes has changed. All of these classes have moved from org.infinispan.cdi to org.infinispan.cdi.embedded, and any applications utilizing CDI should have their imports updated to use the new packages.

Configuration of CDI/JCache

CDI Extensions have been split into two separate types of classes:

  1. CDI Classes that begin with Injected before the classname, such as org.infinispan.jcache.annotation.InjectedCacheResultInterceptor. These classes are intended for use in managed environments, such as JBoss EAP.
  2. CDI classes without Injected before the classname, such as org.infinispan.jcache.annotation.CacheResultInterceptor - This class should be used in standalone environments.

4.2.3. Spring 3 support removed

Spring 3 support has been removed in JBoss Data Grid 7.0. Any applications will need to be rewritten to use Spring 4.

4.2.4. RemoteCache Deprecated Methods

The following methods have been deprecated in JBoss Data Grid 7.0:

  • remoteCache.getVersioned - This method has been replaced by remoteCache.getWithMetadata(Object).
  • remoteCache.getBulk, getBulk(size) - Both of these methods have proven expensive for large data sets. The remoteCache.retrieveEntries* methods offer a lazy, pull-style, approach which retrieves bulk data more efficiently.

4.2.5. Interceptors Deprecated

Support for custom interceptors is being deprecated in JBoss Data Grid 7.0. A new method of executing custom interceptors is expected to be introduced in JBoss Data Grid 7.1. In addition, the interceptor stack is part of JBoss Data Grid’s internal API, and is subject to change from release to release. Due to this it is not recommended to use custom interceptors directly from your application.

4.2.6. Map/Reduce replaced by Distributed Streams

Map/Reduce has been removed in JBoss Data Grid 7.0.0. This feature has been replaced by Distributed Streams, which were shown to have better performance.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.