Upgrading the Client

There are two upgrade scenarios:

  • Minor version upgrade: Update your current version of the Native Client with its next minor revision, which typically incorporates non-breaking changes; for example, from Native Client 9.1 to minor version 9.2.

  • Major version upgrade: Update your client for compatibility with a new GemFire server. This usually involves an upgrade from one major version to another; for example, from Native Client version 8 to version 9.

Minor Version Upgrade

To upgrade from one minor version to another:

  1. Install the Native Client library. Consult the Release Notes for feature changes and bug fixes that might affect your application.
  2. Compile your application and verify that it works as expected.

Major Version Upgrade

Upgrading your GemFire server software from one major version to another, such as GemFire version 8 to GemFire version 9, usually introduces breaking changes. A server upgrade from one major version to another should be followed by a client upgrade, and updating your client applications will require more intervention than merely recompiling.

To allow for client upgrades, server developers usually support one earlier version of the client software, so your current clients will continue to run with the new server for a certain window of time. In general, however, you will have best performance and reliability if:

  • All clients run the same version of the client software.
  • Clients and servers both run the latest versions of their respective software.

GemFire server and client software releases follow similar numbering schemes, but they are not released in lockstep. The following diagram illustrates the interoperability between recent versions of GemFire server software and GemFire Native Client software.

Changes you may need to make when you update, recompile, and link your client code include:

  • Removing or replacing obsolete identifiers
  • Renaming packages
  • Reinstating secure client/server messaging

Remove or Replace Obsolete Identifiers

Review the Release Notes for a list of classes, methods, and other identifiers that are no longer present in the current release. Update client code so it no longer uses any of these removed identifiers.

Rename Packages

Pivotal GemFire 9 uses the same packages as open-source Apache Geode. Beginning with Gemfire version 9.0, com.gemstone.gemfire package names are now org.apache.geode. The server class path uses geode-dependencies.jar in place of the no-longer-used gemfire.jar and server-dependencies.jar. If you have written code that explicitly imports gemfire packages, you must change those references to use the geode names and recompile.

For C++ clients, update the namespace to use apache::geode::client in place of gemfire.

For .NET clients, use Apache.Geode.Client in place of Gemstone.GemFire.Cache.Generic.

The Pivotal GemFire 9.x release is backwards compatible with Pivotal GemFire 8.2.3 and more recent 8.2 clients, so a version 9 server will understand calls from an 8.2.3 client that uses the old com.gemstone.gemfire package names. There is one exception: Pivotal GemFire 8.x clients that run functions on servers using the Execution interface’s execute(Function function) signature cannot work with GemFire 9.x servers. Clients that run server-side functions with this signature must be reimplemented as 9.x clients that use the 9.x package names.

Reinstate Secure Client/Server Messaging After Upgrading

When servers are upgraded to GemFire v9.1.1 or later from an earlier release, their authentication of client messages is deactivated to facilitate rolling upgrades. If your clients are set up to send authenticated messages, the servers will honor those messages but will not enforce authentication until you reinstate authentication on each of the upgraded servers. To reinstate secure client/server messaging, restart each server with the geode.disallow-internal-messages-without-credentials system property set to true. For example:

gfsh>start server --name=server_name --dir=server_config_dir \
--J=-Dgeode.disallow-internal-messages-without-credentials=true