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:

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 one 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.

Version 9: Removed Class Version 10: Recommended Action
Assert N/A
AttributesFactory Replace with RegionAttributesFactory
CacheableArrayType, CacheableContainerType, CacheableKeyType Converted to templates. See INSTALL_DIR/include/geode/CacheableBuiltins.hpp
DistributedSystem Used internally
EqualToSB No longer needed; use std types
GeodeTypeIds Removed from public API
HashMapOfCacheable Replace with std::hash
HashMapOfSharedBase Replace with std::hash
HashSB Replace with std::hash
HashSetOfCacheableKey Replace with std::hash
HashSetOfSharedBase Replace with std::shared_ptr<T>
HashSetT Replace with std::hash
InternalCacheTransactionManager2PC Removed from public API
Log Use LogLevel at cache creation
LogFn Use LogLevel at cache creation
LogVarargs Use LogLevel at cache creation
NullSharedBase Replace with nullptr
SelectResultsIterator Replace with ResultsCollector
SharedArrayPtr Replace with std::shared_ptr<T>
SharedBase Abstract base class no longer needed. Replace with std::shared_ptr<T>
SharedPtr Replace with std::shared_ptr<T>
SPEHelper Exception helper no longer needed after move from SharedPtr to std::shared_ptr
VectorOfCacheable std::vector<std::shared_ptr<T>>
VectorOfCacheableKey std::vector<std::shared_ptr<T>>
VectorOfSharedBase std::vector<std::shared_ptr<T>>
VectorT std::vector<T>

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

New or Renamed Class Summary of Changes
AuthenticatedView Replaces AuthenticatedCache in v9 API. Used for multi-user authentication.
DataSerializable An interface for objects whose state can be written/read as primitive types. Supersedes Serializable, which is now the superclass of all user objects in the cache that can be serialized.
DefaultResultCollector Default class that gathers results from function execution. The ResultCollector interface also changed.
LogLevel Method returns log level.
RegionAttributesFactory Replaces AttributesFactory
RegionShortcut Enum class holding all region types (PROXY, CACHING_PROXY, CACHING_PROXY_ENTRY_LRU, LOCAL_ENTRY_LRU)
TypeRegistry Class for registering a custom serializable type.