Upgrading a Native Client Application From Version 9 to Version 10

GemFire Native Client Version 10 introduces breaking changes for Version 9 applications. Updating your client applications will require more intervention than merely recompiling.

In general, you will have best performance and reliability if 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.

Overview of Changes

VMware Tanzu GemFire Native Client improvements and new features include:

• A modernized C++ API that constitutes a big step forward to fully supporting C++ 11.

• Local memory management has been greatly improved, as well as the adoption of a new cache model that allows for multiple cache objects to exist in a given process space.

• The .NET interface benefits from all the enhancements made in the C++ interface.

• The Native Client now supports IIS application domains and Pivotal Cloud Foundry.

• A new architecture that allows for more flexible client-side data models

• Improvements to the reflection-based AutoSerializer

The Apache Geode community has a host of examples based on the latest C++ and .NET APIs (https://github.com/apache/geode-native/tree/develop/examples).

For examples of source changes see the Native Client 9 to Native Client 10 Upgrade Sample.

These examples show both the original and new API usage, and may be helpful as starting points for upgrading your application to Native Client 10. To see details for upgrading your particular API usage refer to the Native Client 10 API documentation:

• C++ API docs
• .NET API docs

Compiler Upgrade

Using Version 10 of the Native Client with your application requires a C++11-compatible compiler.

Removal of Cache Singleton

A major change in Native Client 10 is the change from a singleton-based design to an instance-based design. This gives developers greater programming flexibility, as client cache instances can have completely independent access to the GemFire data grid.

Multiple client-side instances of Cache do not automatically share objects with each another.

The cache creation process in Native Client 10 follows a different pattern and now returns an object (see examples). Each also requires a pool. Native Client 10 further simplifies the cache creation and system architecture with the removal of DistributedSystem. An instance of DistributedSystem is no longer needed to manage an application’s “connecting” into the GemFire Java server. This is now managed through a Cache instance.

A note to .NET users of the Native Client: users can pass in an instance of their authorization class into the CacheFactory (CacheFactory.SetAuthInitialize(app_auth);).

Serialization Interface Changes

The Native Client serialization APIs for both C++ and .NET have been changed to more closely resemble the behavior of the GemFire Java client. The serializable API has been refactored into data serializable and PDX serializable interfaces. In addition, to be consistent with the Java Server, the new data serializable interface does not have fixed ClassId properties. ClassId is now a parameter passed in to register a given type.

C++ Standardization

In Native Client 10, many version 9 utility classes, such as shared pointers, have been replaced by their equivalents from the C++11 standard library.

One of the biggest changes made in Native Client 10 is the replacement of custom apache::geode::client::SharedPtr with std::shared_ptr. The custom base object apache::geode::client::SharedBase has been removed and is no longer a required derivation to make library objects reference counted; instead objects may simply be wrapped by a std::shared_ptr<>. Upgrading to Native Client 10 requires replacing all *Ptr types with their C++11 replacements.

For example, replace

RegionPtr regionPtr; 

with

std::shared_ptr<Region> regionPtr;

Other adopted C++11 standards include:

• All time values now use std::chrono. For example, std::chrono replaces CacheableDate
• Longs and ints are now replaced with language primitives of explicit size, such as int32_t and int16_t.
• std:string replaces char *
• std container classes
• PDXSerializable::objectSize() and DataSerializable::objectSize() return size_t
• Properties use std::unordered map

Enum Classes

The following Version 9 Enums are now defined as C++11 Enum classes in the Version 10 client:

• CqOperation
• CqState
• ExpirationAction
• PdxFieldTypes

Exceptions

GemFire Native Client Exceptions, which were implemented as macros in v9, are now classes that inherit from std::exception.

Object Oriented Design Patterns

Native Client 10 has adopted many more object oriented design patterns. For example, the CacheFactory now uses a builder pattern and returns a value rather than a pointer.

Other examples of pattern-oriented changes:

• Replace apache::geode::client::PoolPtr with std::shared_ptr<apache::geode::client::Pool>
• Replace apache::geode::client::RegionPtr with std::shared_ptr<apache::geode::client::Region>
• Replace apache::geode::client::EntryEventPtr with std::shared_ptr<apache::geode::client::EntryEvent>
• Replace apache::geode::client::CachePtr with std::unique_ptr<apache::geode::client::Cache>
• PdxSerializable toData/fromData are now passed to PdxWriter/PdxReader as references
• Execution factory returns value type
• Cache::createPdxInstanceFactory returns object
• CqQuery::getCqAttributesMutator returns value
• Cache::createDataInput/Output returns value

Initialization Files

The best practice for most applications is to set properties and parameters programmatically. For clients that use the older, file-based scheme, the following changes apply to the system initialization files, geode.properties and cache.xml:

• In both files, parameters specifying times should include units (s, m, h, etc.).
• For the cache.xml file, the schema name space and location have changed. Use

  <client-cache
    xmlns="http://geode.apache.org/schema/cpp-cache"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://geode.apache.org/schema/cpp-cache
      http://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd"
    version="1.0">

Other Changes

• The $GFCPP environment variable is no longer needed
• enable-chunk-handler-thread now defaults to false and replaces disable-chunk-handler-thread
• Native Client 10 now supports OpenSSL
• Statistics and StatisticsFactory are no longer available

.NET API Changes

These .NET API classes have changed as follows:

CacheFactory

• Creation was via static method CreateCacheFactory, now created via new
• Authorization implementation now is a setter on factory called SetAuthInitialize
• Appdomain property is no longer a supported property
• GetAnyInstance() is no longer supported (there is no more global singleton). Make method calls on the specific instance you are working with

PoolFactory

• Creation was obtained via static method PoolManager.CreateFactory, now via GetPoolFactory method on Cache
• SetEntryTimeToLive - was int, now uses TimeSpan
• SetEntryIdleTimeout - was int, now uses TimeSpan
• SetRegionTimeToLive - was int, now uses TimeSpan
• SetRegionIdleTimeout - was int, now uses TimeSpan

RegionFactory

• SetEntryTimeToLive - was int, now uses TimeSpan.

IGeodeSerializable

• The IGeodeSerializable interface has been renamed to IDataSerializable.

.NET Session State Provider

The Native Client 10 version of the Session State Provider (SSP) only requires configuration to be set in Web.Config and the deployment of server-side functions.

C++ API Changes

The following classes have changed or are no longer present in the current release.

The following classes have changed or new in the current release.