Upgrading a Native Client Application From Version 9 to Version 10
<!– Copyright © VMware, Inc. 2022. All rights reserved. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. –>
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:
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
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
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 is now a
parameter passed in to register a given type.
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
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
Upgrading to Native Client 10 requires replacing all *Ptr types with their C++11 replacements.
For example, replace
Other adopted C++11 standards include:
- All time values now use std::chrono. For example,
- Longs and ints are now replaced with language primitives of explicit size, such as
- std container classes
- Properties use
The following Version 9 Enums are now defined as C++11 Enum classes in the Version 10 client:
GemFire Native Client Exceptions, which were implemented as macros in v9, are now classes that inherit from
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:
- PdxSerializable toData/fromData are now passed to PdxWriter/PdxReader as references
- Execution factory returns value type
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,
- In both files, parameters specifying times should include units (
- For the
cache.xmlfile, 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">
$GFCPPenvironment variable is no longer needed
enable-chunk-handler-threadnow defaults to
- Native Client 10 now supports OpenSSL
- Statistics and StatisticsFactory are no longer available
.NET API Changes
These .NET API classes have changed as follows:
- Creation was via static method
CreateCacheFactory, now created via
- Authorization implementation now is a setter on factory called
Appdomainproperty 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
- Creation was obtained via static method
PoolManager.CreateFactory, now via
int, now uses
- SetEntryIdleTimeout - was
int, now uses
- SetRegionTimeToLive - was
int, now uses
- SetRegionIdleTimeout - was
int, now uses
int, now uses
IGeodeSerializableinterface has been renamed to
.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|
|AttributesFactory||Replace with RegionAttributesFactory|
|CacheableArrayType, CacheableContainerType, CacheableKeyType||Converted to templates. See INSTALL_DIR/include/geode/CacheableBuiltins.hpp|
|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|
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.|
|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.|