VMware GemFire® C++ Client 10€¦ · Pivotal Cloud Foundry. GemFire Compatibility The GemFire Native Client supports applications that communicate with GemFire servers. Native Client
Post on 19-Jul-2020
8 Views
Preview:
Transcript
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.
®
©CopyrightPivotalSoftwareInc,2013-2020 3 10.1
GemFireNativeClient10.1ReleaseNotes
What’sNewinGemFireNativeClient10.1VMwareGemFire®NativeClient10.1isbasedonApacheGeode1.11.
Version10.1includesanumberofimprovements:
SSLenhancement-supportforcertificatechaining,betterone-waySSLconsistency
CompatibilityissueswithvariousversionsofPCC
Performanceimprovements
Bugfixes.SeeIssuesResolvedinNativeClient10.1
TheApacheGeodecommunityhasahostofexamplesbasedonthelatestC++and.NETAPIs(https://github.com/apache/geode-native/tree/develop/examples ).
IssuesResolvedinNativeClient10.1ThissectiondescribesissuesresolvedinVMwareGemFire®NativeClientversion10.1anditspatchreleases,beginningwiththemostrecentrelease.
IssuesResolvedinNativeClient10.1.3
GEODE-8297,GEMNC-472:Increaseddefaulttimeoutvalueforauthorizationtoaccommodatenetworkswithhigherlatency.
IssuesResolvedinNativeClient10.1.2
GEODE-7930:Endpointnamesarenolongertruncatedto99characters.TheNativeClientnowsupportsendpointnamesthatmeettheRFC2181standardof255charactersforfully-qualifieddomainnames.Thissolutionalsocorrectsaspurious“Failedtoaddendpoint”errorthatwasissuedwhen,infact,noerrorhadoccurred.
IssuesResolvedinNativeClient10.1.1
GEODE-8015,GEMNC-470:Addeddebuggingsymbolstothereleasedlibraries.TheNativeClientrelease
©CopyrightPivotalSoftwareInc,2013-2020 4 10.1
forWindowsnowincludesa.pdbsymbolfile.OnLinux,thesymbolsarenowembeddedinthesharedlibrary(.sofile).
IssuesResolvedinNativeClient10.1.0
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.
©CopyrightPivotalSoftwareInc,2013-2020 5 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 6 10.1
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:
©CopyrightPivotalSoftwareInc,2013-2020 7 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 8 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 9 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 10 10.1
UpgradingaNativeClientApplicationFromVersion9toVersion10GemFireNativeClientVersion10introducesbreakingchangesforVersion9applications.Updatingyourclientapplicationswillrequiremoreinterventionthanmerelyrecompiling.
Ingeneral,youwillhavebestperformanceandreliabilityifclientsandserversbothrunthelatestversionsoftheirrespectivesoftware.
GemFireserverandclientsoftwarereleasesfollowsimilarnumberingschemes,buttheyarenotreleasedinlockstep.ThefollowingdiagramillustratestheinteroperabilitybetweenrecentversionsofGemFireserversoftwareandGemFireNativeClientsoftware.
OverviewofChangesVMwareGemFire®NativeClientimprovementsandnewfeaturesinclude:
AmodernizedC++APIthatconstitutesabigstepforwardtofullysupportingC++11.
Localmemorymanagementhasbeengreatlyimproved,aswellastheadoptionofanewcachemodelthatallowsformultiplecacheobjectstoexistinagivenprocessspace.
The.NETinterfacebenefitsfromalltheenhancementsmadeintheC++interface.
TheNativeClientnowsupportsIISapplicationdomainsandPivotalCloudFoundry.
Anewarchitecturethatallowsformoreflexibleclient-sidedatamodels
Improvementstothereflection-basedAutoSerializer
TheApacheGeodecommunityhasahostofexamplesbasedonthelatestC++and.NETAPIs(https://github.com/apache/geode-native/tree/develop/examples ).
ForexamplesofsourcechangesseetheNativeClient9toNativeClient10UpgradeSample .
©CopyrightPivotalSoftwareInc,2013-2020 11 10.1
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); ).
©CopyrightPivotalSoftwareInc,2013-2020 12 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 13 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 14 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 15 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 16 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 17 10.1
RegionShortcut Enumclassholdingallregiontypes(PROXY,CACHING_PROXY,CACHING_PROXY_ENTRY_LRU,LOCAL_ENTRY_LRU)
TypeRegistry Classforregisteringacustomserializabletype.
NeworRenamedClass SummaryofChanges
©CopyrightPivotalSoftwareInc,2013-2020 18 10.1
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 .
©CopyrightPivotalSoftwareInc,2013-2020 19 10.1
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 ).
©CopyrightPivotalSoftwareInc,2013-2020 20 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 21 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 22 10.1
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 ).
©CopyrightPivotalSoftwareInc,2013-2020 23 10.1
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;}
©CopyrightPivotalSoftwareInc,2013-2020 24 10.1
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:
©CopyrightPivotalSoftwareInc,2013-2020 25 10.1
<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.
©CopyrightPivotalSoftwareInc,2013-2020 26 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 27 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 28 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 29 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 30 10.1
ConfiguringtheClientCacheClientcachesprovidetheframeworkforclientstostore,manage,anddistributeapplicationdata.
AcacheisanentrypointforaccesstoVMwareGemFire®.Throughthecache,clientsgainaccesstotheVMwareGemFire®cachingframeworkfordataloading,distribution,andmaintenance.
A Cache instanceallowsyourclienttosetgeneralparametersforcommunicationbetweenacacheandothercachesinthedistributedsystem,andtocreateandaccessanyregioninthecache.
Regionsarecreatedfrom Cache instances.Regionsprovidetheentrypointstotheinterfacesforinstancesof Region and RegionEntry .
Formoreinformationspecifictoyourclientprogramminglanguage,seetheC++ClientAPI .
©CopyrightPivotalSoftwareInc,2013-2020 31 10.1
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++.
©CopyrightPivotalSoftwareInc,2013-2020 32 10.1
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-
©CopyrightPivotalSoftwareInc,2013-2020 33 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 34 10.1
whitespace spaceortab
anglebrackets <>
colon :
quote "
forwardslashandbackslash /\
pipe(verticalbar) |
questionmark ?
asterisk *
IneligibleCharacterdescription IneligibleCharacter
GettingtheRegionSizeThe Region APIprovidesa size methodthatgetsthesizeofaregion.Forclientregions,thisgivesthenumberofentriesinthelocalcache,notontheservers.Seethe Region APIdocumentationfordetails.
©CopyrightPivotalSoftwareInc,2013-2020 35 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 36 10.1
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();
©CopyrightPivotalSoftwareInc,2013-2020 37 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 38 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 39 10.1
storesdataintheclientcacheanddoesnotconnecttheregiontotheservers.Thisisaclient-side-onlyregion.Limitstheamountofdatastoredlocallyintheclienttoadefaultlimitof100,000entriesbyejectingtheleastrecentlyused(LRU)entries.
©CopyrightPivotalSoftwareInc,2013-2020 40 10.1
SerializingDataDatainyourclientapplication’sVMwareGemFire®cachemustbeserializabletobesharedwithVMwareGemFire®serversandotherVMwareGemFire®clients.VMwareGemFire®providesmultipledataserializationoptionsforstorageandtransmittalbetweenprocesses,ofwhichVMwareGemFire®PortableDataeXchange(PDX)serialization)offersthebestcombinationofversatilityandease-of-useformostapplications.
Tolearnmoreaboutotherserializationoptions,seetheDataSerializationsectionintheVMwareGemFire®UserGuide .
©CopyrightPivotalSoftwareInc,2013-2020 41 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 42 10.1
ReducedDeserializationofSerializedObjectsTheaccessmethodsfor PdxSerializable objectsallowyoutoexaminespecificfieldsofyourdomainobjectwithoutdeserializingtheentireobject.Thiscanreducedeserializationcostssignificantly.ClientC++appscanrunqueriesandexecutefunctionsagainsttheobjectsintheservercacheswithoutdeserializingtheentireobjectontheserverside.ThequeryengineautomaticallyrecognizesPDXobjectsandusesonlythefieldsitneeds.
ClientscanexecuteJavafunctionsonserverdatathatonlyaccesspartsofthedomainobjectsbyusingPdxInstance.
Likewise,peerscanaccessjustthefieldsneededfromtheserializedobject,keepingtheobjectstoredinthecacheinserializedform.
DeltaPropagationwithPDXSerializationYoucanuseVMwareGemFire®deltapropagationwithPDXserialization.
PDXSerializationDetailsSeethefollowingsectionsfordetailsonimplementingPDXserialization:
UsingthePdxSerializableAbstractClass
PdxSerializableExample
©CopyrightPivotalSoftwareInc,2013-2020 43 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 44 10.1
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_);}
©CopyrightPivotalSoftwareInc,2013-2020 45 10.1
PdxSerializableExampleThenativeclientreleasecontainsanexampleshowinghowaclientapplicationcanregisterforserializationofcustomobjectsusingtheC++PdxSerializableabstractclass.
Theexampleislocatedin examples/cpp/pdxserializable .
Theexampledefinestheserializableclass, Orders ,includingitsserializationanddeserializationmethodsanditsfactorymethod.Oncethesepiecesareinplace,executionissimple:themainroutineoftheexampleregisterstheserializableclassthenperformssomeputandgetoperations.
Execution
Theexampleperformsasequenceofoperations,displayingsimplelogentriesastheyrun.
Toruntheexample,followtheinstructionsintheREADME.mdfileintheexampledirectory.
Reviewthesourcecodeintheexampledirectorytoseeexactlyhowitoperates.
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:
©CopyrightPivotalSoftwareInc,2013-2020 46 10.1
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>();}
©CopyrightPivotalSoftwareInc,2013-2020 47 10.1
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:
©CopyrightPivotalSoftwareInc,2013-2020 48 10.1
if(region->existsValue("rtimmons")){std::cout<<"rtimmons'sinfonotdeleted"<<std::endl;}else{std::cout<<"rtimmons'sinfosuccessfullydeleted"<<std::endl;}
Finally,theapplicationclosesthecache:
cache.close();
©CopyrightPivotalSoftwareInc,2013-2020 49 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 50 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 51 10.1
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;}
©CopyrightPivotalSoftwareInc,2013-2020 52 10.1
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,
©CopyrightPivotalSoftwareInc,2013-2020 53 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 54 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 55 10.1
/*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();
©CopyrightPivotalSoftwareInc,2013-2020 56 10.1
Security:AuthenticationandEncryptionMostsecurityconfigurationtakesplaceontheVMwareGemFire®server.Theserver’ssecurityframeworkauthenticatesclientsastheyconnecttoacacheserverandauthorizesclientcacheoperationsusingdeveloper-providedimplementationsforauthenticationandauthorization.
Foranexplanationoftheserver-sideimplementationofsecurityfeatures,seeSecurity intheVMwareGemFire®UserGuide.
ANativeClientapplicationmustaddresstwosecurityconcernswhenconnectingtoaVMwareGemFire®server:
AuthenticationTheClientmustsubmititsauthenticationcredentialstotheserverusingthedeveloper-providedauthenticationimplementationexpectedbytheserver.
TLS/SSLClient/ServerCommunicationEncryptionCommunicationbetweenclientandservershouldbeencryptedsoauthenticationcredentialsandothertransmissionscannotbeviewedbythird-parties.
©CopyrightPivotalSoftwareInc,2013-2020 57 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 58 10.1
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;}};
©CopyrightPivotalSoftwareInc,2013-2020 59 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 60 10.1
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:
©CopyrightPivotalSoftwareInc,2013-2020 61 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 62 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 63 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 64 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 65 10.1
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>®ion){for(inti=0;i<keys.size();i++){region->put(keys[i],values[i]);}}
Asconfirmationthatthedatahasbeenstored,thesampleclientusestheAPItoretrievethevaluesandwritethemtotheconsole.Thisisdonewithoutreferencetotheserver-sideexamplefunction.
©CopyrightPivotalSoftwareInc,2013-2020 66 10.1
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;}
©CopyrightPivotalSoftwareInc,2013-2020 67 10.1
©CopyrightPivotalSoftwareInc,2013-2020 68 10.1
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.
©CopyrightPivotalSoftwareInc,2013-2020 69 10.1
Inadditiontothefailureconditionscommontoalltransactions,clienttransactionscanalsofailifthetransactiondelegatefails.Ifthedelegateperformingthetransactionfails,thetransactioncodethrowsaTransactionException .
ClientTransactionExamplesThenativeclientreleasecontainsatransactionexamplein ../examples/cpp/transaction .
Theexampleperformsasequenceofoperations,displayingsimplelogentriesastheyrun.
Torunanexample,followtheinstructionsinthe README.md fileintheexampledirectory.
Reviewthesourcecodeintheexampledirectorytoseeexactlyhowitoperates.
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");
©CopyrightPivotalSoftwareInc,2013-2020 70 10.1
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;}}
©CopyrightPivotalSoftwareInc,2013-2020 71 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 72 10.1
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-
©CopyrightPivotalSoftwareInc,2013-2020 73 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 74 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 75 10.1
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
©CopyrightPivotalSoftwareInc,2013-2020 76 10.1
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:
©CopyrightPivotalSoftwareInc,2013-2020 77 10.1
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>
©CopyrightPivotalSoftwareInc,2013-2020 78 10.1
<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
©CopyrightPivotalSoftwareInc,2013-2020 79 10.1
<pool>ElementThe<pool>elementisacollectionoftheconnectionsbywhichyourclientapplicationcommunicateswiththeVMwareGemFire®server.
Aconnectioncanspecifyeitheralocatororaserver.
A <pool> mustcontainatleastoneconnection,locatororserver,andcancontainmultiplesofeitherorboth.
Sub-elementsof<pool>
A <pool> mustcontainatleastonesub-elementthatspecifiesaconnection,whichcanbeeitheraserveroralocator.Multiplesofeitherorbothtypesarepermitted.
Element MinimumOccurrences MaximumOccurrences
<locator> 0 unbounded
<server> 0 unbounded
Attributesof<pool>
Attribute Description Default
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
©CopyrightPivotalSoftwareInc,2013-2020 80 10.1
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
Attribute Description Default
©CopyrightPivotalSoftwareInc,2013-2020 81 10.1
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() .
Attribute Description Default
<locator><locator> isasub-elementof <pool> thatdefinesaconnectiontoaVMwareGemFire®locator,specifiedbyahostandportcombination.
Attributesof<locator>
Attribute Description
host String.Locatorhostname.
port Integerintherange0-65535,inclusive.Locatorportnumber.
Forexample:
<locatorhost="stax01"port="1001"/>
<server><server> isasub-elementof <pool> thatdefinesaconnectiontoaVMwareGemFire®server,specifiedbyahostandportcombination.
©CopyrightPivotalSoftwareInc,2013-2020 82 10.1
Attributesof<server>
Attribute Description
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.
Element MinimumOccurrences MaximumOccurrences
<region-attributes> 0 1
<region> 0 unbounded
Attributesof<region>
Youcanspecifymanyattributestoconfigurearegion,butmostoftheseattributesareencapsulatedinthe <region-attributes> sub-element.The <region> elementitselfhasonlytwoattributes:arequirednameandanoptionalreferenceidentifier.
©CopyrightPivotalSoftwareInc,2013-2020 83 10.1
Attribute Description
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>
Attribute Description Default
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
©CopyrightPivotalSoftwareInc,2013-2020 84 10.1
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.
Attribute Description Default
<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:
Attribute Description
timeout Duration,specifiedasanintegerandunits.Required.
action Enumeration.Oneof: invalidate , destroy , local-invalidate , local-destroy
©CopyrightPivotalSoftwareInc,2013-2020 85 10.1
<region-idle-time><region-idle-time>specifieshowlongthisregionremainsinthecacheafterthelastaccess,andtheexpirationactiontoinvokewhentimerunsout.Thecounterisresetafteranyaccess,includingcreate,put,andgetoperations.Accesstoanyentryintheregionresetstheregion’scounter,aswell.
Usethe <expiration-attributes> sub-elementtospecifydurationandexpirationaction.Theattributesof<expiration-attributes>mustbedefinedinthisorder:
Attribute Description
timeout Duration,specifiedasanintegerandunits.Required.
action Enumeration.Oneof: invalidate , destroy , local-invalidate , local-destroy
<entry-time-to-live><entry-time-to-live>specifieshowlongthisentryremainsinthecacheafterthelastcreateorupdate,andtheexpirationactiontoinvokewhentimerunsout.Get(read)operationsdonotresetthecounter.
Usethe <expiration-attributes> sub-elementtospecifydurationandexpirationaction.Theattributesof<expiration-attributes>mustbedefinedinthisorder:
Attribute Description
timeout Duration,specifiedasanintegerandunits.Required.
action Enumeration.Oneof: invalidate , destroy , local-invalidate , local-destroy
<entry-idle-time><entry-idle-time>specifieshowlongthisentryremainsinthecacheafterthelastaccess,andtheexpirationactiontoinvokewhentimerunsout.Thecounterisresetafteranyaccess,includingcreate,put,andgetoperations.
Usethe <expiration-attributes> sub-elementtospecifydurationandexpirationaction.Theattributesof
©CopyrightPivotalSoftwareInc,2013-2020 86 10.1
<expiration-attributes>mustbedefinedinthisorder:
Attribute Description
timeout Duration,specifiedasanintegerandunits.Required.
action Enumeration.Oneof: invalidate , destroy , local-invalidate , local-destroy
<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.
©CopyrightPivotalSoftwareInc,2013-2020 87 10.1
<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.
©CopyrightPivotalSoftwareInc,2013-2020 88 10.1
Attributesof<pdx>
Attribute Description
ignore-unread-fields
Boolean.When true ,donotpreserveunreadPDXfieldsduringdeserialization.Youcanusethisoptiontosavememory.Setthisattributeto true onlyinmembersthatareonlyreadingdatafromthecache.
read-serialized
Boolean.When true ,PDXdeserializationproducesa PdxInstance insteadofaninstanceofthedomainclass.
©CopyrightPivotalSoftwareInc,2013-2020 89 10.1
top related