VMware GemFire® C++ Client 10€¦ · Pivotal Cloud Foundry. GemFire Compatibility The GemFire Native Client supports applications that communicate with GemFire servers. Native Client

VMwareGemFire®C++Client10.1

Rev:10.1.3

©Copyright2020VMwareInc.oritsaffiliates.AllRightsReserved.

2346

111920232527313236394142444650535758606061636972777778

TableofContents

TableofContentsVMwareGemFire®NativeClient10.1DocumentationGemFireNativeClient10.1ReleaseNotesSystemRequirementsUpgradingaNativeClientApplicationFromVersion9toVersion10InstallingtheNativeLibraryGettingStartedwiththeNativeLibraryPut/Get/RemoveExampleConfiguringaClientApplicationSystemLevelConfigurationConfiguringtheClientCacheConfiguringRegionsRegisteringInterestforEntriesRegionAttributesSerializingDataVMwareGemFire®PDXSerializationUsingthePdxSerializableAbstractClassPdxSerializableExampleRemoteQueriesContinuousQueriesSecurity:AuthenticationandEncryptionAuthenticationTLS/SSLClient-ServerCommunicationEncryptionSetUpOpenSSLStartingandstoppingtheclientandserverwithSSLinplaceFunctionExecutionTransactionsSystemPropertiesClientCacheXMLReferenceCacheInitializationFile:XMLEssentialsCacheInitializationFileElementDescriptions

©CopyrightPivotalSoftwareInc,2013-2020 2 10.1

VMwareGemFire®NativeClient10.1DocumentationPublishedJuly10,2020.

TheVMwareGemFire®NativeClientisalibrarythatprovidesaccessforC++andMicrosoft .NET™clientstoaVMwareGemFire®distributedsystem.

SeetheReleaseNotesfornewfeaturesandsupportinformationregardingthisrelease.

UpgradingaNativeClientApplicationFromVersion9toVersion10provideshelpwiththeupgradefromNativeClient9.xtoNativeClient10.x.

SeetheAPIdocsforAPIdetails:

C++APIdocs

.NETAPIdocs

TheApacheGeodecommunityhasahostofexamplesbasedonthelatestC++and.NETAPIs(https://github.com/apache/geode-native/tree/develop/examples ).

SeetheVMwareGemFire®UserGuide forinformationregardingtheserver.

®


http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/cppdocs

http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/dotnetdocs

https://github.com/apache/geode-native/tree/develop/examples

http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/gemfireman/about_gemfire.html

GemFireNativeClient10.1ReleaseNotes

What’sNewinGemFireNativeClient10.1VMwareGemFire®NativeClient10.1isbasedonApacheGeode1.11.

Version10.1includesanumberofimprovements:

SSLenhancement-supportforcertificatechaining,betterone-waySSLconsistency

CompatibilityissueswithvariousversionsofPCC

Performanceimprovements

Bugfixes.SeeIssuesResolvedinNativeClient10.1


IssuesResolvedinNativeClient10.1ThissectiondescribesissuesresolvedinVMwareGemFire®NativeClientversion10.1anditspatchreleases,beginningwiththemostrecentrelease.

IssuesResolvedinNativeClient10.1.3

GEODE-8297,GEMNC-472:Increaseddefaulttimeoutvalueforauthorizationtoaccommodatenetworkswithhigherlatency.


GEODE-7930:Endpointnamesarenolongertruncatedto99characters.TheNativeClientnowsupportsendpointnamesthatmeettheRFC2181standardof255charactersforfully-qualifieddomainnames.Thissolutionalsocorrectsaspurious“Failedtoaddendpoint”errorthatwasissuedwhen,infact,noerrorhadoccurred.


GEODE-8015,GEMNC-470:Addeddebuggingsymbolstothereleasedlibraries.TheNativeClientrelease



forWindowsnowincludesa.pdbsymbolfile.OnLinux,thesymbolsarenowembeddedinthesharedlibrary(.sofile).


GEODE-3415:AddedsupportforcertificatechainfilesinSSLconfiguration.

GEODE-7437:Enforcedrecognitionoftruststoreinone-waySSL.

GEODE-5708,GEMNC-465:Fixedanissuewithanoverly-aggressivememoryfree-upoperationinpartitionedregionsthatcausedtheputAll()operationtofailwhencalledasecondtimeduetoaclosedserverconnection.

GEODE-6576:Improvedhandlingofstaleconnectionstopartitionedregions.

GEODE-6624,GEMNC-438:Improvedhandlingofdataserializationerrorreportingbyfixingaproblemcausedbynestedexceptions.

GEODE-6800,GEMNC-448:FixedagcccompilationerrorrelatedtoCacheableFileNameobjects.

GEODE-6835,GEMNC-442:Addedretrylogictopreventspuriousserver-sideSecurityManagererrors.

GEODE-7019:Fixclosingofidleconnectionsinnativeclient.

GEODE-7061:Reducedthenumberofconnectionscreatedduringhighloadconditionswithmanythreads.

GEODE-7299:FixedamemoryleakassociatedwithPDXdataserialization.

GEODE-7316:Fixedaraceconditionthatcouldcauseaclientapptocrashonshutdown.

GEODE-7418,GEMNC-464:FixedanissuewithPDXserialization/deserializationofJSONobjects.

GEODE-7476,GEODE-7509,GEMNC-436:Fixedamemoryleakthatappearedduringrepeatedqueries.

GEODE-7783:Optimizedconnectionhandlingtoimproveperformance.


SystemRequirementsInthistopic

GemFireCompatibility

ApplicationCompatibility

.NETCompatibility

HostMachineRequirements

WindowsSupport

LinuxSupport

PCFSupport

SoftwareRequirementsforUsingSSL

TheVMwareGemFire®nativeclientprovidesaccessforC++andMicrosoft®.NET™clientstotheVMwareGemFire®distributedsystem.ItoperatesonplatformsrunningMicrosoftWindows,Linux(Intel),andPivotalCloudFoundry.

GemFireCompatibilityTheGemFireNativeClientsupportsapplicationsthatcommunicatewithGemFireservers.NativeClientversion10.1workswithPivotalGemFireversions9.0.0andlater.

ThefollowingtableshowswhichversionsoftheNativeClientarecompatiblewiththevariousversionsoftheGemFireserver.

GemFireNativeClientVersion GemFireServerVersion

GemFireNativeClient10 GemFireServer10

GemFireNativeClient10GemFireNativeClient9.1,9.2

GemFireServer9.x

GemFireNativeClient9.1GemFireNativeClient8.2

GemFireServer8.2

ApplicationCompatibilityGemFireNativeClientiscompiledusing64-bitarchitecturesforalloperatingsystems.Linkingwith32-bit


applicationsisnotsupported.

SupportedPlatforms:C++ClientTheGemFireNativeClientsupportsapplicationsthatruninthefollowingclientenvironments:

Platform Version

Linux RedHatEnterpriseLinux(RHEL)7

Linux Ubuntu16(Xenial)

WindowsDesktop 10

WindowsServer 2016

PivotalCloudFoundry PCF2.3.2+

SupportedPlatforms:.NETClient

Platform Version

WindowsDesktop 10

WindowsServer 2016

PivotalCloudFoundry PCF2.3.2+

.NETCompatibilityForWindowsapplications,aMicrosoft.NETFrameworkmustbeinstalledtosupporttheC++/CLI(CommonLanguageInfrastructure)libraryforthenativeclient.

Theclientsupports.NET4.5.2(andnewer)andVisualStudio2017(andnewer)forcompiling.NETapplicationsonWindows.Itdoesnotsupport.NETCore.Formoreinformationonthefeaturesof.NETandVisualStudioCommunityEdition2017,seetheVisualStudio2017webpage .

HostMachineRequirementsEachmachinethatrunsanativeclientmustmeetthefollowingrequirements:

AsystemclocksettothecorrecttimeandatimesynchronizationservicesuchasNetworkTimeProtocol(NTP).Correcttimestampspermitthefollowingactivities:


https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-family

Logsthatareusefulfortroubleshooting.Synchronizedtimestampsensurethatlogmessagesfromdifferenthostscanbemergedtoreproduceanaccuratechronologicalhistoryofadistributedrun.Aggregateproduct-levelandapplication-leveltimestatistics.Accuratemonitoringofthesystemwithscriptsandothertoolsthatreadthesystemstatisticsandlogfiles.

Thehostnameandhostfilesareproperlyconfiguredforthemachine.

WindowsSupportForWindowsC++applications,theGemFireNativeClientlibrary, pivotal-gemfire.dll ,requirestheMicrosoftVisualC++2017RedistributablePackage,whichyoucanfindontheVisualStudio2017webpage .Scrolldownto“RedistributablesandBuildTools”andselect“MicrosoftVisualC++RedistributableforVisualStudio2017”,andbesuretoselectthe“x64”version.InstallitonallmachinesthatwillrunyourC++application.

LinuxSupportForLinux,youcanverifythatyoumeetthenativeclientdependenciesatthelibrarylevelbyusingtheldd toolandenteringthiscommand:

$ldd$client-installdir/lib/libpivotal-gemfire.so

whereclient-installdiristhelocationinwhichyouhaveinstalledtheclient.

Thefollowinglibrariesareexternaldependenciesofthenativelibrary, libpivotal-gemfire.so .Verifythattheldd tooloutputincludesallofthese:

libdl.so.2

libm.so.6

libpthread.so.0

libc.so.6

libz.so.1

DisablingSynCookiesonLinux

ManydefaultLinuxinstallationsuseSYNcookiestoprotectthesystemagainstmaliciousattacksthat


https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-family

floodTCPSYNpackets.TheuseofSYNcookiesdramaticallyreducesnetworkbandwidth,andcanbetriggeredbyarunningVMwareGemFire®distributedsystem.

TodisableSYNcookiespermanently:

1. Editthe /etc/sysctl.conf filetoincludethefollowingline:

net.ipv4.tcp_syncookies=0

SettingthisvaluetozerodisablesSYNcookies.

2. Reload sysctl.conf :

$sysctl-p

PCFSupportPivotalCloudFoundrysupports.NETandC++nativeclientapplications.

PCFversions2.3.2andhigherincludetheMicrosoftVS2017C++RedistributableDLLs.

PCF.NETRequirements

PCF2.3.2ornewer

WindowsServer2016

.NET4.5.2ornewer

Torunyourcloudnative.NETapplicationonPCF:

1. The Pivotal.GemFire.dll mustbeinthe output folderofyour.NETproject.

2. Rebuildyourapplication.

3. FromVisualStudio,publishyourapplicationtoafilesystem.

4. Fromwithinthepublishedfilesystem,use cf push todeployyourapplicationtoPCFasyouwouldother.NETapplications.

PCFC++Requirements


PCF2.3.2ornewer

UbuntuorWindows2017stemcells

TorunyourcloudnativeC++applicationonPCF:

1. Theruntimelibraries pivotal-gemfire.dll and cryptoImpl.dll mustbeinthepathofyourC++application.

2. Use cf push todeployyourapplicationtoPCFasyouwouldotherC++applications.

SoftwareRequirementsforUsingSSLIfyouplanonusingSSLinyourVMwareGemFire®nativeclientandserverdeployment,youwillneedtodownloadandinstallOpenSSL.TheVMwareGemFire®nativeclientrequiresOpenSSLversion1.1.1.

ForWindowsplatforms,youcanuseeithertheregularortheOpenSSL“Light”version.

Inaddition,makesurethatyoursystemenvironmentvariableshavebeenconfiguredtoincludeOpenSSL.


UpgradingaNativeClientApplicationFromVersion9toVersion10GemFireNativeClientVersion10introducesbreakingchangesforVersion9applications.Updatingyourclientapplicationswillrequiremoreinterventionthanmerelyrecompiling.

Ingeneral,youwillhavebestperformanceandreliabilityifclientsandserversbothrunthelatestversionsoftheirrespectivesoftware.

GemFireserverandclientsoftwarereleasesfollowsimilarnumberingschemes,buttheyarenotreleasedinlockstep.ThefollowingdiagramillustratestheinteroperabilitybetweenrecentversionsofGemFireserversoftwareandGemFireNativeClientsoftware.

OverviewofChangesVMwareGemFire®NativeClientimprovementsandnewfeaturesinclude:

AmodernizedC++APIthatconstitutesabigstepforwardtofullysupportingC++11.

Localmemorymanagementhasbeengreatlyimproved,aswellastheadoptionofanewcachemodelthatallowsformultiplecacheobjectstoexistinagivenprocessspace.

The.NETinterfacebenefitsfromalltheenhancementsmadeintheC++interface.

TheNativeClientnowsupportsIISapplicationdomainsandPivotalCloudFoundry.

Anewarchitecturethatallowsformoreflexibleclient-sidedatamodels

Improvementstothereflection-basedAutoSerializer


ForexamplesofsourcechangesseetheNativeClient9toNativeClient10UpgradeSample .



http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/upgrade-example-cpp.html

TheseexamplesshowboththeoriginalandnewAPIusage,andmaybehelpfulasstartingpointsforupgradingyourapplicationtoNativeClient10.ToseedetailsforupgradingyourparticularAPIusagerefertotheNativeClient10APIdocumentation:

C++APIdocs

.NETAPIdocs

CompilerUpgradeUsingVersion10oftheNativeClientwithyourapplicationrequiresaC++11-compatiblecompiler.

RemovalofCacheSingletonAmajorchangeinNativeClient10isthechangefromasingleton-baseddesigntoaninstance-baseddesign.Thisgivesdevelopersgreaterprogrammingflexibility,asclientcacheinstancescanhavecompletelyindependentaccesstotheGemFiredatagrid.

Multipleclient-sideinstancesofCachedonotautomaticallyshareobjectswithoneanother.

ThecachecreationprocessinNativeClient10followsadifferentpatternandnowreturnsanobject(seeexamples).Eachalsorequiresapool.NativeClient10furthersimplifiesthecachecreationandsystemarchitecturewiththeremovalof DistributedSystem .Aninstanceof DistributedSystem isnolongerneededtomanageanapplication’s“connecting”intotheVMwareGemFire®Javaserver.ThisisnowmanagedthroughaCacheinstance.

Anoteto.NETusersoftheNativeClient:userscanpassinaninstanceoftheirauthorizationclassintotheCacheFactory( CacheFactory.SetAuthInitialize(app_auth); ).


http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/cppdocs

http://docs-gemfire-native-cpp-staging.cfapps.io/101/gemfire-native-client-cpp/dotnetdocs

SerializationInterfaceChangesTheNativeClientserializationAPIsforbothC++and.NEThavebeenchangedtomorecloselyresemblethebehavioroftheGemFireJavaclient.TheserializableAPIhasbeenrefactoredintodataserializableandPDXserializableinterfaces.Inaddition,tobeconsistentwiththeJavaServer,thenewdataserializableinterfacedoesnothavefixed ClassId properties. ClassId isnowaparameterpassedintoregisteragiventype.

C++StandardizationInNativeClient10,manyversion9utilityclasses,suchassharedpointers,havebeenreplacedbytheirequivalentsfromtheC++11standardlibrary.

OneofthebiggestchangesmadeinNativeClient10isthereplacementofcustomapache::geode::client::SharedPtr with std::shared_ptr .Thecustombaseobject apache::geode::client::SharedBase hasbeenremovedandisnolongerarequiredderivationtomakelibraryobjectsreferencecounted;insteadobjectsmaysimplybewrappedbya std::shared_ptr<> .UpgradingtoNativeClient10requiresreplacingall*PtrtypeswiththeirC++11replacements.

Forexample,replace

RegionPtrregionPtr;

with

std::shared_ptr<Region>regionPtr;

OtheradoptedC++11standardsinclude:

Alltimevaluesnowusestd::chrono.Forexample, std::chrono replaces CacheableDate

Longsandintsarenowreplacedwithlanguageprimitivesofexplicitsize,suchas int32_t andint16_t .

std:string replaces char *

stdcontainerclasses

PDXSerializable::objectSize() and DataSerializable::objectSize() return size_t

Propertiesuse std::unordered map


EnumClassesThefollowingVersion9EnumsarenowdefinedasC++11EnumclassesintheVersion10client:

CqOperation

CqState

ExpirationAction

PdxFieldTypes

ExceptionsGemFireNativeClientExceptions,whichwereimplementedasmacrosinv9,arenowclassesthatinheritfrom std::exception .

ObjectOrientedDesignPatternsNativeClient10hasadoptedmanymoreobjectorienteddesignpatterns.Forexample,the CacheFactorynowusesabuilderpatternandreturnsavalueratherthanapointer.

Otherexamplesofpattern-orientedchanges:

Replace apache::geode::client::PoolPtr withstd::shared_ptr<apache::geode::client::Pool>

Replace apache::geode::client::RegionPtr withstd::shared_ptr<apache::geode::client::Region>

Replace apache::geode::client::EntryEventPtr withstd::shared_ptr<apache::geode::client::EntryEvent>

Replace apache::geode::client::CachePtr withstd::unique_ptr<apache::geode::client::Cache>

PdxSerializabletoData/fromDataarenowpassedtoPdxWriter/PdxReaderasreferences

Executionfactoryreturnsvaluetype

Cache::createPdxInstanceFactory returnsobject

CqQuery::getCqAttributesMutator returnsvalue

Cache::createDataInput/Output returnsvalue


InitializationFilesThebestpracticeformostapplicationsistosetpropertiesandparametersprogrammatically.Forclientsthatusetheolder,file-basedscheme,thefollowingchangesapplytothesysteminitializationfiles,geode.properties and cache.xml :

Inbothfiles,parametersspecifyingtimesshouldincludeunits( s , m , h ,etc.).

Forthe cache.xml file,theschemanamespaceandlocationhavechanged.Use

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

OtherChangesThe $GFCPP environmentvariableisnolongerneeded

enable-chunk-handler-thread nowdefaultsto false andreplacesdisable-chunk-handler-thread

NativeClient10nowsupportsOpenSSL

StatisticsandStatisticsFactoryarenolongeravailable

.NETAPIChangesThese.NETAPIclasseshavechangedasfollows:

CacheFactory

Creationwasviastaticmethod CreateCacheFactory ,nowcreatedvia new

Authorizationimplementationnowisasetteronfactorycalled SetAuthInitialize

Appdomain propertyisnolongerasupportedproperty

GetAnyInstance() isnolongersupported(thereisnomoreglobalsingleton).Makemethodcallsonthespecificinstanceyouareworkingwith

PoolFactory


Creationwasobtainedviastaticmethod PoolManager.CreateFactory ,nowvia GetPoolFactorymethodon Cache

SetEntryTimeToLive -was int ,nowuses TimeSpan

SetEntryIdleTimeout-was int ,nowuses TimeSpan

SetRegionTimeToLive-was int ,nowuses TimeSpan

SetRegionIdleTimeout-was int ,nowuses TimeSpan

RegionFactory

SetEntryTimeToLive -was int ,nowuses TimeSpan .

IGeodeSerializable

The IGeodeSerializable interfacehasbeenrenamedto IDataSerializable .

.NETSessionStateProviderTheNativeClient10versionoftheSessionStateProvider(SSP)onlyrequiresconfigurationtobesetinWeb.Config andthedeploymentofserver-sidefunctions.

C++APIChangesThefollowingclasseshavechangedorarenolongerpresentinthecurrentrelease.

Version9:RemovedClass Version10:RecommendedAction

Assert N/A

AttributesFactory ReplacewithRegionAttributesFactory

CacheableArrayType,CacheableContainerType,CacheableKeyType

Convertedtotemplates.SeeINSTALL_DIR/include/geode/CacheableBuiltins.hpp

DistributedSystem Usedinternally

EqualToSB Nolongerneeded;usestdtypes

GeodeTypeIds RemovedfrompublicAPI

HashMapOfCacheable Replacewithstd::hash

HashMapOfSharedBase Replacewithstd::hash


HashSB Replacewithstd::hash

HashSetOfCacheableKey Replacewithstd::hash

HashSetOfSharedBase Replacewithstd::shared_ptr<T>

HashSetT Replacewithstd::hash

InternalCacheTransactionManager2PC RemovedfrompublicAPI

Log UseLogLevelatcachecreation

LogFn UseLogLevelatcachecreation

LogVarargs UseLogLevelatcachecreation

NullSharedBase Replacewithnullptr

SelectResultsIterator ReplacewithResultsCollector

SharedArrayPtr Replacewithstd::shared_ptr<T>

SharedBaseAbstractbaseclassnolongerneeded.Replacewithstd::shared_ptr<T>

SharedPtr Replacewithstd::shared_ptr<T>

SPEHelperExceptionhelpernolongerneededaftermovefromSharedPtrtostd::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>

Version9:RemovedClass Version10:RecommendedAction

Thefollowingclasseshavechangedornewinthecurrentrelease.

NeworRenamedClass SummaryofChanges

AuthenticatedView ReplacesAuthenticatedCacheinv9API.Usedformulti-userauthentication.

DataSerializableAninterfaceforobjectswhosestatecanbewritten/readasprimitivetypes.SupersedesSerializable,whichisnowthesuperclassofalluserobjectsinthecachethatcanbeserialized.

DefaultResultCollectorDefaultclassthatgathersresultsfromfunctionexecution.TheResultCollectorinterfacealsochanged.

LogLevel Methodreturnsloglevel.

RegionAttributesFactory ReplacesAttributesFactory


RegionShortcut Enumclassholdingallregiontypes(PROXY,CACHING_PROXY,CACHING_PROXY_ENTRY_LRU,LOCAL_ENTRY_LRU)

TypeRegistry Classforregisteringacustomserializabletype.

NeworRenamedClass SummaryofChanges


InstallingtheNativeLibraryInstallthenativeclientbyextractingthecontentsofthedistributionarchiveandsettinguptheenvironment.

InstallationPrerequisites

BeforeinstallingtheGemFirenativeclient,confirmthatyoursystemmeetsthehardwareandsoftwarerequirementsdescribedinGemFireNativeClientSystemRequirements.

CopyandUncompresstheDistributionArchive

1. Inabrowser,navigatetothePivotalGemFiredownloadpage .

2. FromtheReleases:pull-downmenu,selectthemostrecentversionofVMwareGemFire®NativeClient.

3. ExpandtheentryintheReleaseDownloadFilesdialogbox,selecttheversionthatbestsuitsyourdevelopmentplatform,anddownloadit.

4. MovethedownloadedarchivetothelocaldirectoryorfolderinwhichyouwishtoinstalltheNativeClientlibraries.Foreaseofuse,chooseawell-knownlocation:

OnLinux,/usr/localOnWindows,C:\ProgramFiles

5. Uncompressthedistributionarchive,whichmaybeaZIParchiveoracompressedtarfile(.tar.gzor.tgz).Forexample:

$unzippivotal-gemfire-nativeclient-windows-64bit-10.x.y.zip

or

$tarxvzfpivotal-gemfire-nativeclient-linux-64bit-10.x.y.tar.gz

6. Foreaseofuse,renametheresultingdirectoryto nativeclient .


https://network.pivotal.io/products/pivotal-gemfire

GettingStartedwiththeNativeLibraryInthistopic

SetUpYourDevelopmentEnvironment

EstablishAccesstoaVMwareGemFire®ClusterConnectingtotheServer

ApplicationDevelopmentWalkthrough

ProgrammingExamples

TousetheVMwareGemFire®NativeLibraryfordevelopingVMwareGemFire®clientapplications:

ObtainadistributionoftheNativelibraryandinstallitonyourdevelopmentplatform.

Setupyourdevelopmentenvironmentwiththetoolsyouneed,suchasacompilerandanOpenSSLsecuritylibrary.

EstablishaccesstoaneworexistingVMwareGemFire®cluster.

WriteyourclientapplicationusingtheVMwareGemFire®nativelibrarytointeractwiththeVMwareGemFire®server.

SetUpYourDevelopmentEnvironmentYouwillneedsomeessentialtools,suchasacompilerandalinker.YourcompilermusthaveaccesstotheNativeClientheaderfiles,andthelinkermusthaveaccesstotheNativeClientlibraries.TheheaderfilesandlibrariesarelocatedintheNativeClientinstallationdirectory.

EstablishAccesstoaVMwareGemFire®ClusterAsyoudevelopyourapplication,youwillneedaccesstoaVMwareGemFire®cluster.YourclientapplicationconnectstoaVMwareGemFire®clusterbyspecifyingtheaddress(hostnameorIPaddress)andportnumberofoneormorelocators,andthenameofaregionthatalsoexistsonthecluster.TheclientAPIestablishesapoolofthesenetworkconnectionsforyourclientapplicationtouse.

Youcanchoosewhethertousealarge,remote,production-qualitycluster;asmall,local,developmentcluster;orsomethingin-between,suchasatestingorexperimentallabinstallation.

IntheVMwareGemFire®User’sGuide,seeConfiguringandRunningaCluster andClient/ServerConfiguration forinstructionsonsettingupandstartingtheclusterforaclient/serverconfiguration.

ConnectingtotheServer

Toconnecttoaserver,yourapplicationmustfollowthesesteps:

1. Instantiatea CacheFactory ,settingcharacteristicsofinterest(forexample, log-level ).


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/getting-started/serverman/configuring/chapter_overview.html

http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/getting-started/serverman/topologies_and_comm/cs_configuration/chapter_overview.html

2. Createacacheanduseittoinstantiatea PoolFactory ,specifyingthehostnameandportfortheserverlocator.

3. Createanamedpoolofnetworkconnections.

4. Instantiatearegionofthedesiredtype(usuallyCACHING_PROXYorPROXY)andconnectitbynametoitscounterpartontheserver.

Oncetheconnectionpoolandthesharedregionareinplace,yourclientapplicationisreadytosharedatawiththeserver.

ServerConnection:C++Example

ThisexampleofconnectingtotheserveristakenfromtheC++ put-get-remove example.

Instantiatea CacheFactory andsetitscharacteristics:

autocacheFactory=CacheFactory();//instantiatecachefactorycacheFactory.set("log-level","none");//setcachelog-levelcharacteristics

Createacacheanduseittoinstantiatea PoolFactory :

autocache=cacheFactory.create();//createcacheautopoolFactory=cache.getPoolManager().createFactory();//instantiatepoolfactory

poolFactory.addLocator("localhost",10334);//addlocatortopoolfactory

Createanamedpoolofnetworkconnections,andinstantiatearegionofthedesiredtype:

autopool=poolFactory.create("pool");//createapoolcalled"pool"thatknowswheretheserverisautoregionFactory=cache.createRegionFactory(RegionShortcut::PROXY);//instantiateregionfactorywithPROXYcharacteristicsautoregion=regionFactory.setPoolName("pool").create("example_userinfo");//createaconnectiontotheregion"example_userinfo"ontheserver

SeetheVMwareGemFire®UserGuidesectionConfiguringaClient/ServerSystem formoredetails.

ApplicationDevelopmentWalkthrough

TheC++AppDevelopmentWalkthrough describeshowtosetupanativeclientdevelopmentenvironmentusingCMake.

ProgrammingExamplesTheVMwareGemFire®ClientbuildprovidesasetofprogrammingexamplestohelpyouunderstandtheclientAPI.Theexamples directorycontainsCMakefilesanda cpp subdirectorycontainingC++examples.TheWindowsbuildalsoincludesa dotnet subdirectorycontainingC#examples.

CMakefilesarelocatedateachlevelofthedirectorystructuretoallowexamplestobebuiltindividuallyoringroups.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/getting-started/serverman/topologies_and_comm/cs_configuration/setting_up_a_client_server_system.html

http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/getting-started/app-dev-walkthrough-cpp.html

Thedirectorystructureresemblesthishierarchy(someentriesareomittedforclarity):

MyProject/cmake/CMakeLists.txtexamples/BUILD-EXAMPLES.mdCMakeLists.txtCMakeLists.txt.incmake/cpp/authinitialize/continuousquery/dataserializable/functionexecution/pdxserializable/pdxserializer/putgetremove/remotequery/sslputget/transaction/dotnet/authinitialize/continuousquery/dataserializable/functionexecution/pdxautoserializer/pdxserializable/putgetremove/remotequery/sslputget/transaction/

Seethe BUILD-EXAMPLES.md filefordetailedinstructionsonbuildingandexecutingtheexamples,andreadthesourcecodetounderstandhowtheexamplesareconstructed.

SeePut/Get/RemoveExampleforsamplecodeshowingthebasicsofhowaclientapplicationconnectstoaVMwareGemFire®clusterandperformsbasicoperationsonaremoteserver.


Put/Get/RemoveExampleInthistopic

Put/Get/RemoveExampleCode

ThenativeclientreleasecontainsanexamplewrittenforC++showinghowaclientapplicationcanestablishaconnectiontoaclusterandthenusethatconnectiontoperformbasicoperationsonaremoteserver.Theexamplesarelocatedin examples/cpp/putgetremove .

Theexampleperformsasequenceofoperations,displayingsimplelogentriesastheyrun.

Toruntheexample,followtheinstructionsinthe README.md fileintheexampledirectory.

Reviewthesourcecodeintheexampledirectorytoseeexactlyhowitoperates.

Beginbyrunningascriptthatsetsuptheserver-sideenvironmentbyinvoking gfsh commandstocreatearegion,simplycalled“example_userinfo.”

Runtheexampleclientapplication,whichperformsthefollowingsteps:

ConnectstotheserverPerformsregionputoperationsusingkey/valuepairsUsesregiongettoretrievethevaluesUsesregionremovetoremovethevalues

Put/Get/RemoveExampleCodeThissectioncontainscodesnippetsshowinghighlightsoftheC++put/get/removeexample.Theyarenotintendedforcut-and-pasteexecution.Forthecompletesource,seetheexamplesourcedirectory.

TheC++examplecreatesacache,thenusesittocreateaconnectionpoolandaregionobject(ofclassRegion ).


autocacheFactory=CacheFactory();cacheFactory.set("log-level","none");autocache=cacheFactory.create();autopoolFactory=cache.getPoolManager().createFactory();

poolFactory.addLocator("localhost",10334);autopool=poolFactory.create("pool");autoregionFactory=cache.createRegionFactory(RegionShortcut::PROXY);autoregion=regionFactory.setPoolName("pool").create("example_userinfo");

Theclientthenpopulatesthedatastorewithtwokey/valuepairs.

region->put("rtimmons","RobertTimmons");region->put("scharles","SylviaCharles");

Next,theapplicationretrievesthestoredvaluesusing Get operations.

autouser1=region->get("rtimmons");autouser2=region->get("scharles");

Finally,theapplicationdeletesoneofthestoredvaluesusingthe Remove method.

if(region->existsValue("rtimmons")){std::cout<<"rtimmons'sinfonotdeleted"<<std::endl;}else{std::cout<<"rtimmons'sinfosuccessfullydeleted"<<std::endl;}


ConfiguringaClientApplicationInthistopic

ProgrammaticConfigurationvsXMLConfiguration

HighAvailabilitywithServerRedundancy

Youcanconfigureyournativeclientapplication:

Programmaticallyinyourappcode

ViaXMLfilesandpropertiesfiles(seeClientCacheXMLReference)

Throughacombinationofprogrammaticandfile-basedapproaches

Thissectiondescribesconfigurationontwolevels,thesystemlevelandthecachelevel.Systempropertysettingsdescribeyourapplication’sbehavior,whilecacheconfigurationdescribesdata.

ProgrammaticConfigurationvsXMLConfigurationProgrammaticconfigurationenablesyourclientapplicationtodynamicallyadapttochangingruntimeconditions.

Incontrast,XMLconfigurationexternalizesproperties,suchaslocatoraddressesandpoolconnectiondetails,sotheycanbechangedwithoutrequiringthatyourecompileyourapplication.

C++RegionFactoryExample

Thefollowingexamplesillustratehowtosetaregion’sexpirationtimeoutattributeprogrammaticallyandthroughXML.

Settingapropertyprogrammatically:

autoregionFactory=cache.createRegionFactory(RegionShortcut::CACHING_PROXY);autoregion=regionFactory.setRegionTimeToLive(ExpirationAction::INVALIDATE,std::chrono::seconds(120)).create("exampleRegion0");

XMLequivalent:


<regionname="exampleRegion0"refid="CACHING_PROXY"><region-attributespool-name="default"><region-time-to-live><expiration-attributestimeout="120s"action="invalidate"/></region-time-to-live></region-attributes></region>

TablesofpropertiesSeeSystemPropertiesforalistofsystempropertiesthatcanbeconfiguredprogrammaticallyorinthegeode.properties file.

HighAvailabilitywithServerRedundancyWhenredundancyisenabled,secondaryserversmaintainqueuebackupswhiletheprimaryserverpusheseventstotheclient.Iftheprimaryserverfails,oneofthesecondaryserversstepsinasprimarytoprovideuninterruptedeventmessagingtotheclient.Toconfigurehighavailability,setthesubscription-redundancy intheclient’spoolconfiguration.Thissettingindicatesthenumberofsecondaryserverstouse.SeetheVMwareGemFire®UserGuidesectionConfiguringHighlyAvailableServers formoredetails.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/configuring/serverman/developing/events/configuring_highly_available_servers.html

SystemLevelConfigurationInthistopic

AttributeDefinitionPriority

SearchPathforMultiplePropertiesFiles

DefiningPropertiesProgrammatically

Aboutthegeode.propertiesConfigurationFile

ConfigurationFileLocations

UsingtheDefaultSampleFile

ConfiguringSystemPropertiesfortheClient

RunningaClientOutoftheBox

AttributeDefinitionPriorityYoucanspecifyattributesindifferentways,whichcancauseconflictingdefinitions.Applicationscanbeconfiguredprogrammatically,andthathaspriorityoverothersettings.

Incaseanattributeisdefinedinmorethanoneplace,thefirstsourceinthislistisused:

Programmaticconfiguration

Propertiessetatthecommandline

current-working-directory/geode.properties file

native-client-installation-directory/defaultSystem/geode.properties file

defaults

The geode.properties filesandprogrammaticconfigurationareoptional.Iftheyarenotpresent,nowarningsorerrorsoccur.Fordetailsonprogrammaticconfigurationthroughthe Properties object,seeDefiningPropertiesProgrammatically.

SearchPathforMultiplePropertiesFilesTheclientandcacheserverprocessesfirstlookfortheirpropertiesfileinthenative-client-installation-directory/defaultSystem directory,thenintheworkingdirectory.


Anypropertiessetintheworkingdirectoryoverridesettingsinthenative-client-installation-directory/defaultSystem/geode.properties file.

The geode.properties fileprovidesinformationtotheclientregardingtheexpectedserverconfiguration.Propertiessetinthisfile(intheclientenvironment)donothaveanyeffectontheserveritself.Itsmainpurposeistoinformtheclientapplicationastohowtocommunicatewiththeserver.

DefiningPropertiesProgrammaticallyYoucanpassinspecificpropertiesprogrammaticallybyusinga Properties objecttodefinethenon-defaultproperties.

Example:

autosystemProps=Properties::create();systemProps->insert("statistic-archive-file","stats.gfs");systemProps->insert("cache-xml-file","./myapp-cache.xml");systemProps->insert("stacktrace-enabled","true");autocache=CacheFactory(systemProps).create();

Aboutthegeode.propertiesConfigurationFileThe geode.properties fileprovideslocalsettingsrequiredtoconnectaclienttoadistributedsystem,alongwithsettingsforlicensing,logging,andstatistics.SeeSystemProperties.

ConfigurationFileLocationsAclientlooksfora geode.properties filefirstintheworkingdirectorywheretheprocessruns,theninnative-client-installation-directory/defaultSystem .Usethe defaultSystem directorytogroupconfigurationfilesortosharethemamongprocessesformoreconvenientadministration.If geode.properties isnotfound,theprocessstartsupwiththedefaultsettings.

Forthe cache.xml cacheconfigurationfile,aclientlooksforthepathspecifiedbythe cache-xml-fileattributein geode.properties (seeSystemProperties).Ifthe cache.xml isnotfound,theprocessstartswithanunconfiguredcache.

UsingtheDefaultSampleFile


Asample geode.properties fileisincludedwiththeVMwareGemFire®nativeclientinstallationinthenative-client-installation-directory/defaultSystem directory.

Tousethisfile:

1. Copythefiletothedirectorywhereyoustarttheapplication.

2. Uncommentthelinesyouneedandeditthesettingsasshowninthisexample:

cache-xml-file=test.xml

3. Starttheapplication.

Defaultgeode.propertiesFile

#DefaultC++distributedsystemproperties#Copytocurrentdirectoryanduncommenttooverridedefaults.###Debuggingsupport,enablesstacktracesinapache::geode::client::Exception.##Thedefaultisfalse,uncommenttoenablestacktracesinexceptions.#stacktrace-enabled=true#crash-dump-enabled=true####Cacheregionconfiguration##cache-xml-file=cache.xml###Logfileconfig##log-file=gemfire_cpp.log#log-level=config#zeroindicatesusenolimit.#log-file-size-limit=0#zeroindicatesusenolimit.#log-disk-space-limit=0...

ConfiguringSystemPropertiesfortheClientThetypicalconfigurationprocedureforaclientincludesthehigh-levelstepslistedbelow.

1. Placethe geode.properties filefortheapplicationintheworkingdirectoryorin


native-client-installation-directory/defaultSystem .

2. Placethe cache.xml filefortheapplicationinthedesiredlocationandspecifyitspathusingthecache-xml-file propertyinthe geode.properties file.

3. Addotherattributestothe geode.properties fileasneededforthelocalsystemarchitecture.

RunningaClientOutoftheBoxIfyoustartaclientwithoutanyconfiguration,itusesanyattributessetprogrammaticallyplusanyhard-codeddefaults(listedinSystemProperties).Runningwiththedefaultsisaconvenientwaytolearntheoperationofthedistributedsystemandtotestwhichattributesneedtobereconfiguredforyourenvironment.

Runningbasedondefaultsisnotrecommendedforproductionsystems,asimportantcomponents,suchassecurity,mightbeoverlooked.


ConfiguringtheClientCacheClientcachesprovidetheframeworkforclientstostore,manage,anddistributeapplicationdata.

AcacheisanentrypointforaccesstoVMwareGemFire®.Throughthecache,clientsgainaccesstotheVMwareGemFire®cachingframeworkfordataloading,distribution,andmaintenance.

A Cache instanceallowsyourclienttosetgeneralparametersforcommunicationbetweenacacheandothercachesinthedistributedsystem,andtocreateandaccessanyregioninthecache.

Regionsarecreatedfrom Cache instances.Regionsprovidetheentrypointstotheinterfacesforinstancesof Region and RegionEntry .

Formoreinformationspecifictoyourclientprogramminglanguage,seetheC++ClientAPI .


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/configuring/cppdocs

ConfiguringRegionsInthistopic

ProgrammaticRegionCreation

DeclarativeRegionCreation

InvalidatingandDestroyingRegions

RegionAccess

GettingtheRegionSize

TheregionisthecorebuildingblockoftheVMwareGemFire®distributedsystem.Allcacheddataisorganizedintodataregionsandyoudoallofyourdataputs,gets,andqueryingactivitiesagainstthem.

InordertoconnecttoaVMwareGemFire®server,aclientapplicationmustdefinearegionthatcorrespondstoaregionontheserver,atleastinname.SeeDataRegions intheVMwareGemFire®UserGuidefordetailsregardingserverregions,andRegionAttributesinthisguideforclientregionconfigurationparameters.

Youcancreateregionseitherprogrammaticallyorthroughdeclarativestatementsina cache.xml file.Programmaticconfigurationisrecommended,asitkeepstheconfigurationcloseathandandeliminatesanexternaldependency.Regioncreationissubjecttoattributeconsistencychecks.

ProgrammaticRegionCreationTocreatearegion:

1. Instantiatea CacheFactory anduseittocreateacache.

2. Thecacheincludesaninstanceof PoolManager —useittocreateaconnectionpool.

3. Usecachetoinstantiatea RegionFactory anduseittocreatearegion,specifyinganydesiredattributesandanassociationwiththeconnectionpool.

C++RegionCreationExample

ThefollowingexampleillustrateshowtocreatetworegionsusingC++.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/regions/geodeman/basic_config/data_regions/chapter_overview.html

autocache=CacheFactory().create();

autoexamplePool=cache.getPoolManager().createFactory().addLocator("localhost",40404).setSubscriptionEnabled(true).create("examplePool");

autoclientRegion1=cache.createRegionFactory(RegionShortcut::PROXY).setPoolName("examplePool").create("clientRegion1");

DeclarativeRegionCreationDeclarativeregioncreationinvolvesplacingtheregion’sXMLdeclaration,withtheappropriateattributesettings,ina cache.xml filethatisloadedatcachecreation.

Liketheprogrammaticexamplesabove,thefollowingexamplecreatestworegionswithattributesandaconnectionpool:

<?xmlversion="1.0"encoding="UTF-8"?><client-cachexmlns="http://geode.apache.org/schema/cpp-cache"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://geode.apache.org/schema/cpp-cachehttp://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd"version="1.0"><poolname="examplePool"subscription-enabled="true"><serverhost="localhost"port="40404"/></pool><regionname="clientRegion1"refid="PROXY"><region-attributespool-name="examplePool"/></region><regionname="clientRegion2"refid="CACHING_PROXY"><region-attributespool-name="examplePool"><region-time-to-live><expiration-attributestimeout="120s"action="invalidate"/></region-time-to-live></region-attributes></region></client-cache>

The cache.xml filecontentsmustconformtotheXMLdescribedinthe cpp-cache-1.0.xsd fileprovidedinyourdistribution’s xsds subdirectoryandavailableonlineathttps://geode.apache.org/schema/cpp-


https://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd

cache/cpp-cache-1.0.xsd .

InvalidatingandDestroyingRegionsInvalidationmarksallentriescontainedintheregionasinvalid(withnullvalues).Destructionremovestheregionandallofitscontentsfromthecache.

Youcanexecutetheseoperationsexplicitlyinthelocalcacheinthefollowingways:

ThroughdirectAPIcallsfromtheclientusingapache::geode::client::Region:invalidateRegion()

Throughexpirationactivitiesbasedontheregion’sstatisticsandattributesettings.

Ineithercase,youcanperforminvalidationanddestructionasalocaloradistributedoperation.

Alocaloperationaffectstheregiononlyinthelocalcache.

Adistributedoperationworksfirstontheregioninthelocalcacheandthendistributestheoperationtoallothercacheswheretheregionisdefined.Thisistheproperchoicewhentheregionisnolongerneeded,orvalid,foranyapplicationinthedistributedsystem.

Iftheregionontheserverisconfiguredasapartitionedregion,itcannotbeclearedusingAPIcallsfromtheclient.

Auser-definedcachewritercanabortaregiondestroyoperation.Cachewritersaresynchronouslistenerswiththeabilitytoabortoperations.Ifacachewriterisdefinedfortheregionanywhereinthedistributedsystem,itisinvokedbeforetheregionisexplicitlydestroyed.

Whethercarriedoutexplicitlyorthroughexpirationactivities,invalidationanddestructioncauseeventnotification.

RegionAccessYoucanuse Cache::getRegion toretrieveareferencetoaspecifiedregion.

Cache::getRegion returns nullptr iftheregionisnotalreadypresentintheapplication’scache.Aserverregionmustalreadyexist.

Aregionnamecannotcontainthesecharacters:

IneligibleCharacterdescription IneligibleCharacter


whitespace spaceortab

anglebrackets <>

colon :

quote "

forwardslashandbackslash /\

pipe(verticalbar) |

questionmark ?

asterisk *

IneligibleCharacterdescription IneligibleCharacter

GettingtheRegionSizeThe Region APIprovidesa size methodthatgetsthesizeofaregion.Forclientregions,thisgivesthenumberofentriesinthelocalcache,notontheservers.Seethe Region APIdocumentationfordetails.


RegisteringInterestforEntriesForclientregions,youcanprogrammaticallyregisterinterestinentrykeysstoredonacacheserverregion.Aclientregionreceivesupdatenotificationsfromthecacheserverforthekeysofinterest.

Youcanregisterinterestforspecificentrykeysorforallkeys.Regularexpressionscanbeusedtoregisterinterestforkeyswhosestringsmatchtheexpression.Youcanalsounregisterinterestforspecifickeys,groupsofkeysbasedonregularexpressions,orforallkeys.

Note:Interestregistrationandunregistrationaresymmetricaloperations.Consequently,youcannotregisterinterestinallkeysandthenunregisterinterestinaspecificsetofkeys.Also,ifyoufirstregisterinterestinspecifickeyswith registerKeys ,thencall registerAllKeys ,youmustcall unregisterAllKeys beforespecifyinginterestinspecifickeysagain.

ClientAPIforRegisteringInterestYouregisterclientinterestthroughtheC++API.TheC++APIprovidesthe registerKeys , registerAllKeys ,andregisterRegex methods,withcorrespondingunregistrationaccomplishedusingthe unregisterKeys ,unregisterAllKeys ,and unregisterRegex methods.

The registerKeys , registerRegex and registerAllKeys methodshavetheoptiontopopulatethecachewiththeregistrationresultsfromtheserver.The registerRegex and registerAllKeys methodscanalsooptionallyreturnthecurrentlistofkeysregisteredontheserver.

SettingUpClientNotificationInadditiontotheprogrammaticfunctioncalls,toregisterinterestforaserverregionandreceiveupdatedentriesyouneedtoconfiguretheregionwiththe PROXY or CACHING_PROXYRegionShortcut setting.Theregion’spoolshouldhave subscription-enabled=true seteitherintheclientXMLorprogrammaticallyviaaCacheFactory::setSubscriptionEnabled(true) APIcall.Otherwise,whenyouregisterinterest,youwillgetanUnsupportedOperationException .

<regionname="listenerWriterLoader"refid="CACHING_PROXY">...

Allclientsthathavesubscriptionsenabledtrackanddrop(ignore)anyduplicatenotificationsreceived.Toreduceresourceusage,aclientexpirestrackedsourcesforwhichnewnotificationshavenotbeenreceivedforaconfigurableamountoftime.


NotificationSequence

Notificationsinvoke CacheListeners ofcachelessclientsinallcasesforkeysthathavebeenregisteredontheserver.Similarly,invalidatesreceivedfromtheserverinvoke CacheListeners ofcachelessclients.

Ifyouregistertoreceivenotifications,listenercallbacksareinvokedirrespectiveofwhetherthekeyisintheclientcachewhena destroy or invalidate eventisreceived.

RegisteringInterestforSpecificKeysYouregisterandunregisterinterestforspecifickeysthroughthe registerKeys and unregisterKeysfunctions.Youregisterinterestinakeyorsetofkeysbyspecifyingthekeynameusingtheprogrammaticsyntaxshowninthefollowingexample:

keys0.push_back(keyPtr1);keys1.push_back(keyPtr3);regPtr0->registerKeys(keys0);regPtr1->registerKeys(keys1);

Theprogrammaticcodesnippetinthenextexampleshowshowtounregisterinterestinspecifickeys:

regPtr0->unregisterKeys(keys0);regPtr1->unregisterKeys(keys1);

RegisteringInterestforAllKeysIftheclientregistersinterestinallkeys,theserverprovidesnotificationsforallupdatestoallkeysintheregion.Thenextexampleshowshowtoregisterinterestinallkeys:

regPtr0->registerAllKeys();regPtr1->registerAllKeys();

Thefollowingexampleshowsacodesampleforunregisteringinterestinallkeys.

regPtr0->unregisterAllKeys();regPtr1->unregisterAllKeys();


RegisteringInterestUsingRegularExpressionsThe registerRegex functionregistersinterestinaregularexpressionpattern.Theserverautomaticallysendstheclientchangesforentrieswhosekeysmatchthespecifiedpattern.

Keysmustbestringsinordertoregisterinterestusingregularexpressions.

Thefollowingexampleshowsinterestregistrationforallkeyswhosefirstfourcharactersare Key- ,followedbyanystringofcharacters.Thecharacters .* representawildcardthatmatchesanystring.

regPtr1->registerRegex("Key-.*");

Tounregisterinterestusingregularexpressions,youusethe unregisterRegex function.Thenextexampleshowshowtounregisterinterestinallkeyswhosefirstfourcharactersare Key- ,followedbyanystring(representedbythe .* wildcard).

regPtr1->unregisterRegex("Key-.*");

RegisterInterestScenarioInthisregisterinterestscenario,acachelistenerisusedwithacachelessregionthathassubscription-enabled setto true .Theclientregionisconfiguredwithcachingdisabled;clientnotificationisenabled;andacachelistenerisestablished.Theclienthasnotregisteredinterestinanykeys.

Whenavaluechangesinanotherclient,itsendstheeventtotheserver.Theserverwillnotsendtheeventtothecachelessclient,eventhough client-notification issetto true .

Toactivatethecachelistenersothecachelessregionreceivesupdates,theclientshouldexplicitlyregisterinterestinsomeorallkeysbyusingoneoftheAPIcallsforregisteringinterest.Thisway,theclientreceivesalleventsforthekeystowhichithasregisteredinterest.ThisappliestoJava-basedclientsaswellasnon-Javaclients.


RegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.

Regionattributesettingsdeterminewherethedataresides,howtheregionismanagedinmemory,andtheautomaticloading,distribution,andexpirationofregionentries.

SpecifyingRegionAttributesSpecifyregionattributesbeforecreatingtheregion.YoucandothiseitherthroughtheAPIorthroughthedeclarativeXMLfile.TheAPIincludesclassesfordefiningaregion’sattributesbeforecreationandformodifyingsomeattributesaftercreation.Fordetails,seetheAPIfor RegionShortcut , RegionAttributes ,RegionAttributesFactory ,and AttributesMutator .

RegionShortcutsVMwareGemFire®providespredefined,shortcutregionattributessettingsforyourusein RegionShortcut .Theshortcutsare:

PROXY

doesnotstoredataintheclientcache,butconnectstheregiontotheservers.

CACHING_PROXY

storesdataintheclientcacheandconnectstheregiontotheservers.

CACHING_PROXY_ENTRY_LRU

storesdataintheclientcacheandconnectstheregiontotheservers.Limitstheamountofdatastoredlocallyintheclienttoadefaultlimitof100,000entriesbyejectingtheleastrecentlyused(LRU)entries.

LOCAL

storesdataintheclientcacheanddoesnotconnecttheregiontotheservers.Thisisaclient-side-onlyregion.

LOCAL_ENTRY_LRU


storesdataintheclientcacheanddoesnotconnecttheregiontotheservers.Thisisaclient-side-onlyregion.Limitstheamountofdatastoredlocallyintheclienttoadefaultlimitof100,000entriesbyejectingtheleastrecentlyused(LRU)entries.


SerializingDataDatainyourclientapplication’sVMwareGemFire®cachemustbeserializabletobesharedwithVMwareGemFire®serversandotherVMwareGemFire®clients.VMwareGemFire®providesmultipledataserializationoptionsforstorageandtransmittalbetweenprocesses,ofwhichVMwareGemFire®PortableDataeXchange(PDX)serialization)offersthebestcombinationofversatilityandease-of-useformostapplications.

Tolearnmoreaboutotherserializationoptions,seetheDataSerializationsectionintheVMwareGemFire®UserGuide .


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/serialization/serverman/developing/data_serialization/chapter_overview.html

VMwareGemFire®PDXSerializationInthistopic

PortabilityofPDXSerializableObjects

ReducedDeserializationofSerializedObjects

DeltaPropagationwithPDXSerialization

PDXSerializationDetails

VMwareGemFire®’sPortableDataeXchange(PDX)isacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.

VMwareGemFire®C++PDXserialization:

IsinteroperablewithotherlanguagesbyVMwareGemFire®–noneedtoprogramaJava-sideimplementation

Reducesdeserializationoverheadbyprovidingdirectfieldaccessonserversofserializeddata,withoutfulldeserialization.Storesdatainnamedfieldsthatyoucanaccessindividually,toavoidthecostofdeserializingtheentiredataobject

WorkswithVMwareGemFire®deltapropagation

Forgreatercontrol,youcanspecifyindividualtreatmentfordomainobjectsusingthe PdxSerializableinterface.

PortabilityofPDXSerializableObjectsWhenyoucreatea PdxSerializable object,VMwareGemFire®storestheobject’stypeinformationinacentralregistry.Theinformationispassedbetweenpeers,betweenclientsandservers,andbetweendistributedsystems.

WhenusingPDXserialization,clientsautomaticallypassregistryinformationtoserverswhentheystoreaPdxSerializable object.Clientscanrunqueriesandfunctionsagainstthedataintheserverswithouttheserversneedingtoknowanythingaboutthestoredobjects.Oneclientcanstoredataontheservertoberetrievedbyanotherclient,withtheserverneverneedingtoknowtheobjecttype.ThismeansyoucancodeyourC++clientstomanagedatausingJavaserverswithouthavingtocreateJavaimplementationsofyourC++domainobjects.


ReducedDeserializationofSerializedObjectsTheaccessmethodsfor PdxSerializable objectsallowyoutoexaminespecificfieldsofyourdomainobjectwithoutdeserializingtheentireobject.Thiscanreducedeserializationcostssignificantly.ClientC++appscanrunqueriesandexecutefunctionsagainsttheobjectsintheservercacheswithoutdeserializingtheentireobjectontheserverside.ThequeryengineautomaticallyrecognizesPDXobjectsandusesonlythefieldsitneeds.

ClientscanexecuteJavafunctionsonserverdatathatonlyaccesspartsofthedomainobjectsbyusingPdxInstance.

Likewise,peerscanaccessjustthefieldsneededfromtheserializedobject,keepingtheobjectstoredinthecacheinserializedform.

DeltaPropagationwithPDXSerializationYoucanuseVMwareGemFire®deltapropagationwithPDXserialization.

PDXSerializationDetailsSeethefollowingsectionsfordetailsonimplementingPDXserialization:

UsingthePdxSerializableAbstractClass

PdxSerializableExample


UsingthePdxSerializableAbstractClassWhenyouwriteobjectsusingPDXserialization,theyaredistributedtotheservertierinPDXserializedform.Domainclassesneedtoinheritthe PdxSerializable abstractclasstoserializeandde-serializetheobject.

Whenyourunqueriesagainsttheobjectsontheservers,onlythefieldsyouspecifyaredeserialized.Adomainclassshouldserializeandde-serializeallitsmemberfieldsinthesameorderinits toData andfromData functions.

UsethisproceduretoprogramyourdomainobjectforPDXserializationusingthe PdxSerializable abstractclass.

1. Inyourdomainclass,implement PdxSerializable .Forexample:

classOrder:publicPdxSerializable{

2. Programthe toData functiontoserializeyourobjectasrequiredbyyourapplication.(SeemarkIdentityField inalaterstepforanoptimizationthatyoucanapplytothiscodesample.)

voidOrder::toData(PdxWriter&pdxWriter)const{pdxWriter.writeInt(ORDER_ID_KEY_,order_id_);pdxWriter.writeString(NAME_KEY_,name_);pdxWriter.writeShort(QUANTITY_KEY_,quantity_);}

IfyoualsousePDXserializationinJavaor.NETfortheobject,serializetheobjectinthesamewayforeachlanguage.Serializethesamefieldsinthesameorderandmarkthesameidentityfields.

3. Programthe fromData functiontoreadyourdatafieldsfromtheserializedformintotheobject’sfields.

voidOrder::fromData(PdxReader&pdxReader){order_id_=pdxReader.readInt(ORDER_ID_KEY_);name_=pdxReader.readString(NAME_KEY_);quantity_=pdxReader.readShort(QUANTITY_KEY_);}

Inyour fromData implementation,usethesamenameasyoudidin toData andcallthereadoperationsinthesameorderasyoucalledthewriteoperationsinyour toData implementation.


4. Optionally,programyourdomainobject’s hashCode andequalityfunctions.Whenyoudoso,youcanoptimizethosefunctionsbyspecifyingtheidentityfieldstobeusedincomparisons.

Markedidentityfieldsareusedtogeneratethe hashCode andequalityfunctionsofPdxInstance,sotheidentityfieldsshouldthemselveseitherbeprimitives,orimplementhashCode and equals .The markIdentityField functionindicatesthatthegivenfieldnameshouldbeincludedinhashCode andequalitychecksofthisobjectonaserver.Invokethe markIdentityField functiondirectlyaftertheidentityfield’s write* function.Ifnofieldsaresetasidentityfields,thenallfieldswillbeusedin hashCode andequalitychecks,somarkingidentityfieldsimprovestheefficiencyofhashingandequalityoperations.Itisimportantthatthefieldsusedbyyourequalityfunctionand hashCode implementationsarethesamefieldsthatyoumarkasidentityfields.

Thiscodesampleexpandsthesamplefromthedescriptionofthe toData function,above,toillustratetheuseof markIdentityField :

voidOrder::toData(PdxWriter&pdxWriter)const{pdxWriter.writeInt(ORDER_ID_KEY_,order_id_);pdxWriter.markIdentityField(ORDER_ID_KEY_);

pdxWriter.writeString(NAME_KEY_,name_);pdxWriter.markIdentityField(NAME_KEY_);

pdxWriter.writeShort(QUANTITY_KEY_,quantity_);pdxWriter.markIdentityField(QUANTITY_KEY_);}


PdxSerializableExampleThenativeclientreleasecontainsanexampleshowinghowaclientapplicationcanregisterforserializationofcustomobjectsusingtheC++PdxSerializableabstractclass.

Theexampleislocatedin examples/cpp/pdxserializable .

Theexampledefinestheserializableclass, Orders ,includingitsserializationanddeserializationmethodsanditsfactorymethod.Oncethesepiecesareinplace,executionissimple:themainroutineoftheexampleregisterstheserializableclassthenperformssomeputandgetoperations.

Execution


Toruntheexample,followtheinstructionsintheREADME.mdfileintheexampledirectory.


Beginbyrunningascriptthatsetsuptheserver-sideenvironmentbyinvoking gfsh commandstocreatearegion,alocator,andaserver.

Runtheexampleclientapplication,whichperformsthefollowingsteps:

ConnectstotheserverRegistersthePdxSerializableclassCreatesordersStoresordersRetrievesorders

C++Example

ThissectioncontainscodesnippetsshowinghighlightsoftheC++PdxSerialiableexample.Theyarenotintendedforcut-and-pasteexecution.Forthecompletesource,seetheexamplesourcedirectory.

TheC++exampledefinesaPdxSerializableclasscalled Order thatinheritsfromthe PdxSerializableabstractclass.An Order objectcontainsthreefields:


aninteger order_id

astring name

ashort-int quantity

FromOrder.hpp:

classOrder:publicPdxSerializable{public:...

private:int32_torder_id_;std::stringname_;int16_tquantity_;};

Usingthe PdxSerializable readandwritemethods,the Order classdefines fromData() and toData()methodsthatperformthedeserializationandserializationoperations,respectively,andthecreateDeserializable() factorymethod:

FromOrder.cpp:

voidOrder::fromData(PdxReader&pdxReader){order_id_=pdxReader.readInt(ORDER_ID_KEY_);name_=pdxReader.readString(NAME_KEY_);quantity_=pdxReader.readShort(QUANTITY_KEY_);}

voidOrder::toData(PdxWriter&pdxWriter)const{pdxWriter.writeInt(ORDER_ID_KEY_,order_id_);pdxWriter.markIdentityField(ORDER_ID_KEY_);

pdxWriter.writeString(NAME_KEY_,name_);pdxWriter.markIdentityField(NAME_KEY_);

pdxWriter.writeShort(QUANTITY_KEY_,quantity_);pdxWriter.markIdentityField(QUANTITY_KEY_);}

...

std::shared_ptr<PdxSerializable>Order::createDeserializable(){returnstd::make_shared<Order>();}


TheC++examplemainlinecreatesacache,thenusesittocreateaconnectionpoolandaregionobject(ofclass Region ).

autocacheFactory=CacheFactory();cacheFactory.set("log-level","none");autocache=cacheFactory.create();autopoolFactory=cache.getPoolManager().createFactory();

poolFactory.addLocator("localhost",10334);autopool=poolFactory.create("pool");autoregionFactory=cache.createRegionFactory(RegionShortcut::PROXY);autoregion=regionFactory.setPoolName("pool").create("custom_orders");

TheclientregistersthePdxSerializableclassthatwascreatedinOrders.cpp:

cache.getTypeRegistry().registerPdxType(Order::createDeserializable);

Theclienttheninstantiatesandstorestwo Order objects:

autoorder1=std::make_shared<Order>(1,"productx",23);autoorder2=std::make_shared<Order>(2,"producty",37);

region->put("Customer1",order1);region->put("Customer2",order2);

Next,theapplicationretrievesthestoredvalues,inonecaseextractingthefieldsdefinedintheserializationcode:

if(autoorder1retrieved=std::dynamic_pointer_cast<Order>(region->get("Customer1"))){std::cout<<"OrderID:"<<order1retrieved->getOrderId()<<std::endl;std::cout<<"ProductName:"<<order1retrieved->getName()<<std::endl;std::cout<<"Quantity:"<<order1retrieved->getQuantity()<<std::endl;}else{std::cout<<"Order1notfound."<<std::endl;}

Theapplicationretrievesthesecondobjectanddisplaysitwithoutextractingtheseparatefields:


if(region->existsValue("rtimmons")){std::cout<<"rtimmons'sinfonotdeleted"<<std::endl;}else{std::cout<<"rtimmons'sinfosuccessfullydeleted"<<std::endl;}

Finally,theapplicationclosesthecache:

cache.close();


RemoteQueriesInthistopic

RemoteQueryBasicsQuerylanguage:OQL

CreatingIndexes

RemoteQueryAPIQuery

ExecutingaQueryfromtheClient

C++QueryExample

UsetheremotequeryAPItoqueryyourcacheddatastoredonacacheserver.

RemoteQueryBasicsQueriesareevaluatedandexecutedonthecacheserver,andtheresultsarereturnedtotheclient.Youcanoptimizeyourqueriesbydefiningindexesonthecacheserver.

Queryingandindexingoperateonlyonremotecacheservercontents.

Querylanguage:OQL

VMwareGemFire®providesaSQL-likequeryinglanguagecalledOQLthatallowsyoutoaccessdatastoredinVMwareGemFire®regions.OQLisverysimilartoSQL,butOQLallowsyoutoquerycomplexobjects,objectattributes,andmethods.

Inthecontextofaquery,specifythenameofaregionbyitsfullpath,startingwithaslash( / ).

Thequerylanguagesupportsdrillingdownintonestedobjectstructures.NesteddatacollectionscanbeexplicitlyreferencedintheFROMclauseofaquery.

Aqueryexecutionreturnsitsresultsaseithera ResultSet ora StructSet .

QuerylanguagefeaturesandgrammararedescribedintheVMwareGemFire®manualatQuerying .

CreatingIndexes


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/geodeman/developing/querying_basics/chapter_overview.html

Indexescanprovidesignificantperformancegainsforqueryexecution.Youcreateandmaintainindexesonthecacheserver.Fordetailedinformationaboutworkingwithindexesconfiguredonacacheserver,seeWorkingwithIndexes intheserver’sdocumentation.

RemoteQueryAPIThissectiongivesageneraloverviewoftheinterfacesandclassesthatareprovidedbythequerypackageAPI.

Query

Youmustcreatea Query objectforeachnewquery.The Query interfaceprovidesmethodsformanagingthecompilationandexecutionofqueries,andforretrievinganexistingquerystring.

A Query isobtainedfroma QueryService ,whichisobtainedfromoneoftwosources:

Tocreatea Query thatoperatesontheVMwareGemFire®server,useapache::geode::client::Pool::getQueryService() toinstantiatea QueryService obtainedfroma Pool .

Tocreatea Query thatoperatesonyourapplication’slocalcache,useapache::geode::client::Cache::getQueryService() toinstantiatea QueryService obtainedfroma Cache .

ExecutingaQueryfromtheClient

Theessentialstepstocreateandexecuteaqueryare:

1. Createaninstanceofthe QueryService class.IfyouareusingthepoolAPI(recommended),youshouldobtainthe QueryService fromthepool.

2. Createa Query instancethatiscompatiblewiththeOQLspecification.

3. Usethe Query.execute() methodtosubmitthequerystringtothecacheserver.Theserverremotelyevaluatesthequerystringandreturnstheresultstotheclient.

4. Iteratethroughthereturnedobjects.

C++QueryExample

TheseC++codeexcerptsarefromthe examples/cpp/remotequery exampleincludedinyourclientdistribution.Seetheexampleforfullcontext.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/geodeman/developing/query_index/query_index.html

Followingthestepslistedabove,

1. Obtaina QueryService objectfromtheconnectionpool:

std::shared_ptr<QueryService>queryService=nullptr;queryService=pool->getQueryService();

2. Createa Query objectbycalling QueryService.newQuery() ,specifyingyourOQLqueryasastringparameter:

autoquery=queryService->newQuery("SELECT*FROM/custom_ordersWHEREquantity>30");

3. Executethequery.Collectthequeryoutput,returnedaseithera ResultSet ora StructSet ,anditeratethroughtheresults:

autoqueryResults=query->execute();

for(auto&&value:*queryResults){auto&&order=std::dynamic_pointer_cast<Order>(value);std::cout<<order->toString()<<std::endl;}


ContinuousQueriesInthistopic

ContinuousQueryBasics

TypicalContinuousQueryLifecycle

ExecutingaContinuousQueryfromtheClientC++ContinuousQueryExample

TheC++and.NETclientscaninitiatequeriesthatrunontheVMwareGemFire®cacheserverandnotifytheclientwhenthequeryresultshavechanged.Fordetailsontheserver-sidesetupforcontinuousqueries,seeHowContinuousQueryingWorks intheVMwareGemFire®UserGuide.

ContinuousQueryBasicsContinuousqueryingprovidesthefollowingfeatures:

StandardVMwareGemFire®nativeclientquerysyntaxandsemantics.Continuousqueriesareexpressedinthesamelanguageusedforothernativeclientqueries.SeeRemoteQueries.

StandardVMwareGemFire®events-basedmanagementofCQevents.TheeventhandlingusedtoprocessCQeventsisbasedonthestandardVMwareGemFire®eventhandlingframework.

Completeintegrationwiththeclient/serverarchitecture.CQfunctionalityusesexistingserver-to-clientmessagingmechanismstosendevents.Alltuningofyourserver-to-clientmessagingalsotunesthemessagingofyourCQevents.IfyoursystemisconfiguredforhighavailabilitythenyourCQsarehighlyavailable,withseamlessfailoverprovidedincaseofserverfailure(seeHighAvailabilityforClient-to-ServerCommunication ).Ifyourclientsaredurable,youcanalsodefineanyofyourCQsasdurable(seeDurableClientMessaging ).

Interestcriteriabasedondatavalues.Continuousqueriesarerunagainsttheregion’sentryvalues.ComparethistoregisterinterestbyreviewingRegisteringInterestforEntries.

Activequeryexecution.Onceinitialized,thequeriesoperateonnewevents.Eventsthatchangethequeryresultaresenttotheclientimmediately.

TypicalContinuousQueryLifecycle1. TheclientcreatestheCQ.Thissetsupeverythingforrunningthequeryandprovidestheclientwith

a CqQuery object,butdoesnotexecutetheCQ.Atthispoint,thequeryisina STOPPED state,


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/serverman/developing/continuous_querying/how_continuous_querying_works.html

http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/preserving-data/high-availability-client-server.html

http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/preserving-data/durable-client-messaging.html

readytobeclosedorrun.

2. TheclientinitiatestheCQwithanAPIcalltooneofthe CqQueryexecute* methods.Thisputsthequeryintoa RUNNING stateontheclientandontheserver.Theserverremotelyevaluatesthequerystring,andoptionallyreturnstheresultstotheclient. CqQueryexecute* methodsinclude:

CqQuery.execute()

CqQuery.executeWithInitialResults()

3. ACQListenerwaitsforevents.Whenitreceivesevents,ittakesactionaccordinglywiththedataintheCqEvent.

4. TheCQisclosedbyaclientcallto CqQuery.close .Thisde-allocatesallresourcesinusefortheCQontheclientandserver.Atthispoint,thecyclecouldbeginagainwiththecreationofanew CqQuery

instance.

ExecutingaContinuousQueryfromtheClientTheessentialstepstocreateandexecuteacontinuousqueryare:

1. Createaninstanceofthe QueryService class.IfyouareusingthepoolAPI(recommended),youshouldobtainthe QueryService fromthepool.

2. DefineaCQListener(a CqListener )tofieldeventssentfromtheserver.

3. Useoneofthe CqQuery execute* methodstosubmitthequerystringtothecacheserver.

4. Theserverremotelyevaluatesthequerystring,thenmonitorsthoseresultsandnotifiestheclientiftheychange.

5. Theclientlistensforchangesthatmatchthequerypredicate.

6. Iteratethroughthereturnedobjects.

7. Whenfinished,closedownthecontinuousquery.

C++ContinuousQueryExample

TheseC++codeexcerptsarefromthe examples/cpp/continuousquery exampleincludedinyourclientdistribution.Seetheexampleforfullcontext.


Followingthestepslistedabove,

1. Createaqueryservice:

autoqueryService=pool->getQueryService();

2. DefineaCqListener:

classMyCqListener:publicCqListener{

3. CreateaninstanceofyourCqListenerandinsertitintoaCQattributesobject:

CqAttributesFactorycqFactory;

autocqListener=std::make_shared<MyCqListener>();

cqFactory.addCqListener(cqListener);autocqAttributes=cqFactory.create();

4. CreateaContinuousQueryusingthequeryserviceandtheCQattributes:

autoquery=queryService->newCq("MyCq","SELECT*FROM/custom_orderscWHEREc.quantity>30",cqAttributes);

5. Executethequery:

query->execute();

6. Waitforeventsanddosomethingwiththem.


/*ExcerptfromtheCqListener*/

/*DetermineOperationType*/switch(cqEvent.getQueryOperation()){caseCqOperation::OP_TYPE_CREATE:opStr="CREATE";break;caseCqOperation::OP_TYPE_UPDATE:opStr="UPDATE";break;caseCqOperation::OP_TYPE_DESTROY:opStr="DESTROY";break;default:break;}

...

/*TakeactionbasedonOPType*/

7. Whenfinished,closeupshop.

query->execute();

...(respondtoeventsastheyarrive)

query->stop();query->close();

cache.close();


Security:AuthenticationandEncryptionMostsecurityconfigurationtakesplaceontheVMwareGemFire®server.Theserver’ssecurityframeworkauthenticatesclientsastheyconnecttoacacheserverandauthorizesclientcacheoperationsusingdeveloper-providedimplementationsforauthenticationandauthorization.

Foranexplanationoftheserver-sideimplementationofsecurityfeatures,seeSecurity intheVMwareGemFire®UserGuide.

ANativeClientapplicationmustaddresstwosecurityconcernswhenconnectingtoaVMwareGemFire®server:

AuthenticationTheClientmustsubmititsauthenticationcredentialstotheserverusingthedeveloper-providedauthenticationimplementationexpectedbytheserver.

TLS/SSLClient/ServerCommunicationEncryptionCommunicationbetweenclientandservershouldbeencryptedsoauthenticationcredentialsandothertransmissionscannotbeviewedbythird-parties.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/security/geodeman/managing/security/chapter_overview.html

AuthenticationAclientisauthenticatedwhenitconnectswithvalidcredentialstoaVMwareGemFire®cacheserverthatisconfiguredwiththeclientauthenticationcallback.Fordetailsontheserver’sroleinauthenticationandwhatitexpectsfromtheclient,seeImplementingAuthentication intheVMwareGemFire®UserGuide.

Inyourapplication,authenticationcredentialsmustbesetwhencreatingthecache.Inpractice,thismeanssettingtheauthenticationcredentialswhenyoucreatetheCacheFactory.

C++AuthenticationExample

InthisC++authenticationexample,the CacheFactory creationprocesssetstheauthenticationcallback:

autocacheFactory=CacheFactory(config);autoauthInitialize=std::make_shared<UserPasswordAuthInit>();cacheFactory.set("log-level","none");cacheFactory.setAuthInitialize(authInitialize);

Credentialsareimplementedinthe getCredentials memberfunctionofthe AuthInitialize abstractclass.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/security/geodeman/managing/security/implementing_authentication.html

classUserPasswordAuthInit:publicAuthInitialize{public:UserPasswordAuthInit()=default;

~UserPasswordAuthInit()noexceptoverride=default;

std::shared_ptr<Properties>getCredentials(conststd::shared_ptr<Properties>&securityprops,conststd::string&)override{std::shared_ptr<Cacheable>userName;if(securityprops==nullptr||(userName=securityprops->find(SECURITY_USERNAME))==nullptr){throwAuthenticationFailedException("UserPasswordAuthInit:username""property[SECURITY_USERNAME]notset.");}

autocredentials=Properties::create();credentials->insert(SECURITY_USERNAME,userName->toString().c_str());autopasswd=securityprops->find(SECURITY_PASSWORD);if(passwd==nullptr){passwd=CacheableString::create("");}credentials->insert(SECURITY_PASSWORD,passwd->value().c_str());returncredentials;}

voidclose()override{return;}};


TLS/SSLClient-ServerCommunicationEncryptionThissectiondescribeshowtoimplementTLS-basedcommunicationbetweenyourclientsandserversusingtheOpenSSLencryptionutility.WhenconfiguringTLS/SSLsecurityforyourclient,youmayfindithelpfultorefertoTheSSLsectionoftheVMwareGemFire®UserGuide .

SetUpOpenSSL

Theopen-sourceOpenSSLtoolkitprovidesafull-strengthgeneralpurposecryptographylibraryforencryptingclient-servercommunications.

DownloadandinstallOpenSSL1.1.1foryourspecificoperatingsystem.

NotesforWindowsusers:

ForWindowsplatforms,youcanuseeithertheregularorthe“Light”versionofSSL.

Usea64-bitimplementationofOpenSSL.

IfyouuseCygwin,donotusetheOpenSSLlibrarythatcomeswithCygwin,whichisbuiltwithcygwin.dll asadependency.Instead,downloadafreshcopyfromOpenSSL.

FormanyWindowsapplications,themostconvenientwaytoinstallOpenSSListouse choco (seechocolatey.org )toinstallthe“Light”versionofOpenSSL.

Step1.CreatekeystoresTheVMwareGemFire®serverrequireskeysandkeystoresintheJavaKeyStore(JKS)formatwhilethenativeclientrequiresthemintheclearPEMformat.Thusyouneedtobeabletogenerateprivate/publickeypairsineitherformatandconvertbetweenthetwousingthe keytool utilityandthe opensslcommand.

Step2.EnableSSLontheserverandontheclient1. Ontheserver,enableSSLforthe locator and server components,astheSSL-enabledclientmust

beabletocommunicatewithbothlocatorandservercomponents.

2. Ontheclient,set ssl-enabled to true .

3. Ontheclient,set ssl-keystore and ssl-truststore topointtoyourkeystorefiles.Pathstothekeystoreandtruststorearelocaltotheclient.SeeSecurity-RelatedSystemProperties foradescriptionof


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/security/serverman/managing/security/ssl_overview.html

https://chocolatey.org/packages/OpenSSL.Light

http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/security/security-systemprops.html#security

theseproperties.

StartingandstoppingtheclientandserverwithSSLinplace

Beforeyoustartandstoptheclientandserver,makesureyouconfigurethenativeclientwiththeSSLpropertiesasdescribedandwiththeserversorlocatorsspecifiedasusual.

Specifically,ensurethat:

TheOpenSSLandVMwareGemFire®DLLsareintherightenvironmentvariablesforyoursystem:PATH forWindows,and LD_LIBRARY_PATH forUnix.

Youhavegeneratedthekeysandkeystores.

Youhavesetthesystemproperties.

FordetailsonstoppingandstartinglocatorsandcacheserverswithSSL,seeStartingUpandShuttingDownYourSystem .

TheVMwareGemFire®Native’slibcryptoImplfoundin/libmustbelinkedatcompiletime.ThisbinaryisusedtointeractwithOpenSSL.LinklibcryptoImpl,nativeclient,andyourapplicationcode.Wehighlyrecommendusingcmake.

Examplelocatorstartcommand

EnsurethatallrequiredSSLpropertiesareconfiguredinyourserver’s geode.properties file.Thenstartyourlocatorasfollows:

gfsh>startlocator--name=my_locator--port=12345--dir=.\--security-properties-file=/path/to/your/geode.properties

Examplelocatorstopcommand

gfsh>stoplocator--port=12345\--security-properties-file=/path/to/your/geode.properties

Exampleserverstartcommand

Again,ensurethatallrequiredSSLpropertiesareconfiguredin geode.properties .Thenstarttheserverwith:


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/security/geodeman/configuring/running/starting_up_shutting_down.html

gfsh>startserver--name=my_server--locators=hostname[12345]\--cache-xml-file=server.xml--log-level=fine\--security-properties-file=/path/to/your/geode.properties

Exampleserverstopcommand

gfsh>stopserver--name=my_server


FunctionExecutionInthistopic

Server-sideRequirements

Client-sideRequirements

HowFunctionsExecute

ProcessingFunctionResults

FunctionExecutionExampleC++Example

Aclientcaninvokeaserver-residentfunction,withparameters,andcancollectandoperateonthereturnedresults.

Server-sideRequirementsTobecallablefromyourclient,afunctionmustbe

residentontheserver,and

registeredasavailableforclientaccess.

SeeExecutingaFunctioninVMwareGemFire® intheVMwareGemFire®UserGuidefordetailsonhowtowriteandregisterserver-residentfunctions.

Client-sideRequirementsTheclientmustconnecttotheserverthroughaconnectionpoolinordertoinvokeaserver-sidefunction.

HowFunctionsExecute1. Thecallingclientapplicationrunsthe execute methodonthe Execution object.Thefunction

mustalreadyberegisteredontheservers.

2. Thefunctionisinvokedontheserverswhereitneedstorun.TheserversaredeterminedbytheFunctionService on* methodcalls,regionconfiguration,andanyfilters.

3. Ifthefunctionhasresults,theresultisreturnedina ResultCollector object.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/serverman/developing/function_exec/function_execution.html

4. Theclientcollectsresultsusingthe ResultCollector.getResult() method.

Ineveryclientwhereyouwanttoexecutethefunctionandprocesstheresults:

Useoneofthe FunctionService on* methodstocreatean Execution object.The on* methods,onRegion , onServer and onServers ,definethehighestlevelwherethefunctionisrun.

Ifyouuse onRegion youcanfurthernarrowyourrunscopebysettingkeyfilters.

Afunctionrunusing onRegion isadatadependentfunction–othersaredata-independentfunctions.

Youcanrunadatadependentfunctionagainstpartitionedandcolocatedpartitionedregions.Fromtheclient,providetheappropriatekeysetstothefunctioncall.

The Execution objectallowsyoutocustomizetheinvocationby:

Providingasetofdatakeysto withFilter tonarrowtheexecutionscope.ThisworksonlyforonRegion Executionobjects(data-dependentfunctions).Providingfunctionargumentsto withArgs .Definingacustom ResultCollector for withCollector .

Callthe Execution.execute() methodtorunthefunction.

ProcessingFunctionResultsTogettheresultsfromthefunctionintheclientapp,usetheresultcollectorreturnedfromthefunctionexecution.The getResult methodsofthedefaultresultcollectorblockuntilallresultsarereceived,thenreturnthefullresultset.

Theclientcanusethedefaultresultcollector.Iftheclientneedsspecialresultshandling,codeacustomResultsCollector implementationtoreplacethedefault.Usethe Execution::withCollector methodtospecifythecustomcollector.Tohandletheresultsinacustommanner:

1. Writeaclassthatimplementsthe ResultCollector interfacetohandletheresultsinacustommanner.Themethodsareoftwotypes:onehandlesdataandinformationfromVMwareGemFire®andpopulatestheresultsset,whiletheotherreturnsthecompiledresultstothecallingapplication:

addResult iscalledwhenresultsarrivefromthe Function methods.Use addResult toaddasingleresulttotheResultCollector.endResults iscalledtosignaltheendofallresultsfromthefunctionexecution.getResult isavailabletoyourexecutingapplication(theonethatcallsExecution.execute )toretrievetheresults.Thismayblockuntilallresultsareavailable.clearResults iscalledtoclearpartialresultsfromtheresultscollector.Thisisusedonlyfor


highlyavailable onRegion functionswherethecallingapplicationwaitsfortheresults.Ifthecallfails,beforeVMwareGemFire®retriestheexecution,itcalls clearResults toreadytheinstanceforacleansetofresults.

2. Usethe Execution objectinyourexecutingmembertocall withCollector ,passingyourcustomcollector.

FunctionExecutionExampleThenativeclientreleasecontainsexamplesoffunctionexecutionin ../examples/cpp/functionexecution .

Theexamplebeginswithaserver-sidescriptthatruns gfsh commandstocreatearegion,simplycalled“partition_region”.

ThefunctionispreloadedwithaJARfilecontainingtheserver-sideJavafunctioncode.

Thefunction,called“ExampleMultiGetFunction”,isdefinedinthe examples/utilities directoryofyourdistribution.Asitsinputparameter,thefunctiontakesanarrayofkeys,thenperformsa get oneachkeyandreturnsanarraycontainingtheresults.

Thefunctiondoesnotloadvaluesintothedatastore.Thatisaseparateoperation,performedintheseexamplesbytheclient,anddoesnotinvolvetheserver-sidefunction.

Asprerequisites,theclientcodemustbeawareoftheconnectiontotheserver,thenameofthefunction,andtheexpectedtype/formatoftheinputparameterandreturnvalue.

Theclient:

createsanexecutionobject

providestheexecutionobjectwithapopulatedinputparameterarray

invokestheobject’sexecutemethodtoinvoketheserver-sidefunction

Iftheclientexpectsresults,itmustcreatearesultobject.The.NETexampleusesabuilt-inresultcollector( IResultCollector.getResults() )toretrievethefunctionresults.

Theexamplecreatesaresultvariabletoholdtheresultsfromthecollector.

C++Example

ThissectioncontainscodesnippetsshowinghighlightsoftheC++functionexecutionexample.Theyarenotintendedforcut-and-pasteexecution.Forthecompletesource,seetheexamplesourcedirectory.


TheC++examplecreatesacache.

CachesetupCache(){returnCacheFactory().set("log-level","none").create();}

Theexampleclientusesthecachetocreateaconnectionpool,

voidcreatePool(constCache&cache){autopool=cache.getPoolManager().createFactory().addServer("localhost",EXAMPLE_SERVER_PORT).create("pool");}

Then,usingthatpool,theclientcreatesaregionwiththesamecharacteristicsandnameastheserver-sideregion( partition_region ).

std::shared_ptr<Region>createRegion(Cache&cache){autoregionFactory=cache.createRegionFactory(RegionShortcut::PROXY);autoregion=regionFactory.setPoolName("pool").create("partition_region");

returnregion;}

Thesampleclientpopulatestheserver’sdatastorewithvalues,usingtheAPIandsomesamplekey-valuepairs.

voidpopulateRegion(conststd::shared_ptr<Region>&region){for(inti=0;i<keys.size();i++){region->put(keys[i],values[i]);}}

Asconfirmationthatthedatahasbeenstored,thesampleclientusestheAPItoretrievethevaluesandwritethemtotheconsole.Thisisdonewithoutreferencetotheserver-sideexamplefunction.


std::shared_ptr<CacheableVector>populateArguments(){autoarguments=CacheableVector::create();for(inti=0;i<keys.size();i++){arguments->push_back(CacheableKey::create(keys[i]));}returnarguments;}

Next,theclientretrievesthosesamevaluesusingtheserver-sideexamplefunction.Theclientcodecreatestheinputparameter,anarrayofkeyswhosevaluesaretoberetrieved.

std::vector<std::string>executeFunctionOnServer(conststd::shared_ptr<Region>region,conststd::shared_ptr<CacheableVector>arguments){std::vector<std::string>resultList;

Theclientcreatesanexecutionobjectusing Client.FunctionService.OnRegion andspecifyingtheregion.

autofunctionService=FunctionService::onServer(region->getRegionService());

Theclientthencallstheserversidefunctionwithitsinputargumentsandstorestheresultsinavector.

if(autoexecuteFunctionResult=functionService.withArgs(arguments).execute(getFuncIName)->getResult()){for(auto&arrayList:*executeFunctionResult){for(auto&cachedString:*std::dynamic_pointer_cast<CacheableArrayList>(arrayList)){resultList.push_back(std::dynamic_pointer_cast<CacheableString>(cachedString)->value());}}}else{std::cout<<"getexecuteFunctionResultisNULL\n";}

returnresultList;}

Itthenloopsthroughtheresultsvectorandprintstheretrievedvalues.

voidprintResults(conststd::vector<std::string>&resultList){std::cout<<"Resultcount="<<resultList.size()<<std::endl<<std::endl;inti=0;for(auto&cachedString:resultList){std::cout<<"\tResult["<<i<<"]="<<cachedString<<std::endl;++i;}



TransactionsInthistopic

NativeClientTransactionAPIs

RunningNativeClientTransactions

ClientTransactionExamplesC++Example

TheNativeClientAPIrunstransactionsontheserverasiftheywerelocaltotheclientapplication.Thus,thekeytorunningclienttransactionsliesinmakingsuretheserverisproperlyconfiguredandprogrammed.ForcompleteinformationabouthowtransactionsareconductedontheVMwareGemFire®server,seetheTransactionssectionoftheVMwareGemFire®UserGuide .

NativeClientTransactionAPIsTheAPIfordistributedtransactionshasthefamiliarrelationaldatabasemethods, begin , commit ,androllback .TherearealsoAPIsavailabletosuspendandresumetransactions.

TheC++classesforexecutingtransactionsare:

apache.geode.client.CacheTransactionManager

apache.geode.client.TransactionId

RunningNativeClientTransactionsThesyntaxforwritingclienttransactionsisthesameaswithserverorpeertransactions,butwhenaclientperformsatransaction,thetransactionisdelegatedtoaserverthatbrokersthetransaction.

Starteachtransactionwitha begin operation,andendthetransactionwitha commit ora rollback .

Tomaintaincacheconsistency,thelocalclientcacheisnotusedduringatransaction.Whenthetransactioncompletesorissuspended,localcacheusageisreinstated.

Ifthetransactionrunsonserverregionsthatareamixofpartitionedandreplicatedregions,performthefirsttransactionoperationonapartitionedregion.Thissetstheserverdatahostfortheentiretransaction.IfyouareusingPRsingle-hop,single-hopwillbeappliedasusualtothisfirstoperation.


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/geodeman/developing/transactions/chapter_overview.html

Inadditiontothefailureconditionscommontoalltransactions,clienttransactionscanalsofailifthetransactiondelegatefails.Ifthedelegateperformingthetransactionfails,thetransactioncodethrowsaTransactionException .

ClientTransactionExamplesThenativeclientreleasecontainsatransactionexamplein ../examples/cpp/transaction .


Torunanexample,followtheinstructionsinthe README.md fileintheexampledirectory.


Youbeginbyrunningascriptthatsetsuptheserver-sideenvironmentbyinvoking gfsh commandstocreatearegion,simplycalled“exampleRegion.”

Youruntheexampleclientapplication,whichperformsthefollowingsteps:

ConnectstotheserverBeginsatransactionPerformssome put operationsCommitsthetransaction

Forthisexample,thetransactioncodehasthesecharacteristics:

Tointroducethepossibilityoffailure,valuesarerandomizedfrom0to9,andthe0valuesaretreatedasunsuccessful.Thetransactionisretrieduntilitsucceeds.Incasethetransactionrepeatedlyfails,theretryloopusesacountertosetalimitof5retries.

C++Example

ThissectioncontainscodesnippetsshowinghighlightsoftheC++transactionexample.Theyarenotintendedforcut-and-pasteexecution.Forthecompletesource,seetheexamplesourcedirectory.

TheC++examplecreatesacache,thenusesittocreateaconnectionpool.

autocache=CacheFactory().set("log-level","none").create();autopoolFactory=cache.getPoolManager().createFactory();

poolFactory.addLocator("localhost",10334);autopool=poolFactory.create("pool");autoregionFactory=cache.createRegionFactory(RegionShortcut::PROXY);autoregion=regionFactory.setPoolName("pool").create("exampleRegion");


Theexampleapplicationgetsatransactionmanagerfromthecacheandbeginsatransaction.

autotransactionManager=cache.getCacheTransactionManager();

transactionManager->begin();

Withinthetransaction,theclientpopulatesdatastorewith10valuesassociatedwithKey1-Key10.

for(auto&key:keys){autovalue=getValueFromExternalSystem();region->put(key,value);}

Ifall put operationssucceed,theapplicationcommitsthetransaction.Otherwise,itretriesupto5timesifnecessary.

autoretries=5;while(retries--){try{transactionManager->begin();...//PUTOPERATIONS...transactionManager->commit();std::cout<<"Committedtransaction-exiting"<<std::endl;break;}catch(...){transactionManager->rollback();std::cout<<"Rolledbacktransaction-retrying("<<retries<<")"<<std::endl;}}


SystemPropertiesAvarietyofsystempropertiescanbespecifiedwhenaclientconnectstoadistributedsystem,eitherprogrammaticallyorina geode.properties file.See apache::geode::client::SystemProperties intheC++APIdocs

.

Thefollowingsettingscanbeconfigured:

GeneralPropertiesBasicinformationfortheprocess,suchascachecreationparameters.

LoggingPropertiesHowandwheretologsystemmessages.

StatisticsArchivingPropertiesHowtocollectandarchivestatisticsinformation.

DurableClientPropertiesInformationaboutthedurableclientsconnectedtothesystem.

SystemPropertiesforClientAuthenticationandAuthorizationInformationaboutvarioussecurityparameters.

SystemPropertiesforHighAvailabilitySystempropertiestoconfigureperiodicacknowledgment(ack).

Thefollowingtableslistattributesthatcanbespecifiedprogrammaticallyorstoredinthe geode.propertiesfiletobereadbyaclient.

GeneralProperties

cache-xml-file

Nameandpathofthefilewhosecontentsareusedbydefaulttoconfigureacacheifoneiscreated.Ifnotspecified,theclientstartswithanemptycache,whichispopulatedatruntime.

nodefault

heap-lru-delta

Thepercentageofentriesthesystemwillevicteachtimeitdetectsthatithasexceededtheheap-lru-limit.Thispropertyisusedonlyifheap-lru-limit isgreaterthan0.

10%

heap-lru-limit

Maximumamountofmemory,inmegabytes,usedbythecacheforallregions.Ifthislimitisexceededby heap-lru-delta percent,LRUreducesthememoryfootprintasnecessary.Ifnotspecified,orsetto0,memoryusageisgovernedbyeachregion’sLRUentrieslimit,ifany.

0


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/configuring/cppdocs

conflate-events

Clientsideconflationsetting,whichissenttotheserver. server

connect-timeout

Amountoftime(inseconds)towaitforaresponseafterasocketconnectionattempt.

59

connection-pool-size

Numberofconnectionsperendpoint 5

enable-chunk-handler-thread

Ifthechunk-handler-threadisoperative(enable-chunk-handler=true),itprocessestheresponseforeachapplicationthread.Whenthechunkhandlerisnotoperative(enable-chunk-handler=false),eachapplicationthreadprocessesitsownresponse.

false

disable-shuffling-of-endpoints

Iftrue,preventsserverendpointsthatareconfiguredinpoolsfrombeingshuffledbeforeuse.

false

max-fe-threads

Threadpoolsizeforparallelfunctionexecution.AnexampleofthisistheGetAlloperations.

2*numberoflogicalprocessors

max-socket-buffer-size

Maximumsizeofthesocketbuffers,inbytes,thattheclientwilltrytosetforclient-serverconnections.

65*1024

notify-ack-interval

Interval,inseconds,inwhichclientsendsacknowledgmentsforsubscriptionnotifications.

1

notify-dupcheck-life

Amountoftime,inseconds,theclienttrackssubscriptionnotificationsbeforedroppingtheduplicates.

300

ping-interval

Interval,inseconds,betweencommunicationattemptswiththeservertoshowtheclientisalive.Pingsareonlysentwhenthe ping-intervalelapsesbetweennormalclientmessages.Thismustbesetlowerthantheserver’s maximum-time-between-pings .

10

redundancy-monitor-interval

Interval,inseconds,atwhichthesubscriptionHAmaintenancethreadchecksfortheconfiguredredundancyofsubscriptionservers.

10

tombstone-timeout

Timeinmillisecondsusedtotimeouttombstoneentrieswhenregionconsistencycheckingisenabled.

480000

LoggingProperties

log-


disk-space-limit

Maximumamountofdiskspace,inmegabytes,allowedforalllogfiles,current,androlled.Ifsetto0,thespaceisunlimited.

0

log-fileNameandfullpathofthefilewherearunningclientwriteslogmessages.Ifnotspecified,logginggoesto stdout .

nodefaultfile

log-file-size-limit

Maximumsize,inmegabytes,ofasinglelogfile.Oncethislimitisexceeded,anewlogfileiscreatedandthecurrentlogfilebecomesinactive.Ifsetto0,thefilesizeisunlimited.

0

log-level

Controlsthetypesofmessagesthatarewrittentotheapplication’slog.Thesearethelevels,indescendingorderofseverityandthetypesofmessagetheyprovide:

Error(highestseverity)isaseriousfailurethatwillprobablypreventprogramexecution.

Warningisapotentialprobleminthesystem.

Infoisaninformationalmessageofinteresttotheenduserandsystemadministrator.

Configisastaticconfigurationmessage,oftenusedtodebugproblemswithparticularconfigurations.

Fine,Finer,Finest,andDebugprovidetracinginformation.Onlyusethesewithguidancefromtechnicalsupport.

Enablingloggingatanylevelenablesloggingforallhigherlevels.

config

StatisticsArchivingProperties

statistic-sampling-enabled

Controlswhethertheprocesscreatesastatisticarchivefile. true

statistic-archive-file

Nameandfullpathofthefilewherearunningsystemmemberwritesarchivesstatistics.If archive-disk-space-limit isnotset,theclientappendstheprocessIDtotheconfiguredfilename,likestatArchive-PID.gfs .Ifthespacelimitisset,theprocessIDisnotappendedbuteachrolledfilenameisrenamedtostatArchive-ID.gfs,whereIDistherollednumberofthefile.

./statArchive.gfs

archive-disk- Maximumamountofdiskspace,ingigabytes,allowedforallarchive


space-limit

files,current,androlled.Ifsetto0,thespaceisunlimited. 0

archive-file-size-limit

Maximumsize,inmegabytes,ofasinglestatisticarchivefile.Oncethislimitisexceeded,anewstatisticarchivefileiscreatedandthecurrentarchivefilebecomesinactive.Ifsetto0,thefilesizeisunlimited.

0

statistic-sample-rate

Rate,inseconds,thatstatisticsaresampled.Operatingsystemstatisticsareupdatedonlywhenasampleistaken.Ifstatisticarchivalisenabled,thenthesesamplesarewrittentothearchive.

Loweringthesamplerateforstatisticsreducessystemresourceusewhilestillprovidingsomestatisticsforsystemtuningandfailureanalysis.

1

enable-time-statistics

Enablestime-basedstatisticsforthedistributedsystemandcaching.Forperformancereasons,time-basedstatisticsaredisabledbydefault.SeeSystemStatistics .

false

DurableClientProperties

Attribute Description Default

auto-ready-for-events

WhetherclientsubscriptionsautomaticallyreceiveeventswhendeclarativelyconfiguredviaXML.Ifsetto false ,eventstartupisnotautomaticandyouneedtocallthe Cache.ReadyForEvents() methodAPIaftersubscriptionsfortheservertostartdeliveringevents.

true

durable-client-id

Identifiertospecifyifyouwanttheclienttobedurable. empty

durable-timeout

Time,inseconds,adurableclient’ssubscriptionismaintainedwhenitisnotconnectedtotheserverbeforebeingdropped.

300

SecurityProperties

Thetabledescribesthesecurity-relatedsystempropertiesfornativeclientauthenticationandauthorization.

SeeSSLClient/ServerCommunication.

SystemPropertiesforClientAuthenticationandAuthorization


http://docs-gemfire-native-cpp-staging.cfapps.io/101/geode-native-client-cpp/system-statistics/chapter-overview.html#concept_3BE5237AF2D34371883453E6A9474A79

security-client-auth-factory

Setsthekeyforthe AuthInitialize factoryfunction. empty

security-client-auth-library

Registersthepathtothe securityImpl.dll library. empty

security-client-dhalgo

Diffie-Hellmanbasedcredentialsencryptionisnotsupported. null

security-client-kspath

Pathtoa.PEMfile,whichcontainsthepubliccertificatesforallGeodecacheserverstowhichtheclientcanconnectthroughspecifiedendpoints.

null

ssl-enabled TrueifSSLconnectionsupportisenabled. empty

ssl-keystoreNameofthe.PEMkeystorefile,containingtheclient’sprivatekey.Notsetbydefault.Requiredif ssl-enabled istrue.

ssl-keystore-password

Setsthepasswordfortheprivatekey.PEMfileforSSL. null

ssl-truststore

Nameofthe.PEMtruststorefile,containingtheservers’publiccertificate.Notsetbydefault.Requiredif ssl-enabled istrue.

HighAvailabilityProperties

notify-ack-interval

Minimumperiod,inseconds,betweentwoconsecutiveacknowledgmentmessagessentfromtheclienttotheserver.

10

notify-dupcheck-life

Minimumtime,inseconds,aclientcontinuestotrackanotificationsourceforduplicateswhennonewnotificationsarrivebeforeexpiringit.

300


ClientCacheXMLReferenceThissectiondocumentstheXMLelementsyoucanusetoconfigureyourVMwareGemFire®nativeclientapplication.

TodefineaconfigurationusingXML:

1. SetcacheconfigurationparametersinadeclarativeXMLfile.Byconvention,thisuserguidereferstothefileas cache.xml ,butyoucanchooseanyname.

2. SpecifythefilenameandpathtoyourXMLconfigurationfilebysettingthe cache-xml-file propertyinthe geode.properties file.Ifyoudonotspecifypath,theapplicationwillsearchforthefileinitsruntimestartupdirectory.

Forexample:

cache-xml-file=cache.xml

Whenyourunyourapplication,thenativeclientruntimelibraryreadsandappliestheconfigurationspecifiedintheXMLfile.

ThedeclarativeXMLfileisusedtoexternalizetheconfigurationoftheclientcache.ThecontentsoftheXMLfilecorrespondtoAPIsfoundinthe apache::geode::client packageforC++applications,andtheApache::Geode::Client packagefor.NETapplications.

ElementsaredefinedintheClientCacheXSDfile,named cpp-cache-1.0.xsd ,whichyoucanfindinyournativeclientdistributioninthe xsds directory,andonlineathttps://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd .

CacheInitializationFile:XMLEssentials

ThissectionassumesyouarefamiliarwithXML.Whencreatingacacheinitializationfileforyournativeclientapplication,keepthesebasicsinmind:

PlaceanXMLprologatthetopofthefile.Forexample:

<?xmlversion="1.0"encoding="UTF-8"?>

Quoteallparametervalues,includingnumbersandbooleans.Forexample:


concurrency-level="10"caching-enabled="true"

SometypesarespecifictotheVMwareGemFire®cacheinitializationfile:

Duration:Timespecifiedasanon-negativeintegerandaunit,withnointerveningspace.Therecognizedunitsare h , min , s , ms , us ,and ns .Forexample:

idle-timeout="5555ms"statistic-interval="10s"update-locator-list-interval="5min"

Expiration:Complextypeconsistingofaduration(integer+unit)andanaction,wheretheactionisoneof invalidate , destroy , local-invalidate ,or local-destroy .Forexample:

<expiration-attributestimeout="20s"action="destroy"/><expiration-attributestimeout="10s"action="invalidate"/>

Library:Complextypeconsistingofalibrarynameandafunctionname.Usedbytheclienttoinvokefunctions.Forexample:

<persistence-managerlibrary-name="SqLiteImpl"library-function-name="createSqLiteInstance">

CacheInitializationFileElementDescriptions

Thissectionshowsthehierarchyof <client-cache> sub-elementsthatyouusetoconfigureVMwareGemFire®cachesandclients.Thetop-levelelementinthissyntaxis <client-cache> .

<client-cache> <pool> <locator> <server> <region> <region-attributes> <region-time-to-live> <region-idle-time> <entry-time-to-live> <entry-idle-time> <partition-resolver>


<cache-loader> <cache-listener> <cache-writer> <persistence-manager> <pdx>

Inthedescriptions,elementsandattributesnotdesignated“required”areoptional.

<client-cache>ElementThe<client-cache>elementisthetop-levelelementoftheXSDfile.

Yourdeclarativecachefilemustincludeaschemaofthefollowingform:

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

Attributesof<client-cache>

Attribute Description

version Required.Mustbe“1.0”

Sub-elementsof<client-cache>

<client-cache> mustcontainatleastoneofthesesub-elements:

Element MinimumOccurrences MaximumOccurrences

<pool> 0 unbounded

<region> 0 unbounded

<pdx> 0 1


<pool>ElementThe<pool>elementisacollectionoftheconnectionsbywhichyourclientapplicationcommunicateswiththeVMwareGemFire®server.

Aconnectioncanspecifyeitheralocatororaserver.

A <pool> mustcontainatleastoneconnection,locatororserver,andcancontainmultiplesofeitherorboth.

Sub-elementsof<pool>

A <pool> mustcontainatleastonesub-elementthatspecifiesaconnection,whichcanbeeitheraserveroralocator.Multiplesofeitherorbothtypesarepermitted.


<locator> 0 unbounded

<server> 0 unbounded

Attributesof<pool>


nameString.Required.Nameofthepool,usedwhenconnectingregionstothispool.

free-connection-timeout

Duration.Theamountoftimetowaitforafreeconnectionifmax-connectionsissetandalloftheconnectionsareinuse.

10s

load-conditioning-interval

Duration.Theintervalatwhichthepoolcheckstoseeifaconnectiontoagivenservershouldbemovedtoadifferentservertoimprovetheloadbalance.

5min

min-connections

Non-negativeinteger.Theminimumnumberofconnectionstokeepavailableatalltimes.Whenthepooliscreated,itwillcreatethismanyconnections.If0(zero),thenconnectionsarenotmadeuntilanoperationisperformedthatrequiresclient-to-servercommunication.

1

Integer>=-1.Themaximumnumberofconnectionstobecreated.Ifall


max-connections

oftheconnectionsareinuse,anoperationrequiringaclienttoserverconnectionblocksuntilaconnectionisavailable.Avalueof-1meansnomaximum.

-1

retry-attemptsInteger>=-1.Thenumberoftimestoretryanoperationafteratimeoutorexception.Avalueof-1indicatesthatarequestshouldbetriedagainsteveryavailableserverbeforefailing.

-1

idle-timeoutDuration.Setstheamountoftimeaconnectioncanbeidlebeforeitexpires.Avalueof0(zero)indicatesthatconnectionsshouldneverexpire.

5s

ping-interval Duration.Theintervalatwhichthepoolpingsservers. 10s

read-timeoutDuration.Theamountoftimetowaitforaresponsefromaserverbeforetimingoutandtryingtheoperationonanotherserver(ifanyareavailable).

10s

server-groupString.Specifiesthenameoftheservergrouptowhichthispoolshouldconnect.Ifthevalueisnullor""thenthepoolconnectstoallservers.

""

socket-buffer-size

String.Thesizeinbytesofthesocketbufferoneachconnectionestablished.

32768

subscription-enabled

Boolean.When true ,establishaservertoclientsubscription. false

subscription-message-tracking-timeout

String.Theamountoftimethatmessagessentfromaservertoaclientwillbetracked.Thetrackingisdonetominimizeduplicateevents.Entriesthathavenotbeenmodifiedforthisamountoftimeareexpiredfromthelist.

900s

subscription-ack-interval

String.Theamountoftimetowaitbeforesendinganacknowledgementtotheserverforeventsreceivedfromserversubscriptions.

100ms

subscription-redundancy

String.Setstheredundancylevelforthispool’sserver-to-clientsubscriptions.Aneffortismadetomaintaintherequestednumberofcopies(onecopyperserver)oftheserver-to-clientsubscriptions.Atmost,onecopyperserverismadeuptotherequestedlevel.If0thennoredundantcopiesarekeptontheservers.

0

statistic-interval

Duration.Theintervalatwhichclientstatisticsaresenttotheserver.Avalueof0(zero)meansdonotsendstatistics.

0ms(disabled)

pr-single-hop-enabled

String.When true ,enablesinglehopoptimizationsforpartitionedregions.

true

Boolean.Setsthethreadlocalconnectionspolicyforthispool.Whentrue thenanytimeathreadgoestouseaconnectionfromthispoolit



thread-local-connections

willcheckathreadlocalcacheandseeifitalreadyhasaconnectioninit.Ifsoitwilluseit.Ifnotitwillgetonefromthispoolandcacheitinthethreadlocal.Thisgetsridofthreadcontentionfortheconnectionsbutincreasesthenumberofconnectionstheserverssee.When false thenconnectionsarereturnedtothepoolassoonastheoperationbeingdonewiththeconnectioncompletes.Thisallowsconnectionstobesharedamongmultiplethreadskeepingthenumberofconnectionsdown.

false

multiuser-authentication

Boolean.Setsthepooltousemulti-usersecuremode.Ifinmultiusermode,thenappneedstoget RegionService instanceof Cache .

false

update-locator-list-interval

Duration.Thefrequencywithwhichclientupdatesthelocatorlist.Todisablethissetitsvalueto std::chrono::milliseconds::zero() .


<locator><locator> isasub-elementof <pool> thatdefinesaconnectiontoaVMwareGemFire®locator,specifiedbyahostandportcombination.

Attributesof<locator>


host String.Locatorhostname.

port Integerintherange0-65535,inclusive.Locatorportnumber.

Forexample:

<locatorhost="stax01"port="1001"/>

<server><server> isasub-elementof <pool> thatdefinesaconnectiontoaVMwareGemFire®server,specifiedbyahostandportcombination.


Attributesof<server>


host String.Serverhostname.

port Integerintherange0-65535,inclusive.Serverportnumber.

Forexample:

<serverhost="motown01"port="2001"/>

<region>Youcanspecify0ormoreregionsper <client-cache> .Thereisnomaximumlimitonthenumberofregionsa <client-cache> cancontain.

InordertoconnecttoaVMwareGemFire®server,aclientapplicationmustdefineatleastoneregionwhosenamecorrespondstothatofaregionontheserver.

Regionscanbenested.

Sub-elementsof<region>

Usethe <region-attributes> sub-elementtospecifymostofthecharacteristicsofaregion.Regionsmaybenested.


<region-attributes> 0 1

<region> 0 unbounded

Attributesof<region>

Youcanspecifymanyattributestoconfigurearegion,butmostoftheseattributesareencapsulatedinthe <region-attributes> sub-element.The <region> elementitselfhasonlytwoattributes:arequirednameandanoptionalreferenceidentifier.



name String.Required.

refid String.

<region-attributes>Specify0or1 <region-attributes> elementforeach <region> youdefine.

Ifyouspecifya <region-attributes> element,youmustspecifyatleastoneofthesesub-elements.Whenmorethanonesub-elementisspecified,theymustbedefinedinthisorder:

Element Type MinimumOccurrences MaximumOccurrences

<region-time-to-live> expiration 0 1

<region-idle-time> expiration 0 1

<entry-time-to-live> expiration 0 1

<entry-idle-time> expiration 0 1

<partition-resolver> library 0 1

<cache-loader> library 0 1

<cache-listener> library 0 1

<cache-writer> library 0 1

<persistence-manager> listofproperties 0 1

Attributesof<region-attributes>


caching-enabled

Boolean.Iftrue,cachedataforthisregioninthisprocess.Iffalse,thennodataisstoredinthelocalprocess,buteventsanddistributionswillstilloccur,andtheregioncanstillbeusedtoputandremove,etc.

true

cloning-enabled

Boolean.Setscloningonregion. false

scope Enumeration: local , distributed-no-ack , distributed-ack

initial- String.Setstheinitialentrycapacityfortheregion. 10000


capacity

load-factorString.Setstheentryloadfactorforthenext RegionAttributes tobecreated.

0.75

concurrency-level

String.Setstheconcurrencylevelofthenext RegionAttributes tobecreated.

16

lru-entries-limit

String.SetsthemaximumnumberofentriesthiscachewillholdbeforeusingLRUeviction.Areturnvalueofzero,0,indicatesnolimit.Ifdisk-policyisoverflows ,mustbegreaterthanzero.

disk-policyEnumeration: none , overflows , persist .Setsthediskpolicyforthisregion.

none

endpoints String.Alistof servername:port-number pairsseparatedbycommas.

client-notification

Booleantrue/false(on/off) false

pool-nameString.Thenameofthepooltoattachtothisregion.Thepoolwiththespecifiednamemustalreadyexist.

concurrency-checks-enabled

Boolean:true/false.Enablesconcurrentmodificationchecks. true

id String.

refid String.


<region-time-to-live><region-time-to-live>specifieshowlongthisregionremainsinthecacheafterthelastcreateorupdate,andtheexpirationactiontoinvokewhentimerunsout.Acreateorupdateoperationonanyentryintheregionresetstheregion’scounter,aswell.Get(read)operationsdonotresetthecounter.

Usethe <expiration-attributes> sub-elementtospecifydurationandexpirationaction.Theattributesof<expiration-attributes>mustbedefinedinthisorder:


timeout Duration,specifiedasanintegerandunits.Required.

action Enumeration.Oneof: invalidate , destroy , local-invalidate , local-destroy


<region-idle-time><region-idle-time>specifieshowlongthisregionremainsinthecacheafterthelastaccess,andtheexpirationactiontoinvokewhentimerunsout.Thecounterisresetafteranyaccess,includingcreate,put,andgetoperations.Accesstoanyentryintheregionresetstheregion’scounter,aswell.





<entry-time-to-live><entry-time-to-live>specifieshowlongthisentryremainsinthecacheafterthelastcreateorupdate,andtheexpirationactiontoinvokewhentimerunsout.Get(read)operationsdonotresetthecounter.





<entry-idle-time><entry-idle-time>specifieshowlongthisentryremainsinthecacheafterthelastaccess,andtheexpirationactiontoinvokewhentimerunsout.Thecounterisresetafteranyaccess,includingcreate,put,andgetoperations.

Usethe <expiration-attributes> sub-elementtospecifydurationandexpirationaction.Theattributesof


<expiration-attributes>mustbedefinedinthisorder:




<partition-resolver><partition-resolver>identifiesafunctionbyspecifying library-name and library-function-name .

Apartitionresolverisusedforsingle-hopaccesstopartitionedregionentriesontheserverside.Thisresolverimplementationmustmatchthatofthe PartitionResolver ontheserverside.SeetheAPIClassReference forthePartitionResolverclass.

Forexample:

<partition-resolverlibrary-name="appl-lib"library-function-name="createTradeKeyResolver"/>

<cache-loader><cache-loader>identifiesacacheloaderfunctionbyspecifying library-name and library-function-name .SeetheAPIClassReference fortheCacheLoaderclass.

<cache-listener><cache-listener>identifiesacachelistenerfunctionbyspecifying library-name and library-function-name .SeetheAPIClassReference fortheCacheListenerclass.


http://docs-gemfire-native-cpp-staging.cfapps.io/cppdocs/hierarchy.html



<cache-writer><cache-writer>identifiesacachewriterfunctionbyspecifying library-name and library-function-name .SeetheAPIClassReference fortheCacheWriterclass.

<persistence-manager>Foreachregion,ifthedisk-policyattributeissetto overflows ,apersistence-managerplug-inmustperformcache-to-diskanddisk-to-cacheoperations.SeetheAPIClassReference forthePersistenceManagerclass.

<persistence-manager>identifiesapersistencemanagerfunctionbyspecifying library-name andlibrary-function-name .Youcanalsospecifyasetofpropertiestobepassedtothefunctionasparameters.

Thesub-element <properties> isasequenceof0ormore <property> elements.

Each <property> isaname-valuepair.Wheretheattributesmustbespecifiedinthisorder:

name

value

Forexample:

<region-attributes><persistence-managerlibrary-name="libSqLiteImpl.so"library-function-name="createSqLiteInstance"><properties><propertyname="PersistenceDirectory"value="/xyz"/><propertyname="PageSize"value="65536"/><propertyname="MaxPageCount"value="1073741823"/></properties></persistence-manager></region-attributes>

<pdx>SpecifiestheconfigurationforthePortableDataeXchange(PDX)methodofserialization.




Attributesof<pdx>


ignore-unread-fields

Boolean.When true ,donotpreserveunreadPDXfieldsduringdeserialization.Youcanusethisoptiontosavememory.Setthisattributeto true onlyinmembersthatareonlyreadingdatafromthecache.

read-serialized

Boolean.When true ,PDXdeserializationproducesa PdxInstance insteadofaninstanceofthedomainclass.


VMware GemFire® C++ Client 10€¦ · Pivotal Cloud Foundry. GemFire Compatibility The GemFire Native Client supports applications that communicate with GemFire servers. Native Client

Documents