Page 1
PivotalGemFire®NativeClient9.1
Note:ThesupportperiodforGemFireNativeClient9.1hasexpired,andthisversionisnolongersupported.Tostayuptodatewiththelatestsoftwareandsecurityupdates,upgradetoasupportedversion.
©CopyrightPivotalSoftwareInc,2013-2019
Page 2
289
101213141516181921212225282930313233343536394043444546474849505050515253545556575859616263
TableofContents
TableofContentsPivotalGemFire®NativeClient9.1DocumentationPivotalGemFireNativeClient9.1ReleaseNotesGemFireNativeClientSupportedConfigurationsGettingStartedwithaNativeClientAbouttheClientInstallingtheNativeClientRunningClientApplicationsDevelopingC++ProgramsonLinuxDevelopingC++ProgramsonSolarisDevelopingC++ProgramsonWindowsQuickStartExamplesConfiguringtheQuickStartEnvironmentAbouttheQuickStartExamplesRunningtheExamplesSettingSystemPropertiesConfiguringtheClientandServerClientConfigurationCacheServerConfigurationAttributeDefinitionPrioritySearchPathforMultiplePropertiesFilesOverridingPropertiesFileSettingsDefiningPropertiesProgrammaticallyAttributesinthePropertiesFilePropertiesFileExampleUsingtheDefaultSampleFileConfiguringtheNativeClientCacheCachesAbouttheClientCacheCacheAPIsLocal,Remote,andDistributedCachesCreatingandAccessingaCacheClosingtheCacheCacheInitializationFile(cache.xml)CacheInitializationFileBasicsExamplecache.xmlFileRegionsDeclarativeRegionCreationProgrammaticRegionCreationInvalidatingandDestroyingRegionsRegionAccessGettingtheRegionSizeRegionEntriesEntryDistributionRequirementsRegisteringInterestforEntriesUsingserverKeystoRetrieveaSetofRegionKeysAddingEntriestotheCacheUpdatingEntries
©CopyrightPivotalSoftwareInc,2013-2019 2 9.1
Page 3
646566676869707172737475767778798385909192939495969799
100101102103104105106107108110112113118119120122124125130131132133134
AccessingEntriesInvalidatingorDestroyingCachedEntriesNotificationforOperationsRegionConsistencyRegionAttributesSpecifyingRegionAttributesRegionShortcutsMutableandImmutableRegionAttributesCachingEnabledInitialCapacityLoadFactorConcurrencyLevelConcurrencyChecksEnabledLruEntriesLimitDiskPolicyPersistenceManagerSpecifyingExpirationAttributesApplicationPlug-insCacheManagementClient-to-ServerConnectionProcessControllingCacheSizeManagingtheLifetimeofaCachedObjectUsingThreadSafetyinCacheManagementTroubleshootingC++ClientAPIAbouttheC++ClientAPICreatingaCacheCreatingaProxyClient-SideRegionAddinganEntrytotheCacheAccessinganEntryRemovinganEntrySerializingDataRegionDataRequiringSerializationDataSerializationOptionsSerializingDatawithPDXSerializationSerializeYourDomainObjectswithPdxSerializerandPdxWrapperSerializeUsingthePdxSerializableClassPerformingput,get,andlocalDestroyOperationswithaPDXDomainObjectUsingAutomaticPDXSerializationProgrammingYourApplicationtoUsePdxInstancesConfiguringPDXtoIgnoreUnreadFieldsDuringDeserializationUsingPdxInstanceFactorytoCreatePdxInstancesUsingC++EnumTypewithPDXSerializationUsingPDXSerializationwithDeltaPropagationSerializingDatawiththeSerializableInterfaceSerializingObjectGraphsSerializingandAccessingDataasaBlobImplementingUser-DefinedObjectsinJavaClientsUsingaCustomClassCreatingNewStatistics
©CopyrightPivotalSoftwareInc,2013-2019 3 9.1
Page 4
135136137138139140141142143144146148149150151152153154155156157158159160161162163165166167168169170171173174176178179180181182183184185186187188189190
.NETClientAPIAboutthe.NETClientAPI.NETNamingandUsageConventionsPrimaryAPIsCacheAPIsRegionandEntryAPIsDataSerializationAPIsEventHandlingAPIsPropertyCollectionsandLoggingAPIsC++Classto.NETClassMappingsJavato.NETTypeMappingTableObjectLifetimes.NETApplicationDomainsProblemScenariosCreatingaCacheCreatingaRegionAddinganEntrytotheCacheAccessinganEntryRemovinganEntryDataSerializationDataSerializationOptionsSerializewithPDXSerializationGemFirePDXSerializationFeaturesSerializeUsingtheGemFirePDXAutoserializerExtendthePDXAutoserializerSerializeYourDomainObjectswithIPdxSerializerSerializeUsingtheIPdxSerializableInterfaceProgramYourApplicationtoUseIPdxInstanceUsetheIPdxInstanceFactorytoCreateIPdxInstancesMap.NETDomainTypeNamestoPDXTypeNameswithIPdxTypeMapperSerializewiththeIGeodeSerializableInterfaceGenericandCustomSerializableTypesHowSerializationWorkswithIGeodeSerializableImplementtheIGeodeSerializableInterfaceRegistertheTypeUsingaCustomClassWithIGeodeSerializableApplicationCallbacksASimpleC#ExampleTroubleshooting.NETApplicationsResolvingtheErrorUsingApache.Geode.dllAsaPrivateAssemblyImplementingtheSharedAssemblyPreservingDataHighAvailabilityforClient-ServerCommunicationConfiguringClientsforHighAvailabilitySendingPeriodicAcknowledgmentEnablingQueueConflationtoImproveUpdatePerformanceDurableClientMessagingDurableClientMessagingRequirementsClient-SideConfiguration
©CopyrightPivotalSoftwareInc,2013-2019 4 9.1
Page 5
191192193194195196197198199200201202203204205206208209210211212213214215216217218219220221221221223224225226227229230231232233234235236237238239241242
ConfiguringaDurableClientConfiguringDurableInterestinKeysConfiguringDurableClientReconnectionSendingCacheReadyMessagestotheServerDisconnectingfromtheServerLifeCycleofaDurableClientInitialOperationDisconnectionReconnectionDurableMessageReplayApplicationOperationsDuringInterestRegistrationImplementingCacheListenersforDurableClientsSecurityAuthenticationProcessandMultiuserAuthenticationConfiguringCredentialsforAuthenticationConfiguringAuthenticationbytheCacheServerServerAuthenticationErrorsCreatingMultipleSecureUserConnectionsRequirementsandCaveatsforRegionServiceUsinganLDAPServerforClientAuthenticationEncryptedAuthenticationEncryptCredentialswithDiffe-HellmanUsingPKCSforEncryptedAuthenticationClientAuthorizationConfiguringClientAuthorizationPost-OperativeAuthorizationDeterminingPre-orPost-OperationAuthorizationSecurity-RelatedSystemProperties(gemfire.properties)SSLClient/ServerCommunicationSetUpOpenSSLStartingandstoppingtheclientandserverwithSSLinplaceRemoteQueryingRemoteQueryingBasicsExampleDataandClassDefinitionsExecutingaQueryfromtheClientQueryingthePortfoliosRegionModifyingCacheContentsCreatingIndexesRemoteQueryingRequirementsUsingQueryStringsintheClientFROMClauseUsingIteratorVariablesImportingandUsingObjectClassesPredefinedClassTypesSpecifyingtheObjectTypesofFROMClauseCollectionsSELECTProjectionListSELECTStatementQueryResultsWHEREClauseJoins
©CopyrightPivotalSoftwareInc,2013-2019 5 9.1
Page 6
243244245246247248249250251252253254255256257260261263264265266271272273274275276277278279280281282283284286287288289290291292293294297298300301302303
AccessingCachedDataBasicRegionAccessAttributeVisibilityModifyingQueryScopeNestedQueryScopesWhenNamesCannotBeResolvedQueryLanguageElementsMethodInvocationSupportedQueryLanguageLiteralsTypeConversionsRemoteQueryAPICreatingandManagingQueriesQueryResultSetsQueryCodeSamplesReturningResultSetQueryCodeSamplesReturningStructSetContinuousQueryingHowContinuousQueryingWorksImplementingaContinuousQueryConfiguringYourSystemforContinuousQueryingWritingtheContinuousQueryWritingtheCQListenerorCQStatusListenerCqEventObjectRunningtheContinuousQueryCodeCQExecutionOptionsWhenanErrorOccursinaRunningCQManagingContinuousQueriesCQAPIandMainFeaturesUsingConnectionPoolsHowClientLoadBalancingWorksServerLocatorsConnectionPoolsDiscoveringLocatorsDynamicallyConfiguringPoolsNativeClientPoolAPIPoolConfigurationExampleandSettingsSubscriptionPropertiesRunningtheConnectionPoolCodeTransactionsHowClientTransactionsWorkRunningaTransactionSuspendingandResumingTransactionsFunctionExecutionUnderstandingData-AwareFunctionRoutingHowFunctionsExecuteExecutingFunctionsRunningtheFunctionProgrammingtoGetFunctionResultsSolutionsandUseCasesDeltaPropagationHowDeltaPropagationWorks
©CopyrightPivotalSoftwareInc,2013-2019 6 9.1
Page 7
304305306307309310311312313314318320323324325326327328329330331332333334335336337341342343344345
DeltaPropagationAPICloningImplementingDeltaPropagationExceptionsandLimitationsProgrammingExamplesDeclaringaClientRegionAPIProgrammingExample–C#APIProgrammingExample–C++DataSerializationExamplesC++SerializationExampleC#SerializationExampleJavaSerializationExampleInteroperabilityofLanguageClassesandTypesInteroperabilityofC++TypesWhenUsingPDXSerializationSystemStatisticsSamplingStatisticsSystemPerformanceStatisticsRegionStatisticsCachePerformanceStatisticsContinuousQueryStatisticsCQServiceStatisticsPoolStatisticsDeltaStatisticsOperatingSystemStatisticsLinuxProcessStatisticsSolarisProcessStatisticsWindowsProcessStatisticsInstallingtheSQLitePersistenceManagerLinuxInstallationSolarisInstallationWindowsInstallationGlossary
©CopyrightPivotalSoftwareInc,2013-2019 7 9.1
Page 8
LATESTVERSION:9.1.1- RELEASENOTES
PivotalGemFire®NativeClient9.1DocumentationPublishedSeptember12,2017
Thisdocumentationprovidesstep-by-stepproceduresforinstallation,configuration,anddevelopmentofnativeclients.
PivotalGemFireNativeClient9.1ReleaseNotes
SupportedConfigurationsandSystemRequirements
C++and.NETAPI
GettingStartedwithaNativeClientThissectiongivesyouaconceptualoverviewofthenativeclient.Itshowsyouhowtoinstalltheproduct,buildnativeclientapplicationsonvariousplatforms,andruntheproductexamples.
SettingSystemProperties
Thissectiondescribeshowtoconfigureclientsandcacheserverstoparticipateinadistributedsystem.
ConfiguringtheClientCache
Thissectiondescribestheclientcachefunctionality,initializationfile,andAPIs.Itprovidesinformationaboutcreatingandworkingwithcaches,cacheregions,andregionentries.
C++ClientAPI
Thissectiondescribestheprimaryclasses,andusageconventionsforthenativeclientC++API.ItdemonstrateshowtousetheAPItocreatecachesandperformdataserialization.SeetheC++API documentationforAPIdetails.
.NETClientAPI
Thissectiondescribestheprimaryclasses,usageconventions,andC++to.NETclassmappingsofthe.NETclientAPI.ItdemonstrateshowtousetheAPItocreatecachesandperformdataserialization.Seethe.NETAPI documentationforAPIdetails.
PreservingData
Aservermaypreservethedataqueuedandintendedtobesenttoaclient,suchthatthedataisnotdiscardedifcommunicationbetweentheserverandclientisdisrupted.Preservationpreventsmessageloss,whichcancauseaclienttohaveinconsistentdata.Redundantqueuesandahighavailabilityserverimplementationmayfurtherensurethatqueueddataisnotlost.
Security
Securitydescribeshowtoimplementthesecurityframeworkfortheclient,includingauthentication,authorization,ecryption,andSSLclient/servercommunication.
RemoteQuerying
RemoteQueryingdocumentsremotequeryingfromtheclienttotheGemFirecacheserver.Usingexamplesandprocedures,itdescribeshowtousetheAPIstorunqueriesagainstcacheddata,workwithquerystringsintheclient,createandmanagequeries,andcreateindexes.
ContinuousQuerying
ThissectiondescribeshowtoimplementcontinuousqueryingintheclientsothatC++and.NETclientscanrunqueriesagainsteventsinthecacheserverregion.ItalsodescribesmainfeaturesandtheclientCQAPI.
UsingConnectionPools
UsingConnectionPoolsdescribeshowconnectionpoolsachieveloadbalancingfortheclientanddescribeshowtoconfigureconnectionpoolsasserverlocatorsorasalistofservers.
Transactions
Transactionsdescribeshowtransactionsworkontheclientside.Itprovidesexamplesforrunning,suspending,andresumingtransactions.
FunctionExecution
FunctionExecutiondescribeshowyoucanexecuteapplicationfunctionstoachievelinearscalability.Itexplainshowfunctionexecutionworksandlistsspecificusecases.
DeltaPropagationDeltaPropagationdescribeshowdeltas(updatestodata)arepropagatedandhowtoimplementdeltapropagation.Italsoanalyzesperformancelimitations.
ProgrammingExamplesThischapterprovidesasetofprogrammingexamplestohelpyouunderstandtheGemFirenativeclientAPI.
InteroperabilityofLanguageClassesandTypes
InteroperabilityofLanguageClassesandTypesprovidesatablethatmapsC++classmethodstocorresponding.NETclassmethodsandatablethatmapsJavatypesto.NETtypes.
SystemStatistics
SystemStatisticsprovidesinformationonthePivotalGemFireinstallationandincludesstandardstatisticsforcachinganddistributionactivities.
InstallingtheSQLitePersistenceManager
InstallingtheSQLitePersistenceManagerdescribeshowtodownload,buildandinstalltheSQLitedatabaselibrariesforusewithdiskoverflow.
Glossary
Thisglossarydefinestermsusedinthedocumentation.
©CopyrightPivotalSoftwareInc,2013-2019 8 9.1
Page 9
LATESTVERSION:9.1.1- RELEASENOTES
PivotalGemFireNativeClient9.1ReleaseNotes
What’sNewinPivotalGemFireNativeClient9.1ThePivotalGemFireNativeClient9.1includesthesenewfeaturesandchanges:
NativeClientversion9.1workswithPivotalGemFireversions9.0.0andlater.
Fromversion9.0,asimplifiedDLLloadingleadstofewerruntimeerrors,becausethereisonlyasingle.NETassemblytoload.Thisisparticularlybeneficialfor.NETwebapplicationsthatrununderIIS.
Fromversion9.0,GEM-145addssupportfortwo-phasecommittransactions.
Fromversion9.0,enabledSSL/TLSciphersupportforcompatibilitywiththelatestversionoftheOpenSSLDEFAULTcipherlist.
InstallingtheGemFireNativeClient9.1DownloadthePivotalGemFireNativeClient9.1fromthePivotalGemFireproductdownload page.ThereisaZIPformatfileforallplatforms.SeeInstallingtheNativeClientinstallationinstructions.
NativeClientversion9.1workswithPivotalGemFireversions9.0.0andlater.UpgradeallserversrunningPivotalGemFiretoversion9.0.0oralaterversion.
This9.1releaserequiresanupdateofallclientcode:
Updatethenamespacetouse apache::geode::client inplaceof gemfire forC++clients.Use Apache.Geode.Client inplaceof Gemstone.GemFire.Cache.Generic for.NETclients.
Deprecatedfunctionsandclassesarenolongerpresent.Updateclientcodesuchthatitnolongerusesanyoftheseremovedfunctionsandclasses.
Recompileandlinktheupdatedclientcode.
IssuesResolvedinPivotalGemFireNativeClientThefollowingissues,listedbytheirreleasenumbers,havebeenresolvedinversion9.1ofthePivotalGemFireNativeClient.
9.1.1GEMNC-359:Improvedauthorizationacrosstheappdomainboundary.
GEMNC-365:FixedanunexpectedCacheableStringexception.
9.1.0GEODE-2440:Updatesthe CacheableKey::hashcode typetomatchtheserver.
GEMNC-132:ProductversioninformationisnowpropagatedtotheWindowsDLLandEXE.
©CopyrightPivotalSoftwareInc,2013-2019 9 9.1
Page 10
LATESTVERSION:9.1.1- RELEASENOTES
GemFireNativeClientSupportedConfigurationsThePivotalGemFirenativeclientprovidesaccessforC++andMicrosoft®.NET™clientstotheGemFiredistributedsystem.ItoperatesonplatformsrunningMicrosoftWindows,Linux(Intel),andSunSolaris.
NativeClientversion9.1workswithPivotalGemFireversions9.0.0andlater.
Operatingsystemrequirementsarelistedinthechartbelow:
Solaris11(deprecated) x86-64
RHEL6(deprecated) x86-64
RHEL7 x86-64
SLES11**(deprecated) x86-64
SLES12** x86-64
Windows2012(deprecated) x86-64
WindowsServer2012R2(deprecated) x86-64
WindowsServer2016 x86-64
Windows8.1(deprecated) x86-64
Windows10 x86-64
**Indicatesoperatingsystemsthathavenotbeenfullytestedbutarestillsupported.
HostMachineRequirementsEachmachinethatrunsanativeclientmustmeetthefollowingrequirements:
AsystemclocksettothecorrecttimeandatimesynchronizationservicesuchasNetworkTimeProtocol(NTP).Correcttimestampspermitthefollowingactivities:
Logsthatareusefulfortroubleshooting.Synchronizedtimestampsensurethatlogmessagesfromdifferenthostscanbemergedtoreproduceanaccuratechronologicalhistoryofadistributedrun.Aggregateproduct-levelandapplication-leveltimestatistics.Accuratemonitoringofthesystemwithscriptsandothertoolsthatreadthesystemstatisticsandlogfiles.
Thehostnameandhostfilesareproperlyconfiguredforthemachine.
ManydefaultLinuxinstallationsuseSYNcookiestoprotectthesystemagainstmaliciousattacksthatfloodTCPSYNpackets.TheuseofSYNcookiesdramaticallyreducesnetworkbandwidth,andcanbetriggeredbyarunningGemFiredistributedsystem.TodisableSYNcookiespermanently:
1. Editthe /etc/sysctl.conf filetoincludethefollowingline:
net.ipv4.tcp_syncookies=0
SettingthisvaluetozerodisablesSYNcookies.2. Reload sysctl.conf :
sysctl-p
WindowsSupportDetailsRuntimeLibraryRequirements
TheclientrequirestheMicrosoftVisualC++2013RedistributablePackage .Thispackagecontainsruntimelibrariesneededbytheclient;installitforyourplatformarchitectureonallmachinesthatwillruntheclient.
.NETFrameworkVersionSupport
ThePivotalGemFirenativeclientissupportedwithMicrosoft.NETFramework4.5.2.
©CopyrightPivotalSoftwareInc,2013-2019 10 9.1
Page 11
AMicrosoft.NETFrameworkmustbeinstalledtosupporttheC++/CLI(CommonLanguageInfrastructure)libraryforthenativeclient.
Theclientsupports.NET4.5.2andVisualStudio2013(forcompilingC++applicationsonWindows).Formoreinformationonthefeaturesof.NETandVisualStudioCommunityEdition2013Update5,seetheVisualStudio2013webpage .
LinuxForLinux,youcanverifythatyoumeetthenativeclientdependenciesatthelibrarylevelbyusingthe ldd toolandenteringthiscommand:
prompt>ldd$client-installdir/lib/libgfcppcache.so
whereclient-installdiristhelocationinwhichyouhaveinstalledtheclient.
Thefollowinglibrariesareexternaldependenciesofthenativelibrary, libgfcppcache.so .Verifythatthelddtooloutputincludesallofthese:
libdl.so.2
libm.so.6
libpthread.so.0
libc.so.6
libz.so.1
SoftwareRequirementsforUsingSSLIfyouplanonusingSSLinyourGemFirenativeclientandserverdeployment,youwillneedtodownloadandinstallOpenSSL.
TheGemFirenativeclientrequiresOpenSSLversion1.0.2.ForWindowsplatforms,youcanuseeithertheregularortheOpenSSL“Light”version.
Inaddition,makesurethatyoursystemenvironmentvariableshavebeenconfiguredtoincludeOpenSSL.
SeeSSLClient/ServerCommunication forinstructions.
©CopyrightPivotalSoftwareInc,2013-2019 11 9.1
Page 12
LATESTVERSION:9.1.1- RELEASENOTES
GettingStartedwithaNativeClientThissectiongivesyouaconceptualoverviewofthenativeclient.Itshowsyouhowtoinstalltheproduct,buildnativeclientapplicationsonvariousplatforms,andruntheproductexamples.
ThenativeclientprovidesaccessforC++andMicrosoft .NET™clientstoaGeodedistributedsystem.
AbouttheClient
ThenativeclientdeliversthefullsetofcapabilitiessuppliedbyJavaclientscommunicatingwithaGeodeserver.
InstallingtheNativeClientInstallthenativeclientbyextractingthecontentsofaZIPfileandsettinguptheenvironment.
RunningClientApplications
Setuptheenvironmentforthenativeclientonmultipleplatforms.Compileandrunclientprograms.
QuickStartExamplesRunthenativeclientQuickStartexamplestounderstandnativeclientfunctionality.
®
©CopyrightPivotalSoftwareInc,2013-2019 12 9.1
Page 13
LATESTVERSION:9.1.1- RELEASENOTES
AbouttheClientTheGemFireclientdeliversthefullsetofcapabilitiessuppliedbyJavaclientscommunicatingwithaGemFireserver.
TheGemFireclientiswrittenentirelyinC++,soitsinitializationprocessdoesnotinvolvethecreationofaJavavirtualmachine.The.NETclientprovidesoperationsforthe.NETFrameworkapplicationdeveloperwhowritesin.NETlanguagesandneedstoaccesstheGemFireserver.
ClientsinC++,Java,and.NETlanguagescommunicateonlywiththecacheserveranddonotcommunicatewitheachother.Theclientsinterfacewiththeserveratthesocketslevelandimplementthesamewireprotocoltotheserver.Thesecapabilitiesproduceextremelyhighperformanceandsystemscalability.
C++and.NETclientsprovideaccesstothefullregionAPI,includingsupportforapplicationplug-ins,managedconnectivity,highlyavailabledata,andreliablefailovertoaspecifiedserverlist.Allofthisistransparenttotheenduser.
Youcanconfigureclientstocachedatalocally,ortheycanactinacachelessmodewheretheyretrievedatafromacacheserveranddirectlypassittoothersystemmemberswithoutincurringthecachingoverhead.Theycanbeconfiguredasreadonlycaches,orbeconfiguredtoreceivenotificationsfromtheserverwheneverakeyofinteresttotheclientchangesontheserver.
Thisfigurediagramshow.NETandC++applicationsaccessthecacheserver.
©CopyrightPivotalSoftwareInc,2013-2019 13 9.1
Page 14
LATESTVERSION:9.1.1- RELEASENOTES
InstallingtheNativeClientInstallthenativeclientbyextractingthecontentsofaZIPfileandsettinguptheenvironment.
InstallationPrerequisitesBeforeinstallingtheGemFirenativeclient,completethefollowingprerequisites:
ConfirmthatyoursystemmeetsthehardwareandsoftwarerequirementsdescribedinGemFireNativeClientSupportedConfigurations.
FromthePivotalGemFiredownloadpage ,selectDownload.
UnderFileGroups,selectanddownloadthePivotalGemFirenativeclientZIPfileappropriateforyouroperatingsystemandprocessorarchitecture.
UncompresstheZIPFileUncompresstheZIPfile.Forexample:
unzippivotal-gemfire-nativeclient-linux-64bit-9.1.0.zip
Thedirectorycreatedistheproduct-dirusedinsettingenvironmentvariables.
EnvironmentVariablesSettheenvironment:
Setthe GFCPP environmentvariabletoproduct-dir.
Add $GFCPP/bin tothe PATH .
Add $GFCPP/lib tothe LD_LIBRARY_PATH .
Forexample,onLinuxorSolaris:
exportGFCPP=product-direxportPATH=$PATH:$GFCPP/binexportLD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GFCPP/lib
Similarly,onWindows:
setGFCPP=product-dirsetPATH=%PATH%;%GFCPP%\binsetLD_LIBRARY_PATH=%LD_LIBRARY_PATH%;%GFCPP%\lib
©CopyrightPivotalSoftwareInc,2013-2019 14 9.1
Page 15
LATESTVERSION:9.1.1- RELEASENOTES
RunningClientApplicationsSetuptheenvironmentfortheGemFireclientonmultipleplatforms.Compileandrunclientprograms.
DevelopingC++ProgramsonLinuxThissectiondescribeshowtobuildandrunaclientapplicationonLinux.
DevelopingC++ProgramsonSolarisThissectiondescribeshowtobuildandrunaclientapplicationonSolaris.
DevelopingC++ProgramsonWindowsGemFireusestheVisualStudio2010ServicePack1compilerforC++programsonWindows,whichinvokesMicrosoft cl.exe fromthecommandlineatcompiletime.®
©CopyrightPivotalSoftwareInc,2013-2019 15 9.1
Page 16
LATESTVERSION:9.1.1- RELEASENOTES
DevelopingC++ProgramsonLinuxThissectiondescribeshowtobuildandrunaclientapplicationonLinux.
Note:WhencompilingexternalprojectsorapplicationsthatareusedorreferencedbytheGemFireclient,makesurethatyoucompilethemforthesametargetarchitectureasyourclientinstallation.Forexample,ifyouinstalledthe64-bit(x86)versionoftheclient,compileyourexternalprojectsfor64-bit(x86)architecture.
Step1.SetEnvironmentVariablesSettheclientenvironmentvariablesoneachLinuxhost.Foreachcase,product-diristhepathtotheclientproductdirectory.
ForBourneandKornshells(sh,ksh,bash)
GEODE=product-dir;exportGEODEPATH=$GEODE/bin:$PATH;exportPATHLD_LIBRARY_PATH=$GEODE/lib:$LD_LIBRARY_PATH;exportLD_LIBRARY_PATH
Step2.CompileC++ClientsandDynamicallyLinkThemtotheGemFireLibraryOnLinux,the g++ compilerissupported.TobuildandlinkaC++clienttoGemFireonLinux,thecompilationcommandlinemustincludetheargumentslistedinthefollowingtable.
Argument Explanation
-D_REENTRANT RequiredtocompileLinuxprogramsinathread-safeway.
-m32 or -m64 Enables32-bitor64-bitcompilation.
-I$GEODE/include Specifiestheclient include directory.
ThefollowingtableliststhelinkerswitchesthatmustbepresentonthecommandlinewhendynamicallylinkingtotheGemFirelibrary.
Argument Explanation
-rpath $GEODE/lib Tellsthelinkertolookin $GEODE/lib forlibrariesonwhichtheclientlibrarydepends.
-L$GEODE/lib Tellsthelinkerwheretofindthenamedlibraries.
-o durableclient Tellsthelinkertooutputanobjectfilenamed‘durableclient’.
-lpivotalgemfire LinkstheclientC++cachelibrarytothecompiledexecutable.
Thefollowingexamplescompileandlinkthe $GEODE/SampleCode/quickstart/cpp/DurableClient.cpp clienttothe durableclient outputfile.
CompilingandDynamicallyLinkingonLinuxfor32-bit
g++\-D_REENTRANT\-03\-Wall\-m32\-I$GEODE/include\cpp/DurableClient.cpp\cpp/plugins/DurableCacheListener.cpp\-ocpp/DurableClient\-L$GEODE/lib\-Wl,-rpath,$GEODE/lib\-lpivotalgemfire
CompilingandDynamicallyLinkingonLinuxfor64-bit
©CopyrightPivotalSoftwareInc,2013-2019 16 9.1
Page 17
g++\-D_REENTRANT\-03\-Wall\-m64\-I$GEODE/include\cpp/DurableClient.cpp\cpp/plugins/DurableCacheListener.cpp\-ocpp/DurableClient\-L$GEODE/lib\-Wl,-rpath,$GEODE/lib\-lpivotalgemfire
Step3.MakeSuretheClientLibraryCanBeLoadedWhentheC++applicationisdynamicallylinkedtotheclientlibrary,thelibrarymustbedynamicallyloadable.
Toensurethattheclientlibraryisavailableforloading,makesureyouhaveaddedthepathproduct-dir /lib totheLD_LIBRARY_PATHenvironmentvariable,whereproduct-dirtotheGemFireproductdirectory.
©CopyrightPivotalSoftwareInc,2013-2019 17 9.1
Page 18
LATESTVERSION:9.1.1- RELEASENOTES
DevelopingC++ProgramsonSolarisThissectiondescribeshowtobuildandrunaclientapplicationonSolaris.
Step1.SetEnvironmentVariablesNote:Whencompilingexternalprojectsorapplicationsthatareusedorreferencedbytheclient,makesurethatyoucompilethemforthesametargetarchitectureasyourclientinstallation.Forexample,ifyouinstalledthe32-bit(x86)versionoftheclient,compileyourexternalprojectsfor32-bit(x86)architecture.
SettheclientenvironmentvariablesoneachSolarishost.Foreachcase,product-diristhepathtotheclientproductdirectory.
ForBourneandKornshells(sh,ksh,bash)
GEODE=product-dir;exportGEODEPATH=$GEODE/bin:$PATH;exportPATHLD_LIBRARY_PATH=$GEODE/lib:$LD_LIBRARY_PATH;exportLD_LIBRARY_PATH
Step2.CompileC++ClientsandDynamicallyLinktoThemtoClientLibraryVersion5.9oftheSUNprocompilerissupportedonSolaris.Thelinkerswitchesvaryaccordingtowhetheryouarestaticallylinkingtotheclientlibrary.
TobuildandlinkaC++clientonSolaris,thecompilationcommandlinemustincludetheappropriateargumentsfromthistable.
Argument Explanation
-D_REENTRANT RequiredtocompileSolarisprogramsinathread-safeway.
-xarch=v8plus Enables32-bitcompilation.
-xarch=v9 Enables64-bitcompilation.
-ldl ; -lpthread ; -lc ; -lm ; -lsocket ; -lrt ; -lnsl ; -ldemangle ; -lkstat ; -lz Additionallibraries.
-library=stlport4 Solarislibrarycompilation.
-I$ GEODE /include SpecifiestheGemFireincludedirectory.
Step3.MakeSuretheClientLibraryCanBeLoadedWhenaC++applicationisnotstaticallylinkedtotheclientlibrary,thelibrarymustbedynamicallyloadable.
Toverifythattheclientlibraryisavailableforloading,makesureyouhaveaddedthepathproduct-dir /lib totheLD_LIBRARY_PATHenvironmentvariable,whereproduct-dirtotheGemFireproductdirectory.
©CopyrightPivotalSoftwareInc,2013-2019 18 9.1
Page 19
LATESTVERSION:9.1.1- RELEASENOTES
DevelopingC++ProgramsonWindowsGemFireusestheVisualStudio2010ServicePack1compilerforC++programsonWindows,whichinvokesMicrosoft cl.exe fromthecommandlineatcompiletime.
TheGemFireclientsupports.NET4.0andVisualStudio2010.Foradvantagesandmoreinformationonthefeaturesof.NET4.0andVisualStudio2010SP1,seehttp://msdn.microsoft.com/en-us/library/dd831853(v=vs.100).aspx andhttp://msdn.microsoft.com/en-us/library/vstudio/w0x726c2(v=vs.100).aspx .
VisualStudio2010SP1istherecommendedcompiler.Ifyouareusinganyothercompiler,contacttechnicalsupportforassistance.
Note:Whencompilingexternalprojectsorapplicationsthatareusedorreferencedbytheclient,makesurethatyoucompilethemforthesametargetarchitectureasyourclientinstallation.Forexample,ifyouinstalledthe32-bit(x86)versionoftheclient,compileyourexternalprojectsfor32-bit(x86)architecture.
Step1.SetUpEnvironmentVariablesAfteryouhavebuilttheclientlibrariesonWindows,performthesetasks:
SettheGEODEenvironmentvariabletoproduct-dir,whereproduct-diristhepathtotheclientproductdirectory.
Addthe%GEODE%\binexecutabledirectorytotheWindowsPATHenvironmentvariable.
Step2.Choose32-bitor64-bitCommand-linePromptFor32-bit:
Start>Programs>MicrosoftVisualStudio>2010>VisualStudioTools>VisualStudio2010CommandPrompt
For64-bit:
Start>Programs>MicrosoftVisualStudio2010>VisualStudioTools>VisualStudio2010x64Win64CommandPrompt
TobuildusingtheMicrosoftVisualStudioInterface,fromtheSolutionsPlatform,chooseWin32orx86fromtheBuildmenufor32-bitbuildsorx64fora64-bitbuild.
Step3.CompileC++ClientsandDynamicallyLinkThemtoClientLibraryThefollowingtableliststhecompilerandlinkerswitchesthatmustbepresentonthe cl.exe commandline.
Note:IfyouwanttousetheVisualStudiouserinterfaceinsteadofinvoking cl.exe fromthecommandline,besuretosupplytheseparameters.
Argument Explanation
/MD Memorymodel.
/EHsc CatchesC++exceptionsonlyandtellsthecompilertoassumethat*extern*CfunctionsneverthrowaC++exception.
/GR Runtimetypeinformation.
-I%GEODE%\include SpecifiestheGemFire include directory.
%GEODE%\lib\pivotalgemfire.lib Specifiesthelibraryfileforthesharedlibrary.
%GEODE%\lib\gfcppcache.lib Specifiesthelibraryfileforthesharedlibrary.
/D_CRT_SECURE_NO_DEPRECATE Suppresseswarnings.RequiredforVisualStudio2010.
/D_CRT_NON_CONFORMING_SWPRINTFS Suppresseswarnings.RequiredforVisualStudio2010.
Step4.VerifythatYouCanLoadtheClientLibraryBecauseGemFiredoesnotprovidealibrarythatcanbelinkedstaticallyintoanapplicationonWindows,youmustdynamicallylinktotheclientlibrary.
Tomaketheclientlibraryavailableforloading,verifythatthedirectory product-dir/bin isincludedinthePATHenvironmentvariable,whereproduct-diristhepathtotheGemFireproductdirectory.
®
©CopyrightPivotalSoftwareInc,2013-2019 19 9.1
Page 20
©CopyrightPivotalSoftwareInc,2013-2019 20 9.1
Page 21
LATESTVERSION:9.1.1- RELEASENOTES
QuickStartExamplesTheQuickStartexamplesdemonstratethecapabilitiesoftheclient,andtheyprovidesourcecodesoyoucanexaminehoweachexampleisdesigned.C++andC#examplesdemonstratehowtheclientperformsasaC++orC#client.
TheexamplescanbeinvokedindividuallyfromthecommandlineorbyusingtheQuickStartmenu.
Theexamplesandtheirsourcefilesarelocatedinthe gc-dir/SampleCode/quickstart directory,wheregc-diristhelocationinwhichyouinstalledtheclient.
TheC++examplesareinthe cpp directory,andtheC#examplesareinthe csharp directory.NotethattheC#examplesareavailableonlyforWindows.
Ineachexample,clientandserverareconfiguredeitherusingapairofcompanionXMLfilesintheXMLs directoryorprogramatically.Forexample, LoaderListenerWriter usesserverLoaderListenerWriter.xml toconfigurethecacheserverand clientLoaderListenerWriter.xml toconfiguretheclient,while BasicOperations uses serverBasicOperations.xml toconfigurethecacheserverandinitializetheclientprogrammatically.Additionalsupportfilesarestoredinthe lib directory.
ConfiguringtheQuickStartEnvironment
ThefollowingcomponentsmustbeinplacetoruntheQuickStartexamplesonanysystem.System-specificconfigurationsfollow.
Forallsystems:
GemFire:InstallandconfigureGemFire.SeetheGemFireUser’sGuideforinstructions.
Cmakeisrequiredtobuildthequickstartexamples.Ifyouhavenotalreadydoneso,downloadandinstallcmake,followingtheinstructionsoncmake.org .
Java:YoumusthaveacompatibleJREorJDKinstalled.SeetheSunJavawebsite forthelatestJavaversionforyouroperatingsystem.SeetheinstallationinformationintheGemFireUser’sGuidefortheversionsofJavathatarecompatiblewithGemFire.
ConfiguringQuickStarts-LinuxandSolarisFollowthesestepstoprepareyourLinuxorSolarisenvironmenttoruntheQuickStartexamples.
1. Startaterminalsession.Setthe GEMFIRE environmentvariabletopointtoyourGemFireproductinstallationdirectory.Setthe GEODE environmentvariabletopointtothesamelocation:%exportGEMFIRE=gemfire-install-dir
%exportGEODE=$GEMFIRE
2. Setthe JAVA_HOME environmentvariabletopointtoyourinstalledJREorJDK.Setthe GFCPP environmentvariabletopointtothedirectoryinwhichyouinstalledthenativeclient,denotedherebync-dir:%exportJAVA_HOME=installed-jre-path
%exportGFCPP=nc-dir
3. Add $GEMFIRE/bin , $JAVA_HOME/bin ,and $GFCPP/bin tothestartofyour PATH :%exportPATH=$GEMFIRE/bin:$JAVA_HOME/bin:$GFCPP/bin:$PATH
4. Createadirectorytoholdthequickstartexamples.Thisdirectory(shownhereas /home/user/quickstart-examples )shouldbecreatedoutsidethenativeclientdirectoryhierarchy.Aftercreatingthedirectory,setitasyourcurrentworkingdirectory:%mkdir/home/user/quickstart-examples-cpp
%cd/home/user/quickstart-examples-cpp
5. Run cmake twice,oncetoconfigurethebuild,thenagaintobuildtheexamples.Onthefirst cmake commandline,whichconfiguresthebuildenvironment,specifythepathtothecmake instructionslocatedinthequickstartexampledirectory(inthiscase,we’rebuildingthe cpp examples),andspecify pivotal-gemfire asthe PRODUCT_LIB_NAME
%cmake-DPRODUCT_LIB_NAME=pivotal-gemfire$GFCPP/SampleCode/quickstart/cpp
...createsamakefileandothersupportingfiles
%cmake--build.
...buildstheexamples
Thiscreatestheexamplesinyourworkingdirectory,plussupportingfilessuchasthe runcpp.sh shellscript.
SeeRunningtheExamplesforinstructionsonrunningtheexamples.
ConfiguringQuickStarts-WindowsFollowthesestepstoprepareyourWindowsenvironmenttoruntheQuickStartexamples.
©CopyrightPivotalSoftwareInc,2013-2019 21 9.1
Page 22
1. RuntheVisualStudioCommandPrompttocreateasessionwithpresetcompilerenvironmentconfigurations.Setthe GEMFIRE environmentvariabletopointtoyourGemFireproductinstallationdirectory.Setthe GEODE environmentvariabletopointtothesamelocation.>setGEMFIRE=gemfire-install-dir
>setGEODE=%GEMFIRE%
2. Setthe JAVA_HOME environmentvariabletopointtoyourinstalledJREorJDK:Setthe GFCPP environmentvariabletopointtothedirectoryinwhichyouinstalledthenativeclient,denotedherebync-dir.>setJAVA_HOME=installed-jre-path
>setGFCPP=nc-dir
3. Add %GEMFIRE%\bin , %JAVA_HOME%\bin ,and %GFCPP%\bin tothestartofyour PATH :>setPATH=%GEMFIRE%\bin;%JAVA_HOME%\bin;%GFCPP%\bin;%PATH%
4. Createadirectorytoholdthequickstartexamples.Thisdirectory(shownhereas c:\quickstart-examples-csharp )shouldbecreatedoutsidethenativeclientdirectoryhierarchy.Aftercreatingthedirectory,setitasyourcurrentworkingdirectory:>mkdirc:\quickstart-examples-csharp
>cdc:\quickstart-examples-csharp
5. Run cmake twice,oncetoconfigurethebuild,thenagaintobuildtheexamples.Onthefirst cmake commandline,whichconfiguresthebuildenvironment,specifythepathtothecmake instructionslocatedinthequickstartexampledirectory.FortheWindowsenvironment,youshouldalsospecifythecmakegenerator, -G"VisualStudio122013Win64"
configurationstep,and --configRelease inthebuildcommand.>cmake-G"VisualStudio122013Win64"-DPRODUCT_DLL_NAME=Pivotal.Gemfire%GFCPP%\SampleCode\quickstart\csharp
...createsamakefileandothersupportingfiles
>cmake--build.--configRelease
...buildstheexamples
Thiscreatestheexamplesinyourworkingdirectory,plussupportingfilessuchasthe runcs.bat script.ForC++quickstarts,use“cpp”and“PRODUCT_LIB_NAME=pivotal-gemfire”andpointtothecppquickstartdirectory:>cmake-G"VisualStudio122013Win64"-DPRODUCT_LIB_NAME=pivotal-gemfire%GFCPP%\SampleCode\quickstart\cpp
...createsamakefileandothersupportingfiles
>cmake--build.--configRelease
...buildstheexamples
Thiscreatestheexamplesinyourworkingdirectory,plussupportingfilessuchasthe runcpp.bat script.
SeeRunningtheExamplesforinstructionsonrunningtheexamples.
AbouttheQuickStartExamples
Theexamplesarebrieflydescribedinthissection.Eachexampleperformsthefollowingsteps:
1. Startsthecacheserverwiththeexample’sserverXML.
2. CreatesaGemFirecache.
3. Performsoperationsspecifictotheexample.
4. ClosestheGemFirecache.
5. Shutsdownthecacheserver.
Notethemessagesthatappearintheexample’ssessionasitrunsandperformsthestepsinthelist.
BasicOperationsTheBasicOperationsexampleputsentries(keyandvaluepairs)intoaregion,getsentriesfromtheregion,invalidatesanentryintheregion,anddestroysanentryintheregion.
TheBasicOperationsexampleusesthebuilt-inserializabletypes CacheableInt32 and CacheableString .Thereareotherbuilt-intypeswhichcanbeusedforanentry.Sometypescanbeusedaskeysorvalues,whileotherscanonlybeusedasvalues.Thetypesarelistedinthefollowingtable:
Built-InSerializableTypes
CacheableTypesForKeysorValues CacheableTypesOnlyForValues
CacheableInt32 CacheableBytes
CacheableString CacheableDoubleArray
CacheableBoolean CacheableFloatArray
CacheableByte CacheableInt16Array
©CopyrightPivotalSoftwareInc,2013-2019 22 9.1
Page 23
CacheableDouble CacheableInt32Array
CacheableFloat CacheableInt64Array
CacheableInt16 CacheableStringArray
CacheableInt64 CacheableObjectArray
CacheableWideChar CacheableVector
CacheableDate CacheableHashMap
CacheableFileName CacheableHashSet
CacheableTypesForKeysorValues CacheableTypesOnlyForValues
Youcanalsoprovideyourownserializableobjects.Examplesofcustomserializableobjectsare Position and Portfolio intheRemoteQueryexample.Formoreinformationregardingserialization,refertoSerializingData andtheonlineAPIdocumentationfortheclient.
DataExpirationTheDataExpirationexampleisconfiguredwithanexpirationactionofdestroythathasa10-secondtimeout.Itperformsthefollowingoperations:
1. Setsthe SimpleCacheListener pluginonaregion
2. Putsthreeentriesintotheregion
3. Getstheentryidletimeoutsettingfromtheregion
4. Countsthekeysintheregionbeforethetimeoutdurationelapses
5. Waitsforthetimeoutexpirationactiontobereportedbythe SimpleCacheListener
6. Countstheremainingkeysintheregionafterthetimeoutdurationelapses
Multipleevictionactionoptionsareavailable,includingoverflow.Fordetailedinformation,seeSpecifyingExpirationAttributes .
LoaderListenerWriterTheLoaderListenerWriterexamplesetstheSimpleCacheLoader,SimpleCacheListener,andSimpleCacheWriterpluginsonaregion.Thesepluginsreporttheeventsthatoccurduringthefollowingregionoperations:
PutthreeentriesintotheregionUpdateanentryintheregionDestroyanentryintheregionInvalidateanentryintheregionGetanewentryfromtheregionGetthedestroyedentryfromtheregion
RegisterInterestTheRegisterInterestexamplecallstheinterestAPIonaregion.Thesearethefunctionsthatarecalled:
registerAllKeysunregisterAllKeysregisterKeysunregisterKeysregisterRegexunregisterRegex
RemoteQueryTheRemoteQueryexamplepopulatessomequeryobjectsonaregion,executesaquerythatreturnsa ResultSet ,executesaquerythatreturnsa StructSet ,andexecutestheregionshortcutquerymethods.
ContinuousQueryTheCqQueryexampledemonstratethecontinuousqueryAPIs.
©CopyrightPivotalSoftwareInc,2013-2019 23 9.1
Page 24
FunctionExecutionTheExecuteFunctionsexampledemonstratesthefunctionexecutionAPIs.
HACacheTheHACacheexampleusesclientandserverXMLsconfiguredtoprovidehighavailabilityfunctionalityforclientqueues.TheexamplecallstheinterestAPIonaregionanddoessimpleputs.
ExceptionsTheExceptionsexampleperformssomeoperationsinincorrectways,thenlogstheexceptionsthrownbyGemFiretodemonstrateerrorhandling.
DurableClientTheDurableClientexampledemonstratesdurableclientmessaging.Iftheclientlosesitsconnectionwithacacheserver,theprimaryserverandanyredundantserversmaintainaneventqueueuntiltheclientreconnects.Thequeuedmessagesarethensenttotheclient.Thisexampledemonstratesthefollowingfunctionality:
Durableclientproperties( durable-client-id , durable-timeout )
readyForEvents cacheAPI
RegisterinterestAPIswiththe isDurable option
CachecloseAPIwiththe keepalive option
CacheListener withthe afterRegionLive API
PutAllAndGetAllOperationsThePutAllGetAllOperationsexampledemonstrates PutAll and GetAll operations
1. TheClientisinitializedprogrammaticallyratherthandeclaratively
2. PutAlliscalledwith100entriesintotheregion
3. GetAlliscalledwith100entriesfromtheregion
DistributedSystemTheDistributedSystemexampledemonstrateshowclientcanconnecttotwodistributedsystems.
1. Clientcreatestheinstanceofcache.
2. Clientcreatestwodifferentregionsintwodifferentdistributedsystems.
3. Clientcreatesbasicput-getoperationsonthoseregionsandclosestheinstanceofcache.
PoolWithEndpointsThisexampledemonstrateshowclientcancreateprogramaticallypoolwithendpoints.
1. Clientcreatestheinstanceofcache.
2. Clientcreatespoolfactorywithendpoints.
3. Clientcreatespoolusingthispoolfactory.
4. Clientcreatesregionwithpoolanddoesput-getoperationsonthisregion.
©CopyrightPivotalSoftwareInc,2013-2019 24 9.1
Page 25
PoolRemoteQueryThisexampledemonstrateshowclientcancreateapoolwithalocatorusingXML.Itthendemonstrateshowitcanexecuteaqueryonaregion(attachedwithpool).
1. ClientcreatestheinstanceofcacheusingXML.
2. Clientgetsregionfromthecache.
3. Clientputssomedatainthecache.
4. Clientgets queryService fromcacheandexecutessomequeries.
PoolContinuousQueryThePoolCqQueryexampledemonstratesthecontinuousquerywithPoolAPIs.
DeltaPropagationTheDeltaexampleshowshowachangeinavaluestoredinaclientcanbepropagatedtotheserver.Intheexample,asinglefieldofanexistingvalueinaregionismodified,andthedeltaforthevalue(whichisthenewvaluefortheupdatedfield)ispropagatedtotheserverinaputoperation.
RefIDExampleTheRefIDExampleexampleshowshowtodeclarativelyintializetheRegionusing refid .
TransactionsTheTransactionsexampleshowstheuseoftheclient-servertransactionsAPI.
PdxRemoteQueryThePdxRemoteQueryexampleshowstheuseofPDXserializedobjectswithGemFirequerying.
PdxSerializerThePdxSerializerexampleshowstheuseofanexternalPDXserializerforuserdomainclassesthataren’tmodifiedtoimplementthe IPdxSerializable interface.
PdxInstanceThePdxInstanceexampleshowstheabilityofclientstoworkwithPDXserializedobjectswithouthavingtheactualdomainclassesavailable.
RunningtheExamples
YoucanrunthequickstartexamplesbystartingeachC++orC#exampleindividuallyfromthecommandlineorbystartingtheexamplesfromamenu.Themenuprovidesanumberedlistoftheexamplenames,soyoujustentertheexamplenumbertostartit.
TheC#examplesareavailableonlyforWindows.
RunninganExampleFromtheCommandLineC++examples
©CopyrightPivotalSoftwareInc,2013-2019 25 9.1
Page 26
ForWindows: runcppExampleName (forexample, runcppDataExpiration
)
ForLinuxorSolaris: ./runcpp.shExampleName (forexample, ./runcpp.shDataExpiration
)
C#examples
runcsExampleName (forexample, runcsRemoteQuery )
RunningaC++ExampleFromtheMenuForWindows:
StarttheC++menu.
>runcppPleaseselectaGemFireC++QuickStartexampletorun.
1.BasicOperations2.DataExpiration3.LoaderListenerWriter...25.Quit
Enteroption:
Enteranumberfromthelisttostartthatexample.
ForLinuxorSolaris:
StarttheC++menu.
$./runcpp.shPleaseselectaGemFireC++QuickStartexampletorun.
1.BasicOperations2.DataExpiration3.LoaderListenerWriter...25.Quit
Enteroption:
Enteranumberfromthelisttostartthatexample
RunningaC#ExampleFromtheMenu
StarttheC#menu.
>runcsPleaseselectaGemFireC#QuickStartexampletorun.
1.BasicOperations2.DataExpiration3.LoaderListenerWriter...25.Quit
Enteroption:
Enteranumberfromthelisttostartthatexample.
©CopyrightPivotalSoftwareInc,2013-2019 26 9.1
Page 27
IfyouhaveproblemsrunningtheexamplesThissectiondiscussesproblemsyoumightencounterwhenyouruntheexamples,andsuggestscorrectiveactions.Ifyourproblemsaren’tcoveredorresolvedhere,pleasecontactPivotalTechnicalSupport.Forinstructions,seethePivotalpageHowtoFileaSupportRequest.
ErrorMessagesException...Region:putnotconnectedtoGemFire
Verifythatthecacheserverhassuccessfullystartedbyreviewingthecacheserver.logfileinthegfecsdirectory.Thelogmayindicatewhythecacheserverfailedtostart.
Exception...NoClassDefFoundError
Thiserrormayappearinthe cacheserver.log fileinthe gfecs directory.VerifythatyouhavefollowedallthestepsintheConfiguringtheQuickStartEnvironmentsection.Youmustruntheexamplefromthequickstartdirectorywiththe runcpp or runcs scriptforthe CLASSPATH settingtowork,andsotheexamplecanfinditsXMLfiles.
Exception...XMLfile/resourcedoesnotexistornotfound
Thiserrormightappearinthe cacheserver.log fileinthe gfecs directory,orintheexample’sscreenoutput.VerifythatyouhavefollowedallthestepsintheConfiguringtheQuickStartEnvironmentsection.Youmustruntheexamplefromthequickstartdirectorywiththe runcpp or runcs scriptsotheexamplecanfinditsXMLfiles.
ConnectionProblemsGemFireisanetwork-centricdistributedsystem,soifyouhaveafirewallrunningitcouldcauseconnectionproblems.Forexample,yourconnectionsmayfailifyourfirewallplacesrestrictionsoninboundoroutboundpermissionsforsockets.Youmayneedtomodifyyourfirewallconfigurationtopermittraffictoapplicationsrunningonyourmachine.Thespecificconfigurationdependsonthefirewallyou’reusing.
Ifyouexperienceportconflictswithotherdistributedsystems,changethe localhost and bridge-server portnumbersforeachoftheXMLfilesinthe quickstart/XMLs directory.Ifyouneedtospecifyanon-defaultmulticastportsettingfortheJavacacheserver,placeacopyoftheGemFire gemfire.properties fileinthe quickstart/gfecs directory,thenchangethesettingtoauniquevalueforyournetwork.
©CopyrightPivotalSoftwareInc,2013-2019 27 9.1
Page 28
LATESTVERSION:9.1.1- RELEASENOTES
SettingSystemPropertiesThissectiondescribeshowtoconfigureclientsandcacheserverstoparticipateinadistributedsystem.
ConfiguringtheClientandServerYoucanconfigureclientsthroughfilesandAPIcalls.Theserversareconfiguredthroughcommand-lineinputandconfigurationfiles.
AttributesinthePropertiesFileAvarietyof geode.properties settingscanbeusedwhenaclientconnectstoadistributedsystem.
PropertiesFileExampleUsethegeode.propertiesfiletoconfiguredistributedsystemconnectionsfortheclient.
©CopyrightPivotalSoftwareInc,2013-2019 28 9.1
Page 29
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringtheClientandServerYoucanconfigureclientsthroughfilesandAPIcalls.Theserversareconfiguredthroughcommand-lineinputandconfigurationfiles.
ClientConfigurationYouconfiguretheclientintwofiles: geode.properties forsystem-levelconfigurationand cache.xml forcache-levelconfiguration.
CacheServerConfigurationYouconfigurethecacheserverintwofiles: gemfire.properties forserversystem-levelconfigurationand cache.xml forcache-levelconfiguration.
AttributeDefinitionPriorityYoucanspecifyattributesindifferentways,whichcancauseconflictingdefinitions.Applicationscanbeconfiguredprogrammatically,andthathaspriorityoverothersettings.
SearchPathforMultiplePropertiesFilesTheclientandserverprocessesfirstlookfortheirpropertiesfileinthe product-dir/defaultSystem directory,thenintheworkingdirectory.
OverridingPropertiesFileSettingsApplicationdevelopershavetheoptionofconfiguringsystemattributesprogrammatically,ratherthanusingthe geode.properties file.
DefiningPropertiesProgrammaticallyYoucanpassinspecificpropertiesprogrammaticallybyusinga Properties objecttodefinethenon-defaultproperties.
©CopyrightPivotalSoftwareInc,2013-2019 29 9.1
Page 30
LATESTVERSION:9.1.1- RELEASENOTES
ClientConfigurationYouconfiguretheclientintwofiles: geode.properties forsystem-levelconfigurationand cache.xml forcache-levelconfiguration.
Theconfigurationofthecachesispartoftheapplicationdevelopmentprocess.SeeCacheInitializationFile(cache.xml).(Thecache-levelconfigurationfileisgenerallyreferredtoascache.xml ,butyoucanuseanyname.)
Aboutthegeode.propertiesConfigurationFileThe geode.properties fileprovideslocalsettingsrequiredtoconnectaclienttoadistributedsystem,alongwithsettingsforlicensing,logging,andstatistics.SeeAttributesinthePropertiesFile.
Theapplicationsoftwaremayincludeasetof geode.properties files.Yousetanyattributesneededfortheapplicationdesigninthesefiles,thenyoucanaddanyattributesneededforthelocalsite.
Ifyoudonothave geode.properties files,useanytexteditortocreatethem.SeePropertiesFileExampleforasampleofthefileformatandcontents.
ConfigurationFileLocationsAclientlooksfora geode.properties filefirstintheworkingdirectorywheretheprocessruns,thenin product-dir/defaultSystem .Usethe defaultSystem directorytogroupconfigurationfilesortosharethemamongprocessesformoreconvenientadministration.If geode.properties isnotfound,theprocessstartsupwiththedefaultsettings.
Forthe cache.xml cacheconfigurationfile,aclientlooksforthepathspecifiedbythe cache-xml-file attributein geode.properties (seeAttributesinthePropertiesFile).Ifthenotfound,theprocessstartswithanunconfiguredcache.
ConfiguringSystemPropertiesfortheClientThetypicalconfigurationprocedureforaclientincludesthehigh-levelstepslistedbelow.Therestofthischapterprovidesthedetails.
1. Placethe geode.properties filefortheapplicationintheworkingdirectoryorin product-dir/defaultSystem .Usetheconfigurationfilethatcamewiththeapplicationsoftwareifthereisone,orcreateyourown.SeePropertiesFileExampleforasampleofthefileformatandcontents.
2. Placethe cache.xml filefortheapplicationinthedesiredlocationandspecifyitspathinthe geode.properties file.
3. Addotherattributestothe geode.properties fileasneededforthelocalsystemarchitecture.SeeAttributesinthePropertiesFilefortheconfigurableattributes,andFileExampleforasampleofthefileformat.
RunningaClientOutoftheBoxIfyoustartaclientwithoutanyconfiguration,itusesanyattributessetprogrammaticallyplusanyhard-codeddefaults(listedinAttributesinthePropertiesFile).Runningwiththedefaultsisaconvenientwaytolearntheoperationofthedistributedsystemandtotestwhichattributesneedtobereconfiguredforyourenvironment.
©CopyrightPivotalSoftwareInc,2013-2019 30 9.1
Page 31
LATESTVERSION:9.1.1- RELEASENOTES
CacheServerConfigurationYouconfigurethecacheserverintwofiles: gemfire.properties forserversystem-levelconfigurationand cache.xml forcache-levelconfiguration.
Theconfigurationofthecachesispartoftheapplicationdevelopmentprocess.SeeCacheInitializationFile(cache.xml).Thecache-levelconfigurationfileisgenerallyreferredtoascache.xml ,butyoucanuseanyname.
ConfigurationFileLocationsForthecacheserver,the gemfire.properties fileisusuallystoredinthecurrentworkingdirectory.
Forthe cache.xml configurationfile,aclientlooksforthepathspecifiedbythe cache-xml-file attributein geode.properties (seeAttributesinthePropertiesFile).Ifthe cache.xmlfound,theprocessstartswithanunconfiguredcache.
ModifyingAttributesOutsidethegemfire.propertiesFileInadditiontothe gemfire.properties
file,youcanpassattributestothecacheserveronthegfshcommandline.Theseoverrideanysettingsfoundinthe gemfire.properties filewhenstarting
thecacheserver.
©CopyrightPivotalSoftwareInc,2013-2019 31 9.1
Page 32
LATESTVERSION:9.1.1- RELEASENOTES
AttributeDefinitionPriorityYoucanspecifyattributesindifferentways,whichcancauseconflictingdefinitions.Applicationscanbeconfiguredprogrammatically,andthathaspriorityoverothersettings.
Incaseanattributeisdefinedinmorethanoneplace,thefirstsourceinthislistisused:
Programmaticconfiguration
Propertiessetatthecommandline
current-working-directory/geode.properties file
product-dir/defaultSystem/geode.properties file
defaults
The geode.properties filesandprogrammaticconfigurationareoptional.Iftheyarenotpresent,nowarningsorerrorsoccur.FordetailsonprogrammaticconfigurationthroughtheProperties object,seeDefiningPropertiesProgrammatically.
©CopyrightPivotalSoftwareInc,2013-2019 32 9.1
Page 33
LATESTVERSION:9.1.1- RELEASENOTES
SearchPathforMultiplePropertiesFilesTheclientandcacheserverprocessesfirstlookfortheirpropertiesfileinthe product-dir/defaultSystem directory,thenintheworkingdirectory.
Anypropertiessetintheworkingdirectoryoverridesettingsinthe defaultSystem/geode.properties file.
Ifyouarerunningmultipleprocessesononemachine,youcanconfigurethe geode.properties fileinthe defaultSystem directoryasasharedfilethatallprocessescanfind.Ifafewprocessesneedaslightlydifferentconfiguration,youcanputindividual geode.properties filesintheirhomedirectoriestooverridespecificproperties.
©CopyrightPivotalSoftwareInc,2013-2019 33 9.1
Page 34
LATESTVERSION:9.1.1- RELEASENOTES
OverridingPropertiesFileSettingsApplicationdevelopershavetheoptionofconfiguringsystemattributesprogrammatically,ratherthanusingthe geode.properties file.
Attributessetprogrammaticallyoverrideanymatchingattributesettingsinthe geode.properties file,butadditionalattributesnotsetprogrammaticallywillbeconfiguredusingthesettingsin geode.properties .
©CopyrightPivotalSoftwareInc,2013-2019 34 9.1
Page 35
LATESTVERSION:9.1.1- RELEASENOTES
DefiningPropertiesProgrammaticallyYoucanpassinspecificpropertiesprogrammaticallybyusinga Properties objecttodefinethenon-defaultproperties.
Example:
PropertiesPtrsystemProps=Properties::create();systemProps->insert("statistic-archive-file","stats.gfs");systemProps->insert("cache-xml-file","./myapp-cache.xml");systemProps->insert("stacktrace-enabled","true");CacheFactoryPtrsystemPtr=CacheFactory::createCacheFactory(systemProps);
©CopyrightPivotalSoftwareInc,2013-2019 35 9.1
Page 36
LATESTVERSION:9.1.1- RELEASENOTES
AttributesinthePropertiesFileAvarietyof geode.properties settingscanbeusedwhenaclientconnectstoadistributedsystem.
Thefollowingsettingscanbeconfigured:
GeneralPropertiesBasicinformationfortheprocess,suchascachecreationparameters.
LoggingPropertiesHowandwheretologsystemmessages.
StatisticsArchivingPropertiesHowtocollectandarchivestatisticsinformation.
DurableClientPropertiesInformationaboutthedurableclientsconnectedtothesystem.
SecurityPropertiesInformationaboutvarioussecurityparameters.
AttributeDefinitionsThefollowingtableslistattributesthatcanbestoredinthe geode.properties filetobereadbyaclient.
Forthesystempropertiesthatrelatetohighavailability,seeSendingPeriodicAcknowledgement.Foralistofsecurity-relatedsystempropertiesandtheirdescriptions,seethetableSystemPropertiesforClientAuthenticationandAuthorization.
Table1.Attributesingeode.properties—GeneralProperties
appdomain-enabledIf true ,allowsclienttoworkwhenmultiple.NETappdomainsareinuse.
false
cache-xml-file
Nameandpathofthefilewhosecontentsareusedbydefaulttoinitializeacacheifoneiscreated.Ifnotspecified,theclientstartswithanemptycache,whichispopulatedatruntime.
SeeCacheInitializationFileformoreinformationonthecacheinitializationfile.
nodefault
heap-lru-delta
WhenheapLRUistriggered,thisistheamountthatgetsaddedtothepercentagethatisabovetheheap-lru-limit amount.LRUcontinuesuntilthe
memoryusageisbelow heap-lru-limit minusthispercentage.Thispropertyisonlyusedifheap-lru-limit isgreaterthan0.
10
heap-lru-limit
Maximumamountofmemory,inmegabytes,usedbythecacheforallregions.Ifthislimitisexceededbyheap-lru-delta percent,LRUreducesthememoryfootprintasnecessary.Ifnotspecified,orsetto0,memoryusageisgovernedbyeachregion’sLRUentrieslimit,ifany.
0
conflate-events Clientsideconflationsetting,whichissenttotheserver. server
connect-timeoutAmountoftime(inseconds)towaitforaresponseafterasocketconnectionattempt.
59
connection-pool-size Numberofconnectionsperendpoint 5
crash-dump-enabledWhethercrashdumpgenerationforunhandledfatalerrorsisenabled.Trueisenabled,falseotherwise.
true
disable-chunk-handler-threadWhensettofalse,eachapplicationthreadprocessesitsownresponse.Ifsettotrue,thechunk-handler-threadprocessestheresponseforeachapplicationthread.
false
disable-shuffling-of-endpointsIftrue,preventsserverendpointsthatareconfiguredinpoolsfrombeingshuffledbeforeuse.
false
max-fe-threadsThreadpoolsizeforparallelfunctionexecution.AnexampleofthisistheGetAlloperations.
2*numberofCPUcores
©CopyrightPivotalSoftwareInc,2013-2019 36 9.1
Page 37
exampleofthisistheGetAlloperations.
max-socket-buffer-sizeMaximumsizeofthesocketbuffers,inbytes,thattheclientwilltrytosetforclient-serverconnections.
65*1024
notify-ack-intervalInterval,inseconds,inwhichclientsendsacknowledgmentsforsubscriptionnotifications.
1
notify-dupcheck-lifeAmountoftime,inseconds,theclienttrackssubscriptionnotificationsbeforedroppingtheduplicates.
300
ping-interval
Interval,inseconds,betweencommunicationattemptswiththeservertoshowtheclientisalive.Pingsareonlysentwhenthe ping-interval elapsesbetweennormalclientmessages.Thismustbesetlowerthantheserver’smaximum-time-between-pings .
10
redundancy-monitor-intervalInterval,inseconds,atwhichthesubscriptionHAmaintenancethreadchecksfortheconfigured
redundancyofsubscriptionservers.
10
stacktrace-enabled
If true ,theexceptionclassescaptureastacktracethatcanbeprintedwiththeir printStackTrace function.Iffalse,thefunctionprintsamessagethatthetraceisunavailable.
false
tombstone-timeoutTimeinmillisecondsusedtotimeouttombstoneentrieswhenregionconsistencycheckingisenabled.
480000
Table2.Attributesingeode.properties—LoggingProperties
log-disk-space-limitMaximumamountofdiskspace,inmegabytes,allowedforalllogfiles,current,androlled.Ifsetto0,thespaceisunlimited.
0
log-fileNameandfullpathofthefilewherearunningclientwriteslogmessages.Ifnotspecified,logginggoestostdout .
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
Table3.Attributesingeode.properties—StatisticsArchivingProperties
statistic-sampling-enabledControlswhethertheprocesscreatesastatisticarchivefile.
true
Nameandfullpathofthefilewherearunningsystem
©CopyrightPivotalSoftwareInc,2013-2019 37 9.1
Page 38
statistic-archive-file
Nameandfullpathofthefilewherearunningsystemmemberwritesarchivesstatistics.Ifarchive-disk-space-limit isnotset,theclientappendstheprocessIDtotheconfiguredfilename,likestatArchive-PID.gfs .Ifthespacelimitisset,theprocessIDisnotappendedbuteachrolledfilenameisrenamedtostatArchive-ID.gfs,whereIDistherollednumberofthefile.
./statArchive.gfs
archive-disk-space-limitMaximumamountofdiskspace,inmegabytes,allowedforallarchivefiles,current,androlled.Ifsetto0,thespaceisunlimited.
0
archive-file-size-limit
Maximumsize,inbytes,ofasinglestatisticarchivefile.Oncethislimitisexceeded,anewstatisticarchivefileiscreatedandthecurrentarchivefilebecomesinactive.Ifsetto0,thefilesizeisunlimited.
0
statistic-sample-rate
Rate,inseconds,thatstatisticsaresampled.Operatingsystemstatisticsareupdatedonlywhenasampleistaken.Ifstatisticarchivalisenabled,thenthesesamplesarewrittentothearchive.
Loweringthesamplerateforstatisticsreducessystemresourceusewhilestillprovidingsomestatisticsforsystemtuningandfailureanalysis.
1
enable-time-statisticsEnablestime-basedstatisticsforthedistributedsystemandcaching.Forperformancereasons,time-basedstatisticsaredisabledbydefault.SeeSystemStatistics.
false
Table4.Attributesingeode.properties—DurableClientProperties
geode.propertiesAttribute Description
auto-ready-for-events
WhetherclientsubscriptionsautomaticallyreceiveeventswhendeclarativelyconfiguredviaXML.Ifsetto false ,eventstartupisnotautomaticandyouneedtocallthe Cache.ReadyForEvents() methodAPIaftersubscriptionsfortheservertostartdeliveringevents.
durable-client-id Identifiertospecifyifyouwanttheclienttobedurable.
durable-timeout Time,inseconds,adurableclient’ssubscriptionismaintainedwhenitisnotconnectedtotheserverbeforebeingdropped.
Table5.Attributesingeode.properties—SecurityProperties
geode.propertiesAttribute Description
security-client-dhalgo Diffie-Hellmansecretkeyalgorithm.
security-client-kspath keystore(.pemfile)path.
security-client-auth-factory Factorymethodforthesecurity AuthInitialize module.
security-client-auth-library Pathtotheclientsecuritylibraryforthe AuthInitialize module.
ssl-keystore-password Keystorepassword.
©CopyrightPivotalSoftwareInc,2013-2019 38 9.1
Page 39
LATESTVERSION:9.1.1- RELEASENOTES
PropertiesFileExampleUsethe geode.properties filetoconfiguredistributedsystemconnectionsfortheclient.
Thefollowingexampleshowstheformatofageode.propertiesfile.Thefirsttwoattributesinthisexampleshouldbesetbyprogrammersduringapplicationdevelopment,whileotherattributesareseton-siteduringsystemintegration.ThepropertiesandtheirdefaultsettingsthatcanbesetinthisfilearedescribedindetailinAttributesintheProperitesFile
geode.propertiesFileFormat
#TueFeb1417:24:02PDT2006log-level=infocache-xml-file=./cache.xmlstacktrace-enabled=true
©CopyrightPivotalSoftwareInc,2013-2019 39 9.1
Page 40
LATESTVERSION:9.1.1- RELEASENOTES
UsingtheDefaultSampleFileAsample geode.properties fileisincludedwiththePivotalGemFirenativeclientinstallationinthe product-dir/defaultSystem directory.
Tousethisfile:
1. Copythefiletothedirectorywhereyoustarttheapplication.
2. Uncommentthelinesyouneedandeditthesettingsasshowninthisexample:
cache-xml-file=test.xml
3. Starttheapplication.
Defaultgeode.propertiesFile
©CopyrightPivotalSoftwareInc,2013-2019 40 9.1
Page 41
#DefaultC++distributedsystemproperties#Copytocurrentdirectoryanduncommenttooverridedefaults.###Debuggingsupport,enablesstacktracesingemfire::Exception.##Thedefaultisfalse,uncommenttoenablestacktracesinexceptions.#stacktrace-enabled=true#crash-dump-enabled=true####Cacheregionconfigurtion##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###Statisticsvalues##therateisinseconds.#statistic-sample-rate=1#statistic-sampling-enabled=true#statistic-archive-file=statArchive.gfs#zeroindicatesusenolimit.#archive-file-size-limit=0#zeroindicatesusenolimit.#archive-disk-space-limit=0#enable-time-statistics=false###Heapbasedevictionconfiguration##maximumamountofmemoryusedbythecacheforallregions,0disablesthisfeature#heap-lru-limit=0#percentageoverheap-lru-limitwhenLRUwillbecalled.#heap-lru-delta=10###Durableclientsupport##durable-client-id=#durable-timeout=300###SSLsocketsupport##ssl-enabled=false#ssl-keystore=#ssl-truststore=###.NETAppDomainsupport##appdomain-enabled=false###Misc##conflate-events=server#disable-shuffling-of-endpoints=false#max-fe-threads=#max-socket-buffer-size=66560#theunitsareinseconds.#connect-timeout=59#notify-ack-interval=10#notify-dupcheck-life=300#ping-interval=10#redundancy-monitor-interval=10#auto-ready-for-events=true###modulenameoftheinitializerpointingtosample##implementationfromtemplates/security#security-client-auth-library=securityImpl##staticmethodnameofthelibrarymentionedabove#security-client-auth-factory=createUserPasswordAuthInitInstance##credentialforDummyAuthenticatorconfiguredinserver.##note:security-passwordpropertywillbeinsertedbytheinitializer##mentionedintheaboveproperty.#security-username=root
©CopyrightPivotalSoftwareInc,2013-2019 41 9.1
Page 42
©CopyrightPivotalSoftwareInc,2013-2019 42 9.1
Page 43
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringtheNativeClientCacheThissectiondescribestheclientcachefunctionality,initializationfile,andAPIs.Itprovidesinformationaboutcreatingandworkingwithcaches,cacheregions,andregionentries.
Theclientcacheprovidesaframeworkforclientstostore,manage,anddistributeapplicationdata.
CachesThecacheistheentrypointtodatacachinginGemFire.Throughthecache,clientsgainaccesstotheGemFirecachingframeworkfordataloading,distribution,andmaintenance.
CacheInitializationFile(cache.xml)Toeasethetaskofmanagingthestructureofthecache,youcandefinethedefaultGemFirecachestructureinanXML-basedinitializationfile.
RegionsYoucreatecacheregionseitherprogrammaticallyorthroughdeclarativestatementsinthe cache.xml file.Generally,acacheisorganizedandpopulatedthroughacombinationofthetwoapproaches.
RegionEntriesRegionentriesholdcachedapplicationdata.Entriesareautomaticallymanagedaccordingtoregionattributesettings.
RegionConsistencyGemFireensuresthatallcopiesofaregioneventuallyreachaconsistentstateonallmembersandclientsthathosttheregion.
RegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.
CacheManagementThissectioncoverscachemanagement.
©CopyrightPivotalSoftwareInc,2013-2019 43 9.1
Page 44
LATESTVERSION:9.1.1- RELEASENOTES
CachesThecacheistheentrypointtodatacachinginGemFire.Throughthecache,clientsgainaccesstotheGemFirecachingframeworkfordataloading,distribution,andmaintenance.
AbouttheClientCacheThecacheconsistsofdataregions,eachofwhichcancontainanynumberofentries.Regionentriesholdthecacheddata.Everyentryhasakeythatuniquelyidentifiesitwithintheregionandavaluewherethedataobjectisstored.
CacheAPIsTheclienthastwocacheAPIs, RegionService and Cache .
Local,Remote,andDistributedCachesThedistributedsystemdefineshowclientandcacheserverprocessesfindeachother.
CreatingandAccessingaCacheWhenyoucreateaclientcache,youarecreatingaclientcacheinstance.Youmustprovidesomebasicconfigurationinformationsuchasaconnectionnameandcacheinitializationparametersfortheclient’scacheinstance.
ClosingtheCacheUsethe Cache::close functiontoreleasesystemresourceswhenyoufinishusingthecache.
©CopyrightPivotalSoftwareInc,2013-2019 44 9.1
Page 45
LATESTVERSION:9.1.1- RELEASENOTES
AbouttheClientCacheThecacheconsistsofdataregions,eachofwhichcancontainanynumberofentries.Regionentriesholdthecacheddata.Everyentryhasakeythatuniquelyidentifiesitwithintheregionandavaluewherethedataobjectisstored.
The Cache instanceallowsyourprocesstosetgeneralparametersforcommunicationbetweenacacheandothercachesinthedistributedsystem,andtocreateandaccessanyregioninthecache.
Regionsarecreatedfromthe Cache instance.Regionsprovidetheentrypointtotheinterfacesforinstancesof Region and RegionEntry .
MainFeaturesandFunctionalityTheclientcacheprovidesthefollowingfeaturesandfunctionality.
Localanddistributeddatacachingforfastaccess.
Datadistributionbetweenapplicationsonthesameordifferentplatforms.
Localandremotedataloadingthroughapplicationplug-ins.
Applicationplug-insforsynchronousandasynchronoushandlingofdataevents.
Automatedandapplication-specificdataevictionforfreeingupspaceinthecache,includingoptionaloverflowtodisk.
Systemmessagelogging,andstatisticsgatheringandarchiving.
Formoreinformationspecifictoyourclientprogramminglanguage,seeC++ClientAPIor.NETClientAPI.
©CopyrightPivotalSoftwareInc,2013-2019 45 9.1
Page 46
LATESTVERSION:9.1.1- RELEASENOTES
CacheAPIsTheclienthastwocacheAPIs, RegionService and Cache .
RegionServiceAPIRegionService provides:
Accesstoexistingcacheregions.
Accesstothequeryserviceforthecache,whichsendsqueriestotheservers.SeeRemoteQueryingandContinuousQuerying.
RegionService isinheritedby Cache .
Youdonotuseinstancesof RegionService exceptforsecureclientapplicationswithmanyusers.SeeCreatingMultipleSecureUserConnectionswithRegionService.
CacheAPIUsethe Cache tomanageyourclientcaches.Youhaveone Cache perclient.
The Cache inherits RegionService andaddsmanagementoftheseclientcachingfeatures:
Regioncreation.
Subscriptionkeepalivemanagementfordurableclients.
Accesstotheunderlyingdistributedsystem.
RegionService creationforsecureaccessbymultipleusers.
©CopyrightPivotalSoftwareInc,2013-2019 46 9.1
Page 47
LATESTVERSION:9.1.1- RELEASENOTES
Local,Remote,andDistributedCachesThedistributedsystemdefineshowclientandserverprocessesfindeachother.
Thedistributedsystemkeepstrackofitsmembershiplistandmakesitsmembersawareoftheidentitiesoftheothermembersinthedistributedsystem.
Acachewithintheclientisreferredtoasitslocalcache.Allothercachesinthedistributedsystemareconsideredremotecachestotheapplication.Everycacheserverandapplicationprocesshasitsowncache.Thetermdistributedcacheisusedtodescribetheunionofallcachesinthedistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 47 9.1
Page 48
LATESTVERSION:9.1.1- RELEASENOTES
CreatingandAccessingaCacheWhenyoucreateaclientcache,youarecreatingaclientcacheinstance.Youmustprovidesomebasicconfigurationinformationsuchasaconnectionnameandcacheinitializationparametersfortheclient’scacheinstance.
Whenyoucreateacache,youprovidethefollowinginput:
Connectionname.Usedinloggingtoidentifyboththedistributedsystemconnectionandthecacheinstance.Ifyoudonotspecifyaconnectionname,aunique(butnon-descriptive)defaultnameisassigned.
cache.xml toinitializethecache(iftheinitializationisnotdoneprogrammatically).Tomodifythecachestructure,edit cache.xml inyourpreferredtexteditor.Nochangestotheapplicationcodearerequired.Ifyoudonotspecifya cache.xml file,youneedtoinitializethecacheprogrammatically.
The cache.xml filecontainsXMLdeclarationsforcache,region,andregionentryconfiguration.
ThisXMLdeclaresserverconnectionpoolsandregions:
<cache><regionname="clientRegion1"refid="PROXY"><region-attributespool-name="serverPool1"/></region><regionname="clientRegion2"refid="PROXY"><region-attributespool-name="serverPool2"/></region><regionname="localRegion3"refid="LOCAL"/><poolname="serverPool1"><locatorhost="host1"port="40404"/></pool><poolname="serverPool2"><locatorhost="host2"port="40404"/></pool></cache>
Whenyouusetheregions,theclientregionsconnecttotheserversthroughthepoolsnamedintheirconfigurations.
Thisfilecanhaveanyname,butisgenerallyreferredtoas cache.xml .
Foralistoftheparametersinthe cache.xml file,includingtheXSD,seeCacheInitializationFile.
Tocreateyourcache,callthe CacheFactorycreate function.The cache objectitreturnsgivesaccesstotheclientcachingAPI.Forexample:
CacheFactoryPtrcacheFactory=CacheFactory::createCacheFactory();CachePtrcachePtr=cacheFactory->create();
Note:FormoreinformationonhowtocreateacacheforC++clients,seeCreatingaCache,orfor.NETclients,seeCreatingaCache.
©CopyrightPivotalSoftwareInc,2013-2019 48 9.1
Page 49
LATESTVERSION:9.1.1- RELEASENOTES
ClosingtheCacheUsethe Cache::close functiontoreleasesystemresourceswhenyoufinishusingthecache.
Afterthecacheisclosed,anyfurthermethodcallsonthecacheoranyregionobjectresultina CacheClosedException .
Ifthecacheisinadurableclient,youneedtousethe keepalive versionoftheclosemethod.SeeDisconnectingFromtheServer.
©CopyrightPivotalSoftwareInc,2013-2019 49 9.1
Page 50
LATESTVERSION:9.1.1- RELEASENOTES
CacheInitializationFile(cache.xml)Toeasethetaskofmanagingthestructureofthecache,youcandefinethedefaultGemFirecachestructureinanXML-basedinitializationfile.
CacheInitializationFileBasics
Thecontentsofthecacheinitializationfileareusedtopopulateorupdateacache.
Thisoccurswhenacacheserverstartsup,whenaclientapplicationexplicitlycreatesitscache,orwhenaclientexplicitlyloadsanewstructureintoanexistingcache.
Theinitializationfilecanhaveanyname,butisgenerallyreferredtoas cache.xml .Bothclientapplicationsandcacheserverscanuseanoptional cache.xml filetoeasetheinitializationprocess.
FileContentsThecontentsofadeclarativeXMLfilecorrespondtoAPIsdeclaredinthe Cache.hpp and Region.hpp headerfiles.ThecacheinitializationfileallowsyoutoaccomplishdeclarativelymanyofthecachemanagementactivitiesthatyoucanprogramthroughtheAPI.
ThecontentsofthecacheinitializationfilemustconformtotheXMLdefinitioninhttp://geode.apache.org/schema/cache/cache-1.0.xsd .ThisfileidentifiesthevalidelementtagsthatmaybepresentinyourXMLfile,theattributesthatcorrespondtoeachelement,andthevalidvaluesfortheelementsandattributes.
ThenameofthedeclarativeXMLfileisspecifiedwhenestablishingaconnectiontothedistributedsystem.Youcandefineitbysettingthe cache-xml-file configurationattributeinthe geode.properties filefortheclient.Fordetailsaboutthe geode.properties file,seeSettingSystemandCacheProperties.
Examplecache.xmlFile
Anexample cache.xml fileshowscacheandregioninitializationforaclient,presentingasubsetofthepossibledataconfigurations.
SpecificinformationaboutcacheandregionattributesisinRegionAttributes.
Forinformationonusingacachewithaserverpool,seeUsingConnectionPools.Theexamplebelowshowsa cache.xml filethatcreatesaregion.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEcachePUBLIC"-//ExampleSystems,Inc.//ExampleDeclarativeCaching1.0//EN""http://geode.apache.org/schema/cache/cache-1.0.xsd"><!--Samplecache.xmlfile--><!--ExampleDeclarativeCacheInitializationwithcache.xml--><cache><poolname="examplePool"subscription-enabled="true"><serverhost="localhost"port="24680"/></pool><regionname="root1"refid="CACHING_PROXY"><region-attributespool-name="examplePool"initial-capacity="25"load-factor="0.32"concurrency-level="10"lru-entries-limit="35"><region-idle-time><expiration-attributestimeout="20"action="destroy"/></region-idle-time><entry-idle-time><expiration-attributestimeout="10"action="invalidate"/></entry-idle-time><region-time-to-live><expiration-attributestimeout="5"action="local-destroy"/></region-time-to-live><entry-time-to-live><expiration-attributestimeout="10"action="local-invalidate"/></entry-time-to-live></region-attributes></region></cache>
©CopyrightPivotalSoftwareInc,2013-2019 50 9.1
Page 51
LATESTVERSION:9.1.1- RELEASENOTES
RegionsYoucreatecacheregionseitherprogrammaticallyorthroughdeclarativestatementsinthe cache.xml file.Generally,acacheisorganizedandpopulatedthroughacombinationofthetwoapproaches.
TheregionisthecorebuildingblockoftheGemFiredistributedsystem.Allcacheddataisorganizedintodataregionsandyoudoallofyourdataputs,gets,andqueryingactivitiesagainstthem.
Adistributedregioncanbeeithernon-partitionedorapartitionedregion.SeeDataRegions fordetaileddescriptionsofbothnon-partitionedandpartitionedregions.Regioncreationissubjecttoattributeconsistencychecks.TherequirementsforconsistencybetweenattributesaredetailedbothintheAPIdocumentationandthroughoutthediscussionofAttributes.
DeclarativeRegionCreationDeclarativeregioncreationinvolvesplacingtheregion’sXMLdeclaration,withtheappropriateattributesettings,inthe cache.xml filethatisloadedatcachecreation.
ProgrammaticRegionCreationYoucreateregionsprogrammaticallywiththe regionFactory class.
InvalidatingandDestroyingRegionsInvalidationmarksallentriescontainedintheregionasinvalid(withnullvalues).Destructionremovestheregionandallofitscontentsfromthecache.
RegionAccessYoucanuse Cache::getRegion toretrieveareferencetoaspecifiedregion.
GettingtheRegionSizeThe Region APIprovidesa size method( Size propertyfor.NET)thatgetsthesizeofaregion.
©CopyrightPivotalSoftwareInc,2013-2019 51 9.1
Page 52
LATESTVERSION:9.1.1- RELEASENOTES
DeclarativeRegionCreationDeclarativeregioncreationinvolvesplacingtheregion’sXMLdeclaration,withtheappropriateattributesettings,inthe cache.xml filethatisloadedatcachecreation.
Note:Beforecreatingaregion,specifyregionattributes.SeeRegionAttributes.
Regionsareplacedinsidethecachedeclarationin region elements.Forexample:
<cache><poolname="examplePool"subscription-enabled="true"><serverhost="localhost"port="40404"/></pool><regionname="A"refid="PROXY"><region-attributespool-name="examplePool"/></region><regionname="A1"><region-attributesrefid="PROXY"pool-name="examplePool"/></region><regionname="A2"refid="CACHING_PROXY"><region-attributespool-name="examplePool"><region-time-to-live><expiration-attributestimeout="120"action="invalidate"/></region-time-to-live></region-attributes></region></cache>
The cache.xml filecontentsmustconformtotheXMLdescribedathttp://geode.apache.org/schema/cache/cache-1.0.xsd .Fordetails,seeCacheInitializationFile.
©CopyrightPivotalSoftwareInc,2013-2019 52 9.1
Page 53
LATESTVERSION:9.1.1- RELEASENOTES
ProgrammaticRegionCreationYoucreateregionsprogrammaticallywiththe regionFactory class.
Note:Beforecreatingaregion,specifyregionattributes.SeeRegionAttributes.
Createyourregionsusingthe regionFactory class.
C++RegionFactoryExample
RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);RegionPtrregPtr0=regionFactory->setLruEntriesLimit(20000)->create("exampleRegion0");
©CopyrightPivotalSoftwareInc,2013-2019 53 9.1
Page 54
LATESTVERSION:9.1.1- RELEASENOTES
InvalidatingandDestroyingRegionsInvalidationmarksallentriescontainedintheregionasinvalid(withnullvalues).Destructionremovestheregionandallofitscontentsfromthecache.
Youcanexecutetheseoperationsexplicitlyinthelocalcacheinthefollowingways:
ThroughdirectAPIcallsfromtheclient.
Throughexpirationactivitiesbasedontheregion’sstatisticsandattributesettings.
Ineithercase,youcanperforminvalidationanddestructionasalocaloradistributedoperation.
Alocaloperationaffectstheregiononlyinthelocalcache.
Adistributedoperationworksfirstontheregioninthelocalcacheandthendistributestheoperationtoallothercacheswheretheregionisdefined.Thisistheproperchoicewhentheregionisnolongerneeded,orvalid,foranyapplicationinthedistributedsystem.
Iftheregionontheserverisconfiguredasapartitionedregion,itcannotbeclearedusingAPIcallsfromtheclient.
Auser-definedcachewritercanabortaregiondestroyoperation.Cachewritersaresynchronouslistenerswiththeabilitytoabortoperations.Ifacachewriterisdefinedfortheregionanywhereinthedistributedsystem,itisinvokedbeforetheregionisexplicitlydestroyed.
Regioninvalidationanddestructioncancauseotheruser-definedapplicationplug-instobeinvokedaswell.Theseplug-insaredescribedindetailintheOverviewofApplicationPlug-Ins.
Whethercarriedoutexplicitlyorthroughexpirationactivities,invalidationanddestructioncauseeventnotification.
©CopyrightPivotalSoftwareInc,2013-2019 54 9.1
Page 55
LATESTVERSION:9.1.1- RELEASENOTES
RegionAccessYoucanuse Cache::getRegion toretrieveareferencetoaspecifiedregion.
RegionPtr returns NULL iftheregionisnotalreadypresentintheapplication’scache.Aserverregionmustalreadyexist.
Aregionnamecannotcontainthesecharacters:
<
>
:
“
/
\
|
?
*
©CopyrightPivotalSoftwareInc,2013-2019 55 9.1
Page 56
LATESTVERSION:9.1.1- RELEASENOTES
GettingtheRegionSizeThe Region APIprovidesa size method( Size propertyfor.NET)thatgetsthesizeofaregion.
Forclientregions,thisgivesthenumberofentriesinthelocalcache,notontheservers.
Seethe Region APIdocumentationfordetails.
©CopyrightPivotalSoftwareInc,2013-2019 56 9.1
Page 57
LATESTVERSION:9.1.1- RELEASENOTES
RegionEntriesRegionentriesholdcachedapplicationdata.Entriesareautomaticallymanagedaccordingtoregionattributesettings.
Youcancreate,update,invalidate,anddestroyentriesthroughexplicitAPIcallsorthroughoperationsdistributedfromothercaches.
Whenthenumberofentriesisverylarge,apartitionedregioncanprovidetherequireddatamanagementcapacityifthetotalsizeofthedataisgreaterthantheheapinanysingleJVM.
Whenanentryiscreated,anewobjectisinstantiatedintheregioncontaining:
Theentrykey.
Theentryvalue.Thisistheapplicationdataobject.Theentryvaluemaybesetto NULL ,whichistheequivalentofaninvalidvalue.
Entryoperationsinvokecallbackstouser-definedapplicationplug-ins.Inthischapter,thecallsthatmayaffecttheentryoperationitself(byprovidingavalueorabortingtheoperation,forexample)arehighlighted,butallpossibleinteractionsarenotlisted.Fordetailsofplug-ins,seetheOverviewofApplicationPlug-Ins.
DateTime objectsmustbestoredinthecacheinUTC,sothattimescorrespondbetweenclientandserver.Ifyouuseadatewithadifferenttimezone,convertitwhenstoringintoandretrievingfromthecache.
©CopyrightPivotalSoftwareInc,2013-2019 57 9.1
Page 58
LATESTVERSION:9.1.1- RELEASENOTES
EntryDistributionRequirementsEntrydatadistributedamongmembersofthedistributedsystemmustbeserializable.Entrykeysandvaluesareserializedfordistribution.
Ifaclientdefinesaregion,itmustregisteranyserializabletypesforallclassesofobjectsstoredintheregion.Thisincludesentriesthattheapplicationgetsorputs,aswellasentriesthatarepushedtotheclient’scacheautomaticallythroughdistribution.Thetypesmustberegisteredbeforetheclientconnectstothedistributedsystem.
SeeSerializingData formoreinformationabouttheserequirements.
©CopyrightPivotalSoftwareInc,2013-2019 58 9.1
Page 59
LATESTVERSION:9.1.1- RELEASENOTES
RegisteringInterestforEntriesForclientregions,youcanprogrammaticallyregisterinterestinentrykeysstoredonacacheserverregion.Aclientregionreceivesupdatenotificationsfromthecacheserverforthekeysofinterest.
Youcanregisterinterestforspecificentrykeysorforallkeys.Regularexpressionscanbeusedtoregisterinterestforkeyswhosestringsmatchtheexpression.Youcanalsounregisterinterestforspecifickeys,groupsofkeysbasedonregularexpressions,orforallkeys.
Note:Interestregistrationandunregistrationaresymmetricaloperations.Consequently,youcannotregisterinterestinallkeysandthenunregisterinterestinaspecificsetofkeys.Also,ifyoufirstregisterinterestinspecifickeyswith registerKeys ,thencall registerAllKeys ,youmustcall unregisterAllKeys beforespecifyinginterestinspecifickeysagain.
ClientAPIforRegisteringInterestYouregisterclientinterestthroughtheC++orNETAPI.TheC++APIprovidesthe registerKeys , registerAllKeys ,and registerRegex methods,withcorrespondingunregistrationaccomplishedusingthe unregisterKeys , unregisterAllKeys ,and unregisterRegex methods.The.NETAPIprovidesthe RegisterKeys , RegisterAllKeys ,and RegisterRegex methods,withcorrespondingunregistrationaccomplishedusingthe UnregisterKeys , UnregisterAllKeys ,and UnregisterRegex methods.
The registerKeys , registerRegex and registerAllKeys methodshavetheoptiontopopulatethecachewiththeregistrationresultsfromtheserver.The registerRegex and registerAllKeysmethodscanalsooptionallyreturnthecurrentlistofkeysregisteredontheserver.
SettingUpClientNotificationInadditiontotheprogrammaticfunctioncalls,toregisterinterestforaserverregionandreceiveupdatedentriesyouneedtoconfiguretheregionwiththe PROXY orCACHING_PROXYRegionShortcut setting.Theregion’spoolshouldhave subscription-enabled=true seteitherintheclientXMLorprogrammaticallyviaa CacheFactory::setSubscriptionEnabled(true)APIcall.Otherwise,whenyouregisterinterest,youwillgetan UnsupportedOperationException .
<regionname="listenerWriterLoader"refid="CACHING_PROXY">...
Allclientsthathavesubscriptionsenabledtrackanddrop(ignore)anyduplicatenotificationsreceived.Toreduceresourceusage,aclientexpirestrackedsourcesforwhichnewnotificationshavenotbeenreceivedforaconfigurableamountoftime.
NotificationSequence
Notificationsinvoke CacheListeners ofcachelessclientsinallcasesforkeysthathavebeenregisteredontheserver.Similarly,invalidatesreceivedfromtheserverinvokecachelessclients.
Ifyouregistertoreceivenotifications,listenercallbacksareinvokedirrespectiveofwhetherthekeyisintheclientcachewhena destroy or invalidate eventisreceived.
RegisteringInterestforSpecificKeysYouregisterandunregisterinterestforspecifickeysthroughthe registerKeys and unregisterKeys functions.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:
©CopyrightPivotalSoftwareInc,2013-2019 59 9.1
Page 60
regPtr0->registerAllKeys();regPtr1->registerAllKeys();
Thefollowingexampleshowsacodesampleforunregisteringinterestinallkeys.
regPtr0->unregisterAllKeys();regPtr1->unregisterAllKeys();
RegisteringInterestUsingRegularExpressionsThe registerRegex functionregistersinterestinaregularexpressionpattern.Theserverautomaticallysendstheclientchangesforentrieswhosekeysmatchthespecifiedpattern.
Keysmustbestringsinordertoregisterinterestusingregularexpressions.
Thefollowingexampleshowsinterestregistrationforallkeyswhosefirstfourcharactersare Key- ,followedbyanystringofcharacters.Thecharacters .* representawildcardthatmatchesanystring.
regPtr1->registerRegex("Key-.*");
Tounregisterinterestusingregularexpressions,youusethe unregisterRegex function.Thenextexampleshowshowtounregisterinterestinallkeyswhosefirstfourcharactersarefollowedbyanystring(representedbythe .* wildcard).
regPtr1->unregisterRegex("Key-.*");
RegisterInterestScenarioInthisregisterinterestscenario,acachelistenerisusedwithacachelessregionthathas subscription-enabled setto true .Theclientregionisconfiguredwithcachingdisabled;clientnotificationisenabled;andacachelistenerisestablished.Theclienthasnotregisteredinterestinanykeys.
Whenavaluechangesinanotherclient,itsendstheeventtotheserver.Theserverwillnotsendtheeventtothecachelessclient,eventhoughclient-notification issetto true
Toactivatethecachelistenersothecachelessregionreceivesupdates,theclientshouldexplicitlyregisterinterestinsomeorallkeysbyusingoneoftheAPIcallsforregisteringinterest.Thisway,theclientreceivesalleventsforthekeystowhichithasregisteredinterest.ThisappliestoJava-basedclientsaswellasnon-Javaclients.
©CopyrightPivotalSoftwareInc,2013-2019 60 9.1
Page 61
LATESTVERSION:9.1.1- RELEASENOTES
UsingserverKeystoRetrieveaSetofRegionKeysYoucanretrievethesetofkeysdefinedinthecacheserverprocessthatareassociatedwiththeclientregionbyusingthe Region::serverKeys APIfunction.Iftheserverregionisdefinedasareplicate,thekeysreturnedconsistoftheentiresetofkeysfortheregion.
Thefollowingexampleshowshowtheclientcanprogrammaticallycall serverKeys .
VectorOfCacheableKeykeysVec;region->serverKeys(keysVec);size_tvlen=keysVec.size();boolfoundKey1=false;boolfoundKey2=false;for(size_ti=0;i<vlen;i++){CacheableStringPtrstrPtr=dynCast<CacheableStringPtr>keysVec.at(i);std::stringveckey=strPtr->asChar();if(veckey=="skey1"){printf("foundskey1");foundKey1=true;}if(veckey=="skey2"){printf("foundskey2");foundKey2=true;}}
An UnsupportedOperationException occursiftheclientregionisnotanativeclientregion.A MessageException occursifthemessagereceivedfromtheservercouldnotbehandled,whichcanoccurifanunregistered typeId isreceivedinthereply.
©CopyrightPivotalSoftwareInc,2013-2019 61 9.1
Page 62
LATESTVERSION:9.1.1- RELEASENOTES
AddingEntriestotheCacheAregionispopulatedwithcachedentriesinseveralways:
Explicitly,whenanapplicationexecutesa create ora put operationforasingleentryorformultipleentriesthatdonotalreadyexistinthecache.
Implicitly,whenaclientdoesagetonasingleentryoronmultipleentriesthatdonotalreadyexistinthecache.Inthiscase,theentryisretrievedfromaremotecacheorthroughacacheloader.ReadaboutcacheloadersatOverviewofApplicationPlug-Ins.Aclientcanalsouse getAll topopulatearegionwithallvaluesforanarrayofkeys.SeeEntries.
Automatically,whenentriesarecreatedinremotecaches.
Ifanycachewriterisavailableinthedistributedregion,itiscalledbeforetheentryiscreatedanditcanabortthecreationprocess.
AddingEntriestotheLocalCacheIfjustthelocalcacheistobepopulated,youcaneither create anentryusingthe localCreate RegionAPI,or put anentryusing localPut .
DateTime objectsmustbestoredinthecacheinUTC,sothattimescorrespondbetweenclientandserver.Ifyouuseadatewithadifferenttimezone,convertitwhenstoringintoandretrievingfromthecache.ThisexampleconvertsalocaltimetoUTCforaputoperation:
DateTimet1(2009,8,13,4,11,0,DateTimeKind.Local);region0.Put(1,t1.ToUniversalTime());
AddingMultipleEntriesUsingPutAllIfyouneedtoaddmanycacheentriestoaregionatonetime,youcanimprovecacheperformancebyusingtheputAll functiontoaddtheminasingledistributedoperation.Multiplekey/valuepairsarestoredinahashmap,thenthehashmapcontentsareprocessedontheserveraseithernewentries,updates,orinvalidatesforexistingentries.
UnderAddinganEntrytotheCacheseethesubsectiontitledBulkPutOperationsUsingputAllformoreinformationaboutthe putAll API.
©CopyrightPivotalSoftwareInc,2013-2019 62 9.1
Page 63
LATESTVERSION:9.1.1- RELEASENOTES
UpdatingEntriesAcachedentrycanbeupdatedusingthesemethods:
Explicitly,whenaclientinvokesa put operationonanexistingentry.
Implicitly,whena get isperformedonanentrythathasaninvalidvalueinthecache.AnentrycanbecomeinvalidthroughanexplicitAPIcall,throughanautomatedexpirationaction,orbybeingcreatedwithavalueofnull.
Automatically,whenanewentryvalueisdistributedfromanothercache.
Similartoentrycreation,alloftheseoperationscanbeabortedbyacachewriter.
The get functionreturnsadirectreferencetotheentryvalueobject.Achangemadeusingthatreferenceiscalledanin-placechangebecauseitdirectlymodifiesthecontentsofthevalueinthelocalcache.Fordetailsonsafecacheaccess,seeManagingtheLifetimeofaCachedObject.
©CopyrightPivotalSoftwareInc,2013-2019 63 9.1
Page 64
LATESTVERSION:9.1.1- RELEASENOTES
AccessingEntriesUsetheAPItoretrievetheentrykey,entryvalue,andthe RegionEntry objectitself.Avarietyoffunctionsprovideinformationforindividualentriesandforthesetofallentriesresidentintheregion.
Aregion’sentrykeysand RegionEntry objectsaredirectlyavailablefromthelocalcache.Applicationscandirectlyaccessthelocalcache’sstoredentryvaluethroughtheRegionEntry::getValue function.The getValue functioneitherreturnsthevalueifavalidvalueispresentinthelocalcache,or NULL ifthevalueisnotvalidlocally.Thisfunctiondoesnodataloading,nordoesitlookelsewhereinthedistributedsystemforavalidvalue.
Note:Directaccessthrough RegionEntry::getValue doesnotresetanentry’stimestampforLRUexpiration.SeeSpecifyingExpirationAttributesformoreinformationaboutLRUexpiration.
Incomparison,the Region::get functionsconsiderallcachesandallapplicableloadersinthedistributedsysteminanattempttoreturnavalidentryvaluetothecallingapplication.Theprimaryattributesettingaffectingentryretrievalis CacheLoader .SeeSpecifyingApplicationPlug-InAttributes.
The Region::get functionsmayimplementmorethanoneoperationinordertoretrieveavalidentryvalue.Theoperationsuseddependontheregion’sattributesettingsandonthestateoftheentryitself.Bydefault,theclientretrievesentryvaluesthroughcallstothe get function.Theclientcanoverridethisbehaviorforanyregionbydefiningacacheloaderfortheregion.
Thefollowingsectionsdiscussthe get functionandspecialconsiderationsforentryretrieval.
EntryRetrievalRetrieveentryvalueswiththe Region::get function.
Whenanentryvalueisrequestedfromaregion,itiseitherretrievedfromthecacheserverorfetchedbytheregion’slocally-definedcacheloaderinthissequence:
1. localcachesearch
2. servercache
3. localload(Fordistributedregions,thelocalloadisfetchedbeforeremotecachevalues)
HowthegetOperationAffectstheLocalEntryValueIfa get operationretrievesanentryvaluefromoutsidethelocalcachethroughalocalload,itautomatically put sthevalueintothecacheforfuturereference.
Notethattheseloadoperationsdonotinvokeacachewriter.Becausetheloaderandwriteroperateagainstthesamedatasource,youdonotneedtoperformacachewriteforentriesthatwerejustfetchedfromthatdatasource.Fordescriptionsoftheseprocesses,seetheOverviewofApplicationPlug-Ins.
Note:Accessthrougha get operationresetsanentry’stimestampforLRUexpiration.
GettingMultipleEntriesUsinggetAllYoucanusethe getAll Regionfunctiontogetallvaluesforanarrayofkeysfromthelocalcacheorcacheserver.SubsectionBulkPutOperationsUsingputAllhasmoreinformation.
©CopyrightPivotalSoftwareInc,2013-2019 64 9.1
Page 65
LATESTVERSION:9.1.1- RELEASENOTES
InvalidatingorDestroyingCachedEntriesInvalidatinganentrysetstheentry’svalueto NULL .Destroyingitremovestheentryfromtheregionaltogether.Theseoperationscanbecarriedoutinthelocalcacheinthefollowingways:
ThroughdirectAPIcallsfromtheclient.
Throughexpirationactivitiesbasedontheentry’sstatisticsandtheregion’sattributesettings.
Note:Auser-definedcachewriteriscalledbeforeanoperationiscompleted,andcanabortanentrydestroyoperation.
Whethercarriedoutexplicitlyorthroughexpirationactivities,invalidationanddestructioncauseeventnotification:The CacheEvent objecthasan isExpiration flagthatissettotrueforeventsresultingfromexpirationactivities,andsetto false forallotherevents.
©CopyrightPivotalSoftwareInc,2013-2019 65 9.1
Page 66
LATESTVERSION:9.1.1- RELEASENOTES
NotificationforOperationsListenersareinvokedforclient-initiatedoperationsonlyaftertheclientoperationsucceedsontheserver.Listenerinvocationontheclientindicatesthattheserverhasthesamedataastheclient.
Ifaclientoperationfailsontheserver,theoperationisrolledback,assumingthatnootherthreadhasmodifiedthedataintheinterveningperiod.RollbackmaynotbepossibleincaseswheretheentryhasbeenevictedbyLRUorexpirationduringthisperiod.Thuswhenanexceptionisreceivedfromtheserverforanoperation,localchangesmaynothavebeenrolledback.
EventNotificationSequenceEventsreceivedontheclientsthatoriginatedontheserverinvokethesubscriptionfortheeventasseenbytheserver.Eventsoriginatingontheclientinvokethesubscriptionasseenbytheclient.
Forexample,aclientthatreceivesa create andan update fromtheserverfiresa create eventandan update eventbecausethatishowtheserversawit.Acachelessclientthatdoestwoconsecutiveputoperationshastwo afterCreate eventsinvokedontheoriginatingclientbecausetheclientdoesnothaveanyhistoryaboutthefirstput,sinceitiscacheless.
Forthesamesequence,theserverseesan afterCreate andan afterUpdate event,andaremoteclientreceivingtheeventseesan afterCreate followedbyan afterUpdate event.Aclientthatcacheslocallyseesan afterCreate andan afterUpdate forthesamescenario(aswilltheserverandremoteclients).
©CopyrightPivotalSoftwareInc,2013-2019 66 9.1
Page 67
LATESTVERSION:9.1.1- RELEASENOTES
RegionConsistencyGemFireensuresthatallcopiesofaregioneventuallyreachaconsistentstateonallmembersandclientsthathosttheregion.
BydefaultGemFiremembersperformconsistencycheckswhentheyapplyupdatestoadistributedregion,inordertoensurethatallcopiesoftheregioneventuallybecomeconsistentonallGemFiremembersandclientcachesthathosttheregion.Differenttypesofregionensureconsistencyusingdifferenttechniques.However,whenconsistencycheckingisenabled(thedefault)allentriesinaregionrequireadditionaloverheadinordertostoreversionandtimestampinformation.
AlthougharegionmusthavethesameconsistencycheckingconfigurationonallGemFiremembersthathosttheregion,youcanoptionallydisableconsistencycheckinginaclientcacheregionwhileleavingconsistencycheckingenabledfortheregiononGemFiremembers.Thisconfigurationmaybenecessaryincertaincaseswheretheclientmustviewallupdatestoagivenregion,evenwhenGemFiremembersdiscardsanupdateinordertopreserveregionconsistency.
SeeConsistencyforRegionUpdates intheserver’sdocumentationformoreinformation.
ClientOverheadforConsistencyChecksIntheclientregions,theoverheadforperformingconsistencycheckisanadditional11bytesperregionentry.Thisoverheadisslightlysmallerthantheoverheadrequiredtoprovideconsistencycheckingonserver-sideregionentries.
Ifyoucannotsupporttheadditionaloverheadinyourdeployment,youcandisableconsistencychecksbysettingtheregionattribute concurrency-checks-enabled tofalseforeachregionhostedbyyourclient.
©CopyrightPivotalSoftwareInc,2013-2019 67 9.1
Page 68
LATESTVERSION:9.1.1- RELEASENOTES
RegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.
Regionattributesettingsdeterminewherethedataresides,howtheregionismanagedinmemory,andtheautomaticloading,distribution,andexpirationofregionentries.
SpecifyingRegionAttributes
RegionShortcuts
MutableandImmutableRegionAttributes
CachingEnabled
InitialCapacity
LoadFactor
ConcurrencyLevel
ConcurrencyChecksEnabled
LruEntriesLimit
DiskPolicy
PersistenceManager
SpecifyingExpirationAttributes
©CopyrightPivotalSoftwareInc,2013-2019 68 9.1
Page 69
LATESTVERSION:9.1.1- RELEASENOTES
SpecifyingRegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.
Specifyregionattributesbeforecreatingtheregion.YoucandothiseitherthroughthedeclarativeXMLfileorthroughtheAPI.TheAPIincludesclassesfordefiningaregion’sattributesbeforecreationandformodifyingsomeofthemaftercreation.Fordetails,seetheAPIfor RegionShortcut , RegionAttributes , AttributesFactory ,and AttributesMutator .
©CopyrightPivotalSoftwareInc,2013-2019 69 9.1
Page 70
LATESTVERSION:9.1.1- RELEASENOTES
RegionShortcutsGemFireprovidespredefined,shortcutregionattributessettingsforyouruse,in RegionShortcut .
Shortcutattributesareaconvenienceonly.TheyarenamedattributesthatGemFirehasalreadystoredforyou.Youcanoverridetheirsettingsbystoringnewattributeswiththesameid asthepredefinedattributes.
Youcanalsocreatecustomregionattributesandstorethemwithanidentifierforlaterretrieval.Bothtypesofstoredattributesarereferredtoasnamedregionattributes.Youcancreateandstoreyourattributesettingsinthe cache.xml fileandthroughtheAPI.
RetrievenamedattributesbyprovidingtheIDtotheregioncreation.Thisexampleusestheshortcut CACHING_PROXY attributestocreatearegion:
<regionname="testRegion"refid="CACHING_PROXY"/>
Youcanmodifynamedattributesasneeded.Forexample,thisaddsacachelistenertotheregion:
<regionname="testRegion"refid="CACHING_PROXY"><region-attributes><cache-listenerlibrary-name="myAppLib"library-function-name="myCacheListener"/></region-attributes></region>
Inthisexample,themodifiedregionshortcutissavedtothecacheusingtheregionattributeid,forretrievalandusebyasecondregion:
<regionname="testRegion"refid="CACHING_PROXY"><region-attributesid="Caching_Proxy_With_Listener"><cache-listenerlibrary-name="myAppLib"library-function-name="myCacheListener"/></region-attributes></region><regionname="newTestRegion"refid="Caching_Proxy_With_Listener"/>
ShortcutAttributeOptionsYoucanselectthemostcommonregionattributessettingsfrom RegionShortcut ,thepredefinednamedregionattributes.
Thissectionprovidesanoverviewoftheoptionsavailableintheregionshortcutsettings.
CommunicationwithServersandDataStorage
PROXY doesnotstoredataintheclientcache,butconnectstheregiontotheserversfordatarequestsandupdates,interestregistrations,andsoon.
CACHING_PROXY storesdataintheclientcacheandconnectstheregiontotheserversfordatarequestsandupdates,interestregistrations,andsoon.
LOCAL storesdataintheclientcacheanddoesnotconnecttheregiontotheservers.Thisisaclient-side-onlyregion.
DataEviction
Non- PROXY regionsarethosethatstoredataintheclientcache.Youcanadddataevictionfornon- PROXY regions:
ENTRY_LRU causesleastrecentlyuseddatatobeevictedfrommemorywhentheregionreachestheentrycountlimit.
©CopyrightPivotalSoftwareInc,2013-2019 70 9.1
Page 71
LATESTVERSION:9.1.1- RELEASENOTES
MutableandImmutableRegionAttributesAttributesthatareimmutable(fixed)afterregioncreationgovernstoragelocation,datadistribution,statistics,applicationplug-ins,andtheconfigurationandmanagementoftheregion’sdatahashmap.
Thistableliststheimmutableattributesandtheirdefaultsettings.
ImmutableRegionAttribute DefaultSetting
SeeCachingEnabled true
SeeInitialCapacity 16(entries)
SeeLoadFactor 0.75
SeeConcurrencyLevel 16
SeeDiskPolicy
SeePersistenceManager NULL
PartitionResolver.SeeOverviewofApplicationPlug-Ins.
Mutableregionattributesidentifyexpirationandcachelistener,cachewriterandcacheloaderactionsthatarerunfromthedefiningclient.Thenexttableliststhemutableattributesthatgenerallycanbemodifiedafterregioncreationbyusingthe AttributesMutator fortheregion.
MutableRegionAttribute DefaultSetting
Expirationattributes.SeeSpecifyingExpirationAttributes. noexpiration
SeeLruEntriesLimit. 0(nolimit)
CacheLoader.SeeOverviewofApplicationPlug-Ins.
CacheWriter.SeeOverviewofApplicationPlug-Ins.
CacheListener.SeeOverviewofApplicationPlug-Ins.
SeeSpecifyingApplicationPlug-InAttributesforinformationaboutusing AttributesMutator withcachelisteners,cacheloaders,andcachewriters.
Theremainderofthissectionexaminestheseattributesindetail.Throughoutthedescriptions, cache.xml filesnippetsshowhoweachattributecanbesetdeclaratively.
©CopyrightPivotalSoftwareInc,2013-2019 71 9.1
Page 72
LATESTVERSION:9.1.1- RELEASENOTES
CachingEnabledThisattributedetermineswhetherdataiscachedinthisregion.Forexample,youmightchoosetoconfigurethedistributedsystemasasimplemessagingservicewhereclientsrunwithoutacache.
Note:Youcanconfigurethemostcommonoftheseoptionswiththepredefinedregionattributes.SeeRegionShortcutsandtheJavadocsfor RegionShortcut .
If CachingEnabled isfalse(nocaching),an IllegalStateException isthrownifanyoftheseattributesareset:
InitialCapacity
EntryTimeToLive underSpecifyingExpirationAttributes
EntryIdleTimeout underSpecifyingExpirationAttributes
LoadFactor
ConcurrencyLevel
LruEntriesLimit
DiskPolicy
Thefollowingdeclarationenablescachingfortheregion:
<region-attributescaching-enabled="true"></region-attributes>
©CopyrightPivotalSoftwareInc,2013-2019 72 9.1
Page 73
LATESTVERSION:9.1.1- RELEASENOTES
InitialCapacityUsethisattribute,togetherwiththe LoadFactor attribute,tosettheinitialparametersontheunderlyinghashmapthatstoresregionentries.Thisisthenumberofentriesthattheregionmapwillbereadytoholdwhenitiscreated.
Thisdeclarationsetstheregion’sinitialcapacityto 10000 :
<region-attributesinitial-capacity="10000"></region-attributes>
©CopyrightPivotalSoftwareInc,2013-2019 73 9.1
Page 74
LATESTVERSION:9.1.1- RELEASENOTES
LoadFactorUsethisattribute,togetherwiththe InitialCapacity attribute,tosettheinitialparametersontheunderlyinghashmapthatstoresregionentries.Whenthenumberofentriesinthemapexceedsthe LoadFactor timescurrentcapacity,thecapacityisincreasedandthemapisrehashed.Yougetthebestperformanceifyouconfigureaproperlysizedregionatthestartanddonothavetorehashit.
Thisdeclarationsetstheregion’sloadfactorto 0.75 :
<region-attributesload-factor="0.75"></region-attributes>
©CopyrightPivotalSoftwareInc,2013-2019 74 9.1
Page 75
LATESTVERSION:9.1.1- RELEASENOTES
ConcurrencyLevelThisattributeestimatesthemaximumnumberofapplicationthreadsthatconcurrentlyaccessaregionentryatonetime.Thisattributehelpsoptimizetheuseofsystemresourcesandreducethreadcontention.
Thefollowingdeclarationsetstheregion’s ConcurrencyLevel to 16 :
<region-attributesconcurrency-level="16"></region-attributes>
Note:When CachingEnabled is false ,donotsetthe ConcurrencyLevel attribute.An IllegalStateException isthrowniftheattributeisset.
©CopyrightPivotalSoftwareInc,2013-2019 75 9.1
Page 76
LATESTVERSION:9.1.1- RELEASENOTES
ConcurrencyChecksEnabledThisattributedetermineswhethermembersperformcheckstoprovideconsistenthandlingforconcurrentorout-of-orderupdatestodistributedregions.
Aclientcachecandisableconsistencycheckingforaregionevenifservercachesenableconsistencycheckingforthesameregion.Thisconfigurationensuresthattheclientseesalleventsfortheregion,butitdoesnotpreventtheclientcacheregionfrombecomingout-of-syncwiththeservercache.
Optionallyenableconcurrencychecksfortheregion.Example:
<region-attributesconcurrency-checks-enabled="true"></region-attributes>
SeeRegionConsistencyformoreinformation.
©CopyrightPivotalSoftwareInc,2013-2019 76 9.1
Page 77
LATESTVERSION:9.1.1- RELEASENOTES
LruEntriesLimitThisattributesetsthemaximumnumberofentriestoholdinacachingregion.Whenthecapacityofthecachingregionisexceeded,aleast-recently-used(LRU)algorithmisusedtoevictentries.
Note:Thisisatuningparameterthataffectssystemperformance.
Whenevictionisconfigured,memoryconsumptionorentrycountismonitoredand,whencapacityisreached,GemFiremakeswayfornewentriesbyremovingoroverflowingthestalestLRUentriestodisk.
Ifyouusediskdataoverflowtosupplementmemoryforyourdatacache,makesureyouhaveenoughdiskspacetostorethedata.
Thisdeclarationlimitstheregionto20,000entries:
<region-attributeslru-entries-limit="20000"initial-capacity="20000"load-factor="1"></region-attributes>
Evictedentriescanbedestroyedormovedtodiskasanextensionofthecache.SeeDiskPolicy.
Note:When CachingEnabled is false ,donotsetthe LruEntriesLimit attribute.An IllegalStateException isthrowniftheattributeisset.
SeealsoControllingCacheSize.
©CopyrightPivotalSoftwareInc,2013-2019 77 9.1
Page 78
LATESTVERSION:9.1.1- RELEASENOTES
DiskPolicyIfthe lru-entries-limit attributeisgreaterthanzero,theoptional disk-policy attributedetermineshowover-limitLRUentriesarehandled.LRUentriesoverthelimitareeitherdestroyedbydefault( disk-policy isnone)orwrittentodisk( overflows ).
Note:If LruEntriesLimit is 0 ,or CachingEnabled is false ,donotsetthe disk-policy attribute.An IllegalStateException isthrowniftheattributeisset.
ThisdeclarationcausesLRUtooverflowtodisk:
<region-attributeslru-entries-limit="20000"disk-policy="overflows"><persistence-manager.../></region-attributes>
Overflowrequiresapersistencemanagerforcache-to-diskanddisk-to-cacheoperations.SeePersistenceManager.
OverflowingDatatoDiskRegiondatacanbestoredtodiskusingtheoverflowprocesstosatisfyregioncapacityrestrictionswithoutcompletelydestroyingthelocalcachedata.Thestoragemechanismusesdiskfilestoholdregionentrydata.Whenanentryisoverflowed,itsvalueiswrittentodiskbutitskeyandentryobjectremaininthecache.Thisalsousestheregionattribute
Overflowallowsyoutokeeptheregionwithinauser-specifiedsizeinmemorybyrelegatingthevaluesofleastrecentlyused(LRU)entriestodisk.Overflowessentiallyusesdiskasaswapspaceforentryvalues.Whentheregionsizereachesthespecifiedthreshold,entryvaluesaremovedfrommemorytodisk,asshowninthefollowingfigure.Ifanentryisrequestedwhosevalueisonlyondisk,thevalueiscopiedbackintomemory,possiblycausingthevalueofadifferentLRUentrytobeoverflowedtodisk.
Figure:DataFlowBetweenOverflowRegionandDiskFiles
InthisfigurethevalueoftheLRUentryXhasbeenmovedtodisktorecoverspaceinmemory.Thekeyfortheentryremainsinmemory.Fromthedistributedsystemperspective,thevalueondiskisasmuchapartoftheregionasthedatainmemory.A get performedonregionBlooksfirstinmemoryandthenondiskaspartofthelocalcachesearch.
©CopyrightPivotalSoftwareInc,2013-2019 78 9.1
Page 79
LATESTVERSION:9.1.1- RELEASENOTES
PersistenceManagerForeachregion,ifthedisk-policyattributeissettooverflows,apersistence-managerplug-inmustperformcache-to-diskanddisk-to-cacheoperations.SeetheOverviewofApplicationPlug-Ins.
Persistencemanagerdeclaration:
<region-attributeslru-entries-limit="nnnnn"disk-policy="overflows"><persistence-managerlibrary-name="libraryName"library-function-name="functionName"><properties><propertyname="propertyName"value="propertyValue"/></properties></persistence-manager></region-attributes>
Theoptionalpropertiessetparametersfortheplug-in.
UsingSQLiteasaPersistenceManagerTheclientdistributionincludesapersistencemanagerthatusestheopen-sourceSQLitelibrary.
SQLiteisasoftwarelibrarythatimplementsaself-containedtransactionalSQLdatabase.SQLitedoesnotrequireitsownserverorseparateconfiguration,andthesourcecodeforSQLiteisinthepublicdomain.FormoreinformationonSQLite,seehttp://www.sqlite.org .
EachSQLitepersistencemanagerpersistsitsregiondatainaSQLitedatabasethatisstoredindiskfiles.Inagivenclientapplicationprocess,eachregionmusthaveauniquepersistence(overflow)directory.
Figure:SQLiteDatabasePersistenceManagerDirectoryStructure
SQLitePersistenceManagerRegionAttributesThefollowingtabledescribestheregionattributesthatcanbeconfiguredfortheSQLitepersistencemanager.
Property Description DefaultSetting
PersistenceDirectory
Directorywhereeachregion’sdatabasefilesarestored.Thissettingmustbedifferentforeachregionincludingregionsindifferentprocesses.Thisdirectoryiscreatedbythepersistencemanager.Thepersistencemanagerfailstoinitializeifthisdirectoryalreadyexistsorcannotbecreated.
DefaultistocreateasubdirectorynamedGemFireRegionDatainthedirectorywheretheprocessusingtheregionwasstarted.
PageSize
MaximumpagesizeoftheSQLitedatabase.SQLitecanlimitthesizeofadatabasefiletopreventthedatabasefilefromgrowingtoolargeandconsumingtoomuchdiskspace.
Ordinarily,ifnovalueisexplicitlyprovided,SQLitecreatesadatabasewiththepagesizesettoSQLITE_DEFAULT_PAGE_SIZE(defaultis1024).However,basedoncertaindevicecharacteristics(forexample,sector-sizeandatomicwrite()support)SQLitemaychoosealargervalue.PageSizespecifiesthemaximumvaluethatSQLitewillbeabletochooseonitsown.See http://www.sqlite.org/compile.html#default_page_size .formoredetailsonSQLITE_DEFAULT_PAGE_SIZE.
MaxPageCount Maximumnumberofpagesinonedatabasefile. SQLitedefault,whichis1073741823.
©CopyrightPivotalSoftwareInc,2013-2019 79 9.1
Page 80
ConfiguringtheSQLitePersistenceManagerPlug-InforC++ApplicationsToloadtheSQLitepersistencemanagerplug-inforC++applications,youcanconfigureiteitherinyourclient’s cache.xml orprogrammaticallyusingtheC++clientAPI.
Thefollowingisanexampleofhowtospecifythefollowingregionattributesinyourclient’scache.xml:
<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>
C++APIExampleTousetheC++clientAPI,setSQLitepersistencemanagerattributesprogrammaticallyasfollows:
PropertiesPtrsqliteProperties=Properties::create();sqliteProperties->insert("MaxPagecount","5");sqliteProperties->insert("PageSize","1024");sqliteProperties->insert("PersistenceDirectory","SqLite-Test779");regionFactory->setPersistenceManager("SqLiteImpl","createSqLiteInstance",sqliteProperties);
ConfiguringtheSQLitePersistenceManagerPlug-Infor.NETApplicationsToloadtheSQLitepersistencemanagerplug-infor.NETapplications,youcanconfigureiteitherinyourclient’scache.xmlorprogrammaticallyusingthe.NETAPI:
<persistence-managerlibrary-name="Apache.Geode.Plugins.SqLite"library-function-name="Apache.Geode.Plugins.SqLite.SqLiteImpl<System.Object,System.Object>.Create"><properties><propertyname="PersistenceDirectory"value="SqLite"/><propertyname="MaxPageCount"value="1073741823"/><propertyname="PageSize"value="65536"/></properties></persistence-manager>
.NETAPIExampleTousethe.NETclientAPI,settheSQLitepersistencemanagerattributesprogrammaticallyasfollows:
Properties<string,string>sqliteProperties=newProperties<string,string>();sqliteProperties.Insert("PageSize","65536");sqliteProperties.Insert("MaxFileSize","51200000");sqliteProperties.Insert("PersistenceDirectory",SqLiteDir);rf.SetPersistenceManager("Apache.Geode.Plugins.SqLite","Apache.Geode.Plugins.SqLite.SqLiteImpl<System.Object,System.Object>.Create",sqliteProperties);
YoucanalsouseandconfiguretheC++SQLitepersistencemanagerlibraryfromyour.NETapplicationasfollows:
rf.SetPersistenceManager("SqliteImpl","createSqLiteInstance",sqliteProperties);
ImplementingaPersistenceManagerwiththeIPersistenceManagerInterfaceWhendeveloping.NETmanagedapplications,youcanusetheIPersistenceManagermanagedinterfacetoimplementyourownpersistencemanager.ThefollowingcodesampleprovidestheIPersistenceManagerinterface:
©CopyrightPivotalSoftwareInc,2013-2019 80 9.1
Page 81
///<summary>///IPersistenceManagerinterfaceforpersistenceandoverflow.///Thisclassabstractsthedisk-relatedoperationsincaseofpersistenceoroverflowtodisk.///Aspecificdiskstorageimplementationwillimplementallthemethodsdescribedhere.///</summary>generic<classTKey,classTValue>publicinterfaceclassIPersistenceManager{public:///<summary>///Calledafteranimplementationobjectiscreated.Initializesalltheimplementationspecificenvironmentsneeded.///</summary>///<paramname="region">///RegionforwhichthisPersistenceManagerisinitialized.///</param>///<paramname="diskProperties">///ConfigurationPropertiesusedbyPersistenceManagerimplementation.///</param>voidInit(IRegion<TKey,TValue>^region,Properties<String^,String^>^diskProperties);
///<summary>///Writesakey,valuepairofregiontothedisk.Theactualfileordatabaserelatedwriteoperationsshouldbeimplementedinthismethod.///</summary>///<paramname="key">///thekeytowrite.///</param>///<paramname="value">///thevaluetowrite.///</param>voidWrite(TKeykey,TValuevalue);
///<summary>///Thismethodisnotused.///</summary>boolWriteAll();
///<summary>///Readsthevalueforthekeyfromthedisk.///</summary>///<paramname="key">///keyforwhichthevaluehastoberead.///</param>TValueRead(TKeykey);
///<summary>///Thismethodisnotused.///</summary>boolReadAll();
///<summary>///Destroystheentryspecifiedbythekeyintheargument.///</summary>///<paramname="key">///keyoftheentrywhichisbeingdestroyed.///</param>voidDestroy(TKeykey);
///<summary>///Closesthepersistencemanagerinstance.///</summary>voidClose();}
Thefollowingisasampleinterfaceimplementation:
©CopyrightPivotalSoftwareInc,2013-2019 81 9.1
Page 82
classMyPersistenceManager<TKey,TValue>:IPersistenceManager<TKey,TValue>{#regionIPersistenceManager<TKey,TValue>MemberspublicvoidClose(){thrownewNotImplementedException();}
publicvoidDestroy(TKeykey){thrownewNotImplementedException();}
publicvoidInit(IRegion<TKey,TValue>region,Properties<string,string>diskProperties){thrownewNotImplementedException();}
publicTValueRead(TKeykey){thrownewNotImplementedException();}
publicvoidWrite(TKeykey,TValuevalue){thrownewNotImplementedException();}
publicboolReadAll(){thrownewNotImplementedException();}
publicboolWriteAll(){thrownewNotImplementedException();}#endregion}
©CopyrightPivotalSoftwareInc,2013-2019 82 9.1
Page 83
LATESTVERSION:9.1.1- RELEASENOTES
SpecifyingExpirationAttributesExpirationattributesgoverntheautomaticevictionofregionsandregionentriesfromthecache.Evictionisbasedonthetimeelapsedsincethelastupdateoraccesstotheobject.Thisisreferredtoastheleast-recently-used(LRU)evictionprocess.Expirationoptionsrangefrommarkingtheexpiredobjectasinvalidtocompletelyremovingitfromthedistributedcache.Evictioncanhelpkeepdatacurrentbyremovingoutdatedentries,promptingareloadthenexttimetheyarerequested.Evictionmayalsobeusedtorecoverspaceinthecachebyclearingoutunaccessedentriesandregions.
Similartoapplicationplug-ins,expirationactivitiesarehostedbyeachapplicationthatdefinesaregioninitscache.
Thefollowingexampleshowsadeclarationthatcausestheregion’sentriestobeinvalidatedinthelocalcacheaftertheyhavenotbeenaccessedforoneminute.
<region-attributes><entry-idle-time><expiration-attributestimeout="60"action="local-invalidate"/></entry-idle-time></region-attributes>
Regionandregionentryexpirationattributesaresetattheregionlevel.Bydefault,regionsandentriesdonotexpire.Thefollowingattributescovertwotypesofexpiration:time-to-live(TTL)andidletimeout.
RegionTimeToLiveNumberofsecondsthattheregionremainsinthecacheafterthelastcreationorupdatebeforetheexpirationactionoccurs.
EntryTimeToLive
Forentries,thecounterissettozerofor create and put operations.Regioncountersareresetwhentheregioniscreatedandwhenanentryhasitscounterreset.Anupdatetoanentrycausesthetime-to-live(TTL)counterstoberesetfortheentryanditsregion.
RegionIdleTimeoutNumberofsecondsthattheregionremainsinthecacheafterthelastaccessbeforetheexpirationactionoccurs.
EntryIdleTimeout
TheidletimeoutcounterforanobjectisresetwhenitsTTLcounterisreset.Anentry’sidletimeoutcounterisalsoresetwhenevertheentryisaccessedthrougha get
Theidletimeoutcounterforaregionisresetwhenevertheidletimeoutisresetforoneofitsentries.
UsingStatisticstoMeasureExpirationExpirationismeasuredbycomparingexpirationattributesettingswiththelastaccessedtimeandlastmodifiedtimestatistics.Thesestatisticsaredirectlyavailabletoapplicationsthroughthe CacheStatistics objectthatisreturnedbythe Region::getStatistics and RegionEntry::getStatistics functions.The CacheStatistics objectalsoprovidesafunctionforresettingthestatisticscounters.
ExpirationActionsYoucanspecifyoneofthefollowingactionsforeachexpirationattribute:
Destroy.Removestheobjectcompletelyfromthecache.Forregions,allentriesaredestroyedaswell.Destroyactionsaredistributedaccordingtotheregion’sdistributionsettings.
Invalidate.Markstheobjectasinvalid.Forentries,thevalueissetto NULL .Youinvalidatearegionbyinvalidatingallitsentries.Invalidateactionsaredistributedaccordingtotheregion’sdistributionsettings.Whenanentryisinvalid,a get causesthecachetoretrievetheentryaccordingtothestepsdescribedinEntryRetrieval.
Localdestroy.Destroystheobjectinthelocalcachebutdoesnotdistributetheoperation.
Localinvalidate.Invalidatestheobjectinthelocalcachebutdoesnotdistributetheoperation.Note:Destructionandinvalidationcausethesameeventnotificationactivitieswhethercarriedoutexplicitlyorthroughexpirationactivities.
RegionExpirationExpirationactivitiesindistributedregionscanbedistributedorperformedonlyinthelocalcache.Soonecachecouldcontrolregionexpirationforanumberofcachesinthedistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 83 9.1
Page 84
©CopyrightPivotalSoftwareInc,2013-2019 84 9.1
Page 85
LATESTVERSION:9.1.1- RELEASENOTES
ApplicationPlug-ins
TheAPIprovidestheframeworkforapplicationplug-inswithcallbackfunctionsfortheappropriateevents.Yourclassesandfunctionscancustomizetheseforyourapplication’sneeds.Whencreatingaregion,specifytheseaspartoftheregion’sattributessettings.Forregionsalreadyinthecache,youcanspecifynew CacheLoader , CacheWriter ,and CacheListenertheregion’s AttributesMutator .The PartitionResolver isnotmutable.
CacheLoader :Adataloadercalledwhenanentrygetoperationfailstofindavalueforagivenkey.Acacheloaderisgenerallyusedtoretrievedatafromanoutsidesourcesuchasadatabase,butitmayperformanyoperationdefinedbytheuser.Loadersareinvokedaspartofthedistributedloadingactivitiesforentryretrieval,describedinEntryRetrieval
CacheWriter :Asynchronouseventlistenerthatreceivescallbacksbeforeregioneventsoccurandhastheabilitytoaborttheoperations.Writersaregenerallyusedtokeepaback-enddatasourcesynchronizedwiththecache.
CacheListener :Anasynchronouseventlistenerforregioneventsinthelocalcache.
PartitionResolver :Usedforsingle-hopaccesstopartitionedregionentriesontheserverside.ThisresolverimplementationmustmatchthatofthePartitionResolverserverside.
ThefollowingXMLdeclarationspecifiesacacheloaderforaregionwhentheregioniscreated.
<region-attributes><cache-loaderlibrary-name="appl-lib"library-function-name="createCacheLoader"></cache-loader></region-attributes>
Therestofthissectiongivesmoredetaileddescriptionsoftheseapplicationplug-ins,followedbyspecialconsiderationsforplug-insindistributedregionsandsomeguidelinesforwritingcallbacks.
CacheLoaderAcacheloaderisanapplicationplug-inusedtoloaddataintotheregion.Whenanentryisrequestedthatisunavailableintheregion,acacheloadermaybecalledupontoloadit.Generally,youuseacacheloadertoretrievethedatafromadatabaseoranothersourceoutsidethedistributedsystem,butitmayperformanyoperationdefinedbytheuser.
The CacheLoader interfaceprovidesonefunction, load ,forcustomizingregionentryloading.Adistributedregionmayhavecacheloadersdefinedinanyorallcacheswheretheregionisdefined.Whenloadinganentryvalue,alocallydefinedcacheloaderisalwaysusedbeforearemoteloader.Indistributedregions,loadersareavailableforremoteentryretrieval.
CacheWriterAcachewriterisanapplicationplug-inthatsynchronouslyhandleschangestoaregion’scontents.Itisgenerallyusedtokeepback-enddatasourcessynchronizedwithacacheregion.Acachewriterhascallbackfunctionstohandleregiondestructionandentrycreation,update,anddestruction.Thesefunctionsareallcalledbeforethemodificationhastakenplaceandcanaborttheoperation.
Youcanalsousecachewriterstostoredatathatyouwanttomakepersistent.
CacheListenerAcachelistenerisanapplicationplug-inthatasynchronouslyhandleschangestoaregion’scontents.Acachelistenerhascallbackfunctionstohandleregiondestructionandinvalidation,alongwithentrycreation,update,invalidation,anddestruction.Thesefunctionsarecalledasynchronouslyafterthemodificationhastakenplace.
ThisdeclarativeXMLexampleestablishesacachelistenerwhenaregioniscreated:
<regionname="region11"><region-attributes><cache-listenerlibrary-name="appl-lib"library-function-name="createCacheListener"/></region-attributes></region>
Unlikecacheloadersandcachewriters,cachelistenersonlyreceiveeventsforentriestowhichtheclienthasperformedoperationsorregisteredinterest.
Whenthelistenerisattachedtoaregionwithcachingdisabled,theoldvalueisalways NULL .
©CopyrightPivotalSoftwareInc,2013-2019 85 9.1
Page 86
Note:Donotperformregionoperationsinsidethecachelistener.Onceyouhaveconfiguredacachelistener,theeventsuppliesthenewentryvaluestotheapplication.Performingagetwithakeyfromthe EntryEvent canresultindistributeddeadlock.Formoreaboutthis,seetheAPIdocumentationfor EntryEvent .
Whenaregiondisconnectsfromacachelistener,youcanimplementthe afterRegionDisconnected callback.Thiscallbackisonlybeinvokedwhenusingthe pool APIand subscriptionenabledonthepool.Forexample:
classDisconnectCacheListener:publicCacheListener{voidafterRegionDisconnected(constRegionPtr®ion){printf("AfterRegionDisconnectedeventreceived");}};
PartitionResolverThissectionpertainstodataaccessinserverregionsthathavecustompartitioning.CustompartitioningusesaJava PartitionResolver tocolocatelikedatainthesamebuckets.Fortheclient,youcanusea PartitionResolver thatmatchestheserver’simplementationtoaccessdatainasinglehop.Withsingle-hopdataaccess,theclientpoolmaintainsinformationonwhereapartitionedregion’sdataishosted.Whenaccessingasingleentry,theclientdirectlycontactstheserverthathoststhekey–inasinglehop.
Note:Singlehopisusedforthefollowingoperations: put , get , destroy , putAll , getAll , removeAll and onRegion functionexecution.
ImplementingSingle-HoponaPartitionedRegion
1. Makesurethepoolattribute, pr-single-hop-enabled ,issetto true ornotset.Itis true bydefault.
2. Iftheserverusesacustom PartitionResolver installanimplementationof PartitionResolver intheclientregionthatreturns,entryforentry,thesamevalueastheserver’sJavaPartitionResolver implementation.Theserverusestheresolvertocolocatelikedatawithinapartitionedregion.Iftheserverdoesnotuseacustomresolver,thedefaultresolversinclientandservermatch,sosinglehopwillworktherebydefault.
Disablesinglehopbehaviorforaregionbysettingitspoolattribute pr-single-hop-enabled to false .
See<client-cache>ElementReference intheserver’sdocumentationforinformationonsetting pr-single-hop-enabled .
SeetheserverdocumentationonPartitionedRegions formoreinformation,includingcolocatinglikedatawithinapartitionedregionandhowtogetthebestperformancewithPRsinglehop.
ImplementingaPartitionResolver
SeetheserverdocumentationonCustom-PartitioningandColocatingData forinformationoncustom-partitioningtheserverpartitionedregions.
1. Implement PartitionResolver inthesameplacethatyoudidintheserver–customclass,key,orcachecallbackargument.
2. Programtheresolver’sfunctionsthesamewayyouprogrammedthemintheJavaimplementation.Yourimplementationmustmatchtheserver’s.Exampleofprogrammingthe PartitionResolver inC++:
©CopyrightPivotalSoftwareInc,2013-2019 86 9.1
Page 87
classTradeKeyResolver:publicPartitionResolver{private:stringm_tradeID;intm_month;intm_year;public:TradeKeyResolver(){}TradeKeyResolver(intmonth,intyear){m_month=month;m_year=year;}
~TradeKeyResolver(){}
staticPartitionResolverPtrcreateTradeKeyResolver(){PartitionResolverPtrtradeKeyResolver(newTradeKeyResolver());returntradeKeyResolver;}constchar*getName(){return"TradeKey";}CacheableKeyPtrgetRoutingObject(constEntryEvent&opDetails){returnCacheableKey::create(m_month+m_year);}};
Exampleofprogrammingthe PartitionResolver inC#:
usingSystem;usingSystem.Threading;usingApache.Geode.Client;classTradeKeyResolver:IPartitionResolver{privateintm_month=0;privateintm_year=0;
publicstaticTradeKeyResolverCreateTradeKeyResolver(){returnnewTradeKeyResolver();}
publicvirtualICacheableKeyGetRoutingObject(EntryEvententry){returnnewCacheableInt32(m_month+m_year);}
publicvirtualStringGetName(){return"TradeKeyResolver";}}
3. Installtheresolverintheregion.Useoneofthesemethods:XMLpartitionresolverdeclaration:
<regionname="trades"refid="CACHING_PROXY"><region-attributes><partition-resolverlibrary-name="appl-lib"library-function-name="createTradeKeyResolver"/></region-attributes></region><poolfree-connection-timeout="12345"idle-timeout="5555"load-conditioning-interval="23456"max-connections="7"min-connections="3"name="test_pool_1"ping-interval="12345"read-timeout="23456"retry-attempts="3"server-group="ServerGroup1"socket-buffer-size="32768"statistic-interval="10123"subscription-ack-interval="567"subscription-enabled="true"subscription-message-tracking-timeout="900123"subscription-redundancy="0"thread-local-connections="5"pr-single-hop-enabled="true"><locatorhost="localhost"port="34756"/></pool>
Programmaticpartitionresolverinstallation:
©CopyrightPivotalSoftwareInc,2013-2019 87 9.1
Page 88
voidsetPartitionResolver(){CachePtrcachePtr=CacheFactory::createCacheFactory()->create();PartitionResolverPtrresolver(newTradeKeyResolver());RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(PROXY)->setClientNotificationEnabled(true)->setPartitionResolver(resolver);RegionPtrregionPtr=regionFactory->create("Trades");}
Yourimplementationof PartitionResolver mustmatchthatoftheserverside.
UsingAttributesMutatortoModifyaPlug-InAcachelistener,cacheloaderorcachewritercanbeaddedtoorremovedfromaregionaftertheregioniscreatedbyretrievingandrunningtheRegion object’s AttributesMutator
Mutableattributesdefineoperationsthatarerunfromtheclientitself.
Thisexampleshowshowtouse AttributesMutator todynamicallyaddacachelistenertoanexistingregion.
voidsetListener(RegionPtr®ion){CacheListenerPtrregionListener=newTestCacheListener();AttributesMutatorPtrregionAttributesMutator=region->getAttributesMutator();
//Changecachelistenerforregion.regionAttributesMutator->setCacheListener(regionListener);}
Theplug-inscanalsobeimplementedusingadynamicallylinkedlibrary.Theclassisnotavailabletotheapplicationcodeinthiscase,soa factory methodisrequiredbythefunctionalongwiththenameofthelibrary.
Thisexampleshowshowtouse AttributesMutator alongwiththe setCacheListener functiontoobtainanewcachelistenerobjectusingthe factory functionprovidedbythelibrary.Next,thelistenerissetfortheregion.
voidsetListenerUsingFactory(RegionPtr®ion){AttributesMutatorPtrregionAttributesMutator=region->getAttributesMutator();
//Changecachelistenerforregion.regionAttributesMutator->setCacheListener("Library","createTestCacheListener");}
Touse AttributesMutator toremoveaplug-infromaregion,settheplug-in’svalueto NULLPTR ,asshowninthefollowingexample.
voidremoveListener(RegionPtr®ion){CacheListenerPtrnullListener=NULLPTR;AttributesMutatorPtrregionAttributesMutator=region->getAttributesMutator();
//ChangecachelistenerforregiontoNULLPTRregionAttributesMutator->setCacheListener(nullListener);}
ConsiderationsforImplementingCallbacksKeepyourcallbackimplementationslightweightandpreventsituationsthatmightcausethemtohang.Forexample,donotperformdistributionoperationsordisconnectsinsideeventhandlers.
Yourcodeshouldhandleanyexceptionsthatitgenerates.Ifnot,GemFirehandlesthemaswellaspossible.BecauseC++hasnostandardforexceptions,inmanycasesGemFirecanonlyprintan unknown
errormessage.
©CopyrightPivotalSoftwareInc,2013-2019 88 9.1
Page 89
SpecifyingApplicationPlug-InAttributesTheplug-inattributesallowyoutocustomizeclientregionbehaviorforloading,updating,deleting,andoverflowingregiondataandforaccessingdatainserverpartitionedregions.Allclientplug-insareavailablethroughtheC++and.NETAPI.
Applicationplug-insforcacheregionsinclientscanbedeclaredeitherprogrammaticallyorinthe cache.xml file.
Figure:WhereApplicationPlug-InsRun
©CopyrightPivotalSoftwareInc,2013-2019 89 9.1
Page 90
LATESTVERSION:9.1.1- RELEASENOTES
CacheManagementThissectioncoverscachemanagement.
Client-to-ServerConnectionProcessItisimportanttounderstandthesequenceofeventsthatoccurwhentheclientconnectswithaserver.
ControllingCacheSizeYoucancontrolcachesizethroughregionsizelimits,cachesizelimits,oracombinationofthetwo.
ManagingtheLifetimeofaCachedObjectAllcacheableobjectsderivefrom SharedBase ,whichprovidesreferencecounting.Cacheableobjectsarereferencedusing SharedPtr types.
UsingThreadSafetyinCacheManagementWhenyouperformstructuralchangesonyourcache,suchascreatingorclosingaCache , Pool ,or Region ,synchronizeyouroperationsordotheminasinglethread.
TroubleshootingThissectionprovidestroubleshootinginformationfortheclient.
©CopyrightPivotalSoftwareInc,2013-2019 90 9.1
Page 91
LATESTVERSION:9.1.1- RELEASENOTES
Client-to-ServerConnectionProcessItisimportanttounderstandthesequenceofeventsthatoccurwhentheclientconnectswithaserver.
1. Aclientregionisconfiguredin cache.xml orprogrammaticallywithasetofserverconnectionendpoints.Serverendpointsidentifyeachcacheserverbyspecifyingtheserver’snameandportnumber.Clientthreadsobtain,use,andreleaseaconnectiontoaconnectionpoolthatmaintainsnewconnections.Thenumberofconnectionsthataclientcanestablishisgovernedbythepool’s min-connections and max-connections settings,eitherusingclientXMLconfigurationorprogrammaticallythroughthe CacheFactory::setMinConnections() andCacheFactory::setMaxConnections() functions.Thedefaultsfor min-connections is1and max-connections is-1meaningtheconnectioncountcangrowtoaccommodatethenumberofactivethreadsperformingregionoperations.Thisexampleshowshowtouse cache.xml toconfigureaclientregionwithendpointssettotwocacheservers:
<poolname="examplePool"subscription-enabled="true"><serverhost="java_servername1"port="java_port1"/><serverhost="java_servername2"port="java_port2"/></pool><regionname="ClientRegion"refid="CACHING_PROXY"><region-attributespool-name="examplePool"/></region>
TCPconnectionsontheclientarespecifiedatthecachelevel,orbyoverridingendpointsforspecificregions.Theconnectionsarecreatedastheregionsarecreated.Inaddition,connectionscanalsogetcreatedforqueryingwithouthavinganycreatedregions.Inthiscase,whenendpointsaredefinedatthecachelevelnoregionsareyetcreatedandaqueryisfired.Youcanconfigureclient-serverconnectionsintwoways.Useeithertheregion/cacheendpointsorthePoolAPI.FormoreinformationaboutthepoolAPI,seeUsingConnectionPools.
2. Theclientannouncestotheserverwhichentriesitwishestohaveupdatedbyprogrammaticallyregisteringinterestinthoseentries.SeeRegisteringInterestforEntriesinformation.
3. Theclient cache.xml fileshouldhavethefollowingparametersconfiguredsotheclientcanupdatetheserverandtheclientcanreceiveupdatesfromtheserver:
Cachingenabledintheclientregion,byusingthe CACHING_PROXY RegionShortcut settingintheregionattribute refid .Alistenercouldalsobedefinedsoeventnotificationoccurs.Youcanuseboth,butatleastoneofthetwomethodsmustbeusedbytheclienttoreceiveeventnotifications.Set subscription-enabled to true sotheclientreceivesupdatenotificationsfromtheserverforentriestowhichithasregisteredinterest.
4. AclientapplicationcallstheC++or.NETAPItoconnecttoacacheserver.
5. Theclientandthecacheserverexchangeahandshakeoveraconfiguredendpointtocreateaconnection.
6. Any create , put , invalidate ,and destroy eventssenttotheserverarepropagatedacrossthedistributedcachesotheclientcanreceivetheevents.
Note:Youmaybeabletoimprovesystemperformancebymakingadjustmentstothecacheserver.
©CopyrightPivotalSoftwareInc,2013-2019 91 9.1
Page 92
LATESTVERSION:9.1.1- RELEASENOTES
ControllingCacheSizeYoucancontrolcachesizethroughregionsizelimits,cachesizelimits,oracombinationofthetwo.
GemFirecontrolsregionsizebymovingleastrecentlyused(LRU)entriesfromtheregionorfromallcacheregions.
ControllingRegionSizeYoucancapthesizeofanyregionwiththeregionattributeLruEntriesLimit.YoucanspecifywhethertodestroytheentriesoroverflowthemtodiskintheattributeDiskPolicyoverflowentriestodisk,youmustalsospecifytheattributePersistenceManager.
ControllingCacheSizeYoucancontroloverallcachesizewiththeheap-lru-limit,whichissetin geode.properties .Thispropertysetsthemaximumamountofmemoryusedforthecache,inmegabytes.Ifanewentrycausesmemorytogrowpastthislimit,theLRUalgorithmiscalledtoevictentries.HeapLRUcausesevictiontooccuronallregionsinthecache,overridingregion-levelLruEntriesLimitsettingswhenitneedstoreclaimmemory.
Foreachregion,evictionsareperformedaccordingtotheregion’s DiskPolicy and PersistenceManager settings.Ifyouuse heap-lru-limit ,reviewtheseregionattributesforallyourcachingregions,tobesureyouareevictingthewayyouwantto.
Therelatedheap-lru-deltaproperty,alsosetin geode.properties ,istheamountofmemorytofreeuponcetheLRUevictionshavebegun.Memoryisreclaimeduntiltheamountofmemoryusedisbelow heap-lru-limit minus heap-lru-delta .
©CopyrightPivotalSoftwareInc,2013-2019 92 9.1
Page 93
LATESTVERSION:9.1.1- RELEASENOTES
ManagingtheLifetimeofaCachedObjectAllcacheableobjectsderivefrom SharedBase ,whichprovidesreferencecounting.Cacheableobjectsarereferencedusing SharedPtr types.
When SharedPtr retrievesacachedobject,theobjectremainsaliveaslongasthatpointerorthecacheitselfreferencestheobject.
Aclientmayhavemanypointersthatreferenceanobject.Regardlessofhowmanypointerstotheobjectaredeleted,theobjectremainsaliveuntilthelastremainingpointerisdeleted.Atthatpointtheobjectisdeleted.
Thisisaverysimpleexample:
CacheableStringPtrp=CacheableString::create("string");region.put("key",p);
Intheexample:
Theactofobjectcreationallocatesmemoryandinitializestheobject.
Whenyouassigntheobjecttoa SharedPtr ,yourelinquishcontrolofthelifetimeofthatobjecttothereferencecountingmechanismforthecache.
Theputoperationdoesnotactuallycopytheobjectintothecache.Rather,itcopiesa SharedPtr intothecache’shashmap.Consequently,theobjectremainsaliveinthecachewhentheoriginal SharedPtr goesaway.
Theclientcanmakeuseofanobjectafteryouhaveinitializedtheobject.Forexample,another SharedPtr mightissuea get toretrievetheobjectfromthecache:
CacheableStringPtrp2=region.get("key");
Because p (theoriginal SharedPtr )and p2 pointtothesameobjectinmemory,itispossibleundersomecircumstancesformultiple SharedPtr typestoworkonthesameobjectindatastorage.
Note:Onceyouhaveputanobjectintothecache,donotdeleteitexplicitly.Attemptingtodosocanproduceundesirableresults.
ChangedObjectsIfanobjectupdateisreceived,thecachenolongerholdsthesameobject.Rather,itholdsacompletelydifferentinstanceoftheobject.Theclientdoesnotseetheupdatesuntilitcallsaget tofetchtheobjectagainfromthelocalcache,or(inacacheplug-in)calls EntryEvent::getNewValue .
Formoreaboutplug-ins,seeOverviewofApplicationPlug-Ins.
ObjectExpirationWhenacacheautomaticallydeletesanobjectasaresultofanexpirationaction,thereferencecountingpointersprotecttheclientfromsituationsthatmightotherwiseresultifthecacheactuallyfreedtheobject’smemory.Instead,theclientdisconnectstheobjectfromthecachebydeletingthecache’s SharedPtr reference,whileleavinguntouchedanyclientthreadswitha SharedPtr tothatobject.
ObjectLifetimeAcrosstheDistributedCacheAnobjectremainsaliveuntileverycopyoftheobjectisgone.Indistributedregions,expirationactivitiescanbelocalordistributed,dependingonaregion’sdistributionsettings.Onecachecouldcontroltheexpirationofallcopiesofanobjectinallthecachesinthedistributedsystem.Alternatively,eachcachecouldcontroltheexpirationofitsownlocalcopyoftheobject.Iftheconfigurationgiveseachcachelocalcontrol,andtheexpirationparametersaresettodifferentlengthsoftimeindifferentcaches,somecopiesofanobjectmaystillexistafterithasdisappearedinothercaches.SeeSpecifyingExpirationAttributesformoreinformation.
©CopyrightPivotalSoftwareInc,2013-2019 93 9.1
Page 94
LATESTVERSION:9.1.1- RELEASENOTES
UsingThreadSafetyinCacheManagementWhenyouperformstructuralchangesonyourcache,suchascreatingorclosingaCache , Pool ,or Region ,synchronizeyouroperationsordotheminasinglethread.
Othernon-structuraloperations,likeregiongets,puts,andqueries,arethreadsafe,andyoucanperformtheminamultithreadedway.Therearecaveatstothis,forexample,whentwothreadsupdatethesamekeysimultaneously,thereisnowaytodeterminewhichthread’soperationwillprevail.
Youmayneedtoprotectcachedobjectsfromconcurrentusageandmodification.Theclientdoesnotguardcachedobjectsthemselvesfromconcurrentaccess.
Alwayscatchandhandleexceptionsthatmaybethrown,forproblemsliketryingtocreatea Pool withthesamenamemorethanonce.
©CopyrightPivotalSoftwareInc,2013-2019 94 9.1
Page 95
LATESTVERSION:9.1.1- RELEASENOTES
TroubleshootingThissectionprovidestroubleshootinginformationfortheclient.
CannotAcquireWindowsPerformanceDataWhenyouattempttorunperformancemeasurementsfortheclientonWindows,youmayencounterthefollowingerrormessageintherunlogs:
Can'tgetWindowsperformancedata.RegQueryValueExreturned5
ThiscanoccurbecauseincorrectinformationisreturnedwhenaWin32applicationcallstheANSIversionof RegQueryValueEx Win32APIwith HKEY_PERFORMANCE_DATA
describedinMicrosoftKBarticleID226371athttp://support.microsoft.com/kb/226371/en-us .TosuccessfullyacquireWindowsperformancedata,youneedtoverifythatyouhavetheproperregistrykeyaccesspermissionsinthesystemregistry.Inparticular,makesurethat Perflib inthefollowingregistrypathisreadable( KEY_READ access)bytheGemFireprocess:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\Perflib
Anexampleofreasonablesecurityontheperformancedatawouldbetograntadministrators KEY_ALL_ACCESS andinteractiveusers KEY_READ access.Thisparticularconfigurationpreventsnon-administratorremoteusersfromqueryingperformancedata.
Seehttp://support.microsoft.com/kb/310426 andhttp://support.microsoft.com/kb/146906 forinstructionsabouthowtoensurethatGemFireprocesseshaveaccesstotheregistrykeysassociatedwithperformance.
GeneratingaProcessMemoryDumpImageforFatalErrorsYoucangenerateaprocessmemorydumpimage(corefilesinUnixsystemsandminidumpsinWindows).Theimageisproducedwhenafatalerroroccursthatnormallyterminatestheprogram.
Whenthesystemproperty crash-dump-enabled issetto true ,adumpimageisgenerated(thedefaultis true ).Thedumpfileisgeneratedinthesamelocationasthe log-filehasthesameprefixasthelogfile.Thenameis <prefix>-<time>.core.<pid> inUnix,and <prefix>-<time>-<pid>.dmp inWindows).
Unixsystemsgeneratecorefilesautomaticallyforsucherrors,butthisoptionisusefulforprovidingacustomlocationandname,aswellasforsystemswherecoredumpgenerationisdisabled.ForUnix,whensystemcoredumpgenerationisturnedon( ulimit-
c)thispropertycanbesetto false .
For.NETclients,whenthispropertyissetthen AccessViolation exceptionsaretrappedandacrashdumpiscreatedtoassistwithfurtheranalysis.ApplicationsreceiveaFatalInternalException forthiscase,withthe InnerException settotheoriginating AccessViolationException .
Thisrequirestheavailabilityof dbghelp.dll onWindows,eitherinthesamedirectoryas apache-geode.dll orinthesystem PATH .Thefileisinstalledbydefault,thoughforWindows2000anewerversionmayberequiredforminidumps.ForUnixsystems,the gcore commandshouldbeavailable(gdb>5.2onLinux;availablebydefaultinSolaris).
©CopyrightPivotalSoftwareInc,2013-2019 95 9.1
Page 96
LATESTVERSION:9.1.1- RELEASENOTES
C++ClientAPIThissectiondescribestheprimaryclassesandusageconventionsfortheC++clientAPI.ItdemonstrateshowtousetheAPItocreatecachesandperformdataserialization.
TheC++APIdocumentationisavailableat[C++API]((http://geode.apache.org/docs/ ).ItprovidesextensiveimplementationdetailsfortheC++structuresandfunctions.
SeveralexampleAPIprogramsareincludedinthe SampleCode directory.SeeQuickStartExamples .
AbouttheC++ClientAPITheC++clientAPIallowsC++developerstoprogrammaticallycreate,populate,andmanageadistributedsystem.TheC++libraryisthread-safe,exceptwherespecifiedotherwiseintheAPIdocumentation.
CreatingaCacheThecodesnippetsinthissectionshowcachecreation.
CreatingaProxyClient-SideRegionThissectionprovidescodeexamplesforcreatingandcustomizingproxyclient-sideregions.
AddinganEntrytotheCacheYoucanpopulateaclientregionwithcacheentriesusingthe Region::put orthe Region::create APIfunctions.Codeexamplesdemonstratetheseactions.
AccessinganEntryThestandard Region::getAPI methodreturnsthevalueassociatedwiththespecifiedkey,andpassesthecallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
RemovinganEntryThestandard Region::remove APIremovestheentrywiththespecifiedkeyandprovidesauser-definedparameterobjecttoany CacheWriter or CacheListener invokedintheprocess.
SerializingDataAlldatamovedoutofthelocalcachemustbeserializable.
ImplementingUser-DefinedObjectsinJavaClientsYoucanuseoneoftwomethodstoimplementauser-definedobjectinaJavaclientthatworkswithC++clients: Instantiator.register and DataSerializable .
UsingaCustomClassThisexampleshowshowtousethedefined BankAccount customkeytypeandthe AccountHistory valuetype.
CreatingNewStatisticsThisexampleprovidesaprogrammaticcodesampleforcreatingandregisteringnewstatistics.
©CopyrightPivotalSoftwareInc,2013-2019 96 9.1
Page 97
LATESTVERSION:9.1.1- RELEASENOTES
AbouttheC++ClientAPITheC++clientAPIallowsC++developerstoprogrammaticallycreate,populate,andmanageadistributedsystem.TheC++libraryisthread-safe,exceptwherespecifiedotherwise.
Thischaptergivesageneraloverviewoftheclassesinthe apache::geode::client namespace.Forcompleteandcurrentinformationontheclasseslistedhere,seetheC++API
CacheClassesTheC++clientAPIhasthefollowingcacheclasses:
CacheFactory.Usethisclasstocreateandconfigurea Cache instance.If cache.xml isspecified,thecacheiscreatedbasedonthedeclarationsloadedfromthatfile.
Cache.EntrypointtotheclientcachingAPI.Thecacheiscreatedbycallingthe create functionofthefactoryclass, CacheFactory .RegionsareconfiguredandobtainedusingtheCache::createRegionFactory() API.
RegionClassesTheC++clientAPIhasthefollowingregionclasses:
Region.Providesfunctionsformanagingregionsandcacheddata.Usethesefunctionstoperformthefollowingactions:
Retrieveinformationabouttheregion,suchasitsparentregionandregionattributeobjects.Invalidateordestroytheregion.Create,update,invalidateanddestroyregionentries.Retrieveregionentrykeys,entryvalues,andRegionEntryobjects,eitherindividuallyorasentiresets.Retrievethestatisticsobjectassociatedwiththeregion.Setandgetuser-definedattributes.
RegionEntry.Containsthekeyandvaluefortheentry,andprovidesallnon-distributedentryoperations.Thisobject’soperationsarenotdistributedanddonotaffectstatistics.
RegionAttributeClassesThenativeclientC++APIhasthefollowingregionattributeclasses:
RegionAttributes.Holdsallattributevaluesforaregionandprovidesfunctionsforretrievingallattributesettings.Thisclasscanbemodifiedbythe AttributesMutatorregioncreation.
AttributesMutator.Allowsmodificationofanexistingregion’sattributesforapplicationplug-insandexpirationactions.Eachregionhasan AttributesMutator instance.
ApplicationPlug-InClassesTheC++clientAPIhasthefollowingapplicationplug-inclasses:
CacheLoader.Loadsdataintoaregiononacachemiss.
CacheWriter.Synchronouslyhandlesregionandentryeventsbeforetheeventsoccur.Entryeventsare create , update , invalidate ,and destroy .Regioneventsareinvalidateanddestroy.Thisclasshastheabilitytoabortevents.
CacheListener.Handlesregionandentryeventsaftertheyoccur.Entryeventsare create , update , invalidate ,and destroy .Regioneventsare invalidate
EventHandlingClassesTheC++clientAPIhasthefollowingeventhandlingclasses:
RegionEvent.Providesinformationabouttheevent,suchasinwhatregiontheeventoriginated,whethertheeventoriginatedinacacheremotetotheeventhandler,andwhethertheeventresultedfromadistributedoperation.
EntryEvent.Providesallavailableinformationforthe RegionEvent ,andprovidesentry-specificinformationsuchastheoldandnewentryvaluesandwhethertheeventresultedfroma load operation.
©CopyrightPivotalSoftwareInc,2013-2019 97 9.1
Page 98
StatisticsAPIThe StatisticsType APIrepresentsablueprintforthesametypeof Statistics .The StatisticsType APIisacollectionof StatisticDescriptor .Internally,each StatisticDescriptor describesdataofeachindividualstatistic. StatisticsFactory providesfunctionalityforcreating StatisticDescriptor , StatisticsType ,and Statistics objects.
CacheStatistics–Thisclassdefinescommonstatisticsfunctions. Region and RegionEntry bothhavefunctionsthatreturna CacheStatistics objectforaccessingandresettingtheirstatisticscounts.
StatisticDescriptor.Aninstanceofthisclassdescribesastatisticwhosevalueisupdatedbyanapplicationandmaybearchivedbythenativeclient.Eachstatistichasatypeofeitherint , long ,or double ,andeitheragaugeoracounter.Thevalueofagaugecanincreaseanddecrease,andthevalueofacounterstrictlyincreases.CreateaninstanceofStatisticDescriptor bycallingoneofthese StatisticsFactory functions: createDoubleCounter , createDoubleGauge , createIntCounter , createIntGaugecreateLongCounter , createLongGauge .
StatisticsType.Aninstanceofthisclassdescribesalogicalcollectionof StatisticDescriptors .Thesedescriptionsareusedtocreateaninstanceof Statistics .Createaninstanceof StatisticsType bycalling StatisticsFactory::createType .
Statistics.Aninstanceofthisclassrepresentsconcrete Statistics oftheassociated StatisticsType .Thisclassstoresdatarelatedtoallindividualstatisticobjects.Createaninstancebycalling StatisticsFactory::createStatistics .Thisclasshasfunctionstoget,set,andincrementstatisticvalues.
StatisticsFactory.Thisclassprovidesfunctionsforcreatinginstancesof StatisticDescriptor , StatisticsType ,and Statistics objects .Thisisasingletonclass,andyouacquireitsinstancebyusing StatisticsFactory::getExistingInstance .
Tocreatenewstatistics,seeCreatingNewStatistics.
©CopyrightPivotalSoftwareInc,2013-2019 98 9.1
Page 99
LATESTVERSION:9.1.1- RELEASENOTES
CreatingaCacheThecodesnippetinthissectionshowscachecreation.
Whenyoucreateyourcache,thesystemautomaticallyconnectsyourprocesstotheservertier.Forsystemswithsecurityenabled,thecredentialsforaconnectingclientareauthenticatedwhenitcreatesthecache.SeeSecurityformoreinformationaboutauthenticatedconnections.
CreatingtheSystemConnectionandtheCacheInthisexample,theapplicationcreatesthecachebycallingthe CacheFactory::create function,specifyingtheserverstoconnectto:
CacheFactoryPtrcacheFactory=CacheFactory::createCacheFactory();CachePtrcachePtr=cacheFactory->addServer("localhost",40404)->addServer("localhost",40405)->setSubscriptionEnabled(true)->create();
©CopyrightPivotalSoftwareInc,2013-2019 99 9.1
Page 100
LATESTVERSION:9.1.1- RELEASENOTES
CreatingaProxyClient-SideRegionThissectionprovidescodeexamplesforcreatingandcustomizingproxyclient-sideregions.
Note:CreatingaregionthroughtheclientAPIcreatesonlyaproxyclient-sideregion.Acorrespondingregionwiththesamenameandpathshouldalsoexistontheserversthathavebeenconfiguredforclientconnectionsanduponwhichtheclientwillperformitsoperations.
Tocreatearegion,youcreatea RegionFactory usingthe RegionShortcut thatmostcloselyfitsyourregionconfiguration.Fromthat,createyourregion,customizingthesettingsasregionattributesasneeded.
CreatingaCACHING_PROXYRegionThisexamplecreatesaregionusingaCACHING_PROXY RegionShortcut withnofurthermodifications:
RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);regionPtr=regionFactory->create("exampleRegion");
CreatingaCACHING_PROXYRegionwithLRUThisexamplecreatesaregionbasedontheCACHING_PROXYRegionShortcutwithtwoadditionalregionattributessettings.Forinformationonthesettings,seeRegionAttributesDescriptions.
RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);regionPtr=regionFactory->setLruEntriesLimit(20000)->setInitialCapacity(20000)->create("exampleRegion");
©CopyrightPivotalSoftwareInc,2013-2019 100 9.1
Page 101
LATESTVERSION:9.1.1- RELEASENOTES
AddinganEntrytotheCacheYoucanpopulateaclientregionwithcacheentriesusingthe Region::put orthe Region::create APIfunctions.
The put functionplacesanewvalueintoaregionentrywiththespecifiedkey,whilethe create functioncreatesanewentryintheregion.Bothfunctionsprovideauser-definedparameterobjecttoanycachewriterinvokedintheprocess,andnewvaluesforbothfunctionsarepropagatedtoaconnectedcacheserver.
AddingEntriesUsingcreateWhentheputfunctionaddsanentry,thepreviousvalueisoverwrittenifthereisalreadyanentryassociatedwiththespecifiedkeyintheregion.Inthisexample,theprogramusestheAPItoput100entriesintothecachebyiterativelycreatingkeysandvalues,bothofwhichareintegers.
for(int32_ti=0;i<100;i++){regionPtr->put(i,CacheableInt32::create(i));}
BulkPutOperationsUsingputAllYoucanbatchupmultiplekey/valuepairsintoahashmapandputthemintothecachewithasingleoperationusingtheRegion::putAll APIfunction.Eachentryisprocessedforinterestregistrationontheserver,soeachentryrequiresitsownuniqueeventID.Updatesandcreatescanbemixedina putAll operation,sothoseeventsneedtobeaddressedonthecacheserverforappropriatecachelistenerinvocationondistributedsystemmembers.Mapentriesretaintheiroriginalorderwhentheyareprocessedattheserver.
Thefollowingtableliststheclientandcacheserverstatisticsfor putAll .
StatisticType ChartName Description
CachePerfStats PutallsTotalnumberoftimesamapisaddedorreplacedinthecacheasaresultofalocaloperation.Alsoreportsthenumberofoperations.
CachePerfStats putallTime Totaltimetoreplaceamapinthecacheasaresultofalocaloperation.
CacheServerStats
putAllRequests Numberof putAll requests.
CacheServerStats
putAllResponses Numberof putAll responseswrittentothecacheclient.
CacheServerStats
processPutAllTime Totaltimetoprocessacacheclient putAll request,includingthetimetoputallobjectsintothecache.
CacheServerStats
readPutAllRequestTime Totaltimetoread putAll requests.
CacheServerStats
writePutAllResponseTime
Totaltimetowrite putAll responses.
CacheClientStats
putAll Numberof putAll requestssenttothecacheserver.
CacheClientStats
sendPutAllTime Totaltimefor sendPutAll .
Table1.putAllStatisticsforCacheServerandClient
The putAll functionalsosupportsprovidingacallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
©CopyrightPivotalSoftwareInc,2013-2019 101 9.1
Page 102
LATESTVERSION:9.1.1- RELEASENOTES
AccessinganEntryThe Region::get methodreturnsthevalueassociatedwiththespecifiedkey,andpassesthecallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
Ifthevalueisnotpresentlocally,itisrequestedfromthecacheserver.Ifthecacheserverrequestisunsuccessful,alocalcacheloaderisinvoked.
Theentryvalueiseitherretrievedfromthelocalcacheorfetchedbytheregion’slocallydefinedcacheloader.
Inthefollowingexample,theprogramusestheAPItodoagetforeachentrythatwasputintothecache:
for(int32_ti=0;i<100;i++){CacheableInt32Ptrres=dynCast<CacheableInt32Ptr>(regionPtr->get(i));}
BulkGetOperationsUsinggetAllYoucanusethe Region::getAll methodtogetvaluesforanarrayofkeysfromthelocalcacheorserver.Ifthevalueforakeyisnotpresentlocally,thenitisrequestedfromtheserver.
Note:Thevaluereturnedisnotcopied,somulti-threadedapplicationsshouldnotmodifythevaluedirectly,butshouldinsteadusetheupdatemethods.
The getAll methodalsosupportsprovidingacallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
©CopyrightPivotalSoftwareInc,2013-2019 102 9.1
Page 103
LATESTVERSION:9.1.1- RELEASENOTES
RemovinganEntryThe Region::remove functionremovestheentrywithspecifiedkeyandprovidesauser-definedparameterobjecttoany CacheWriter or CacheListener invokedintheprocess.
The remove callnotonlyremovesthevalue,butalsothekeyandentryfromthisregion.Theremoveoperationispropagatedtotheservertowhichtheclientisconnected.Ifthedestroyoperationfailsduetoanexceptionontheserver(forexample,a CacheServerException orsecurityexception),thenthelocalentryisstillremoved.
The remove operationupdates CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime forthisregionandtheentry.
The remove functionreturnstrueiftheentry(key,value)hasbeenremovedorfalseiftheentry(key,value)hasnotbeenremoved.
BulkRemoveOperationsUsingremoveAllYoucanusethe Region::removeAll functiontoremoveallentriesfromtheregionforacollectionofspecifiedkeys.Theeffectofthiscallisequivalenttothatofcallingdestroyonceforeachkeyinthespecifiedcollection.Ifanentrydoesnotexist,thenthatkeyisskipped.Notethatan EntryNotFoundException isnotthrown.
The removeAll functionalsosupportsprovidingacallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
©CopyrightPivotalSoftwareInc,2013-2019 103 9.1
Page 104
LATESTVERSION:9.1.1- RELEASENOTES
SerializingDataAlldatamovingoutoftheclientcachemustbeserializable.
RegionDataRequiringSerializationCertainregiontypes(includingclientregions)requireserialization.
DataSerializationOptionsTheC++clientAPIprovidestwoserializationoptions:the apache::geode::client::Serializable interfaceandGemFirePDXserialization.
SerializingDatawithPDXSerializationPDXisacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.PDXstoresdatainnamedfieldsthatyoucanaccessindividuallytoavoidthecostofdeserializingtheentiredataobject.WhenyouusePDXserializationwithaC++client,youcanregisteraPdxSerializerfortheentirecache,implementPDXserializationforeachdomainobjectoruseautomaticPDXserializationbyrunningthe pdxautoserializer tool.
SerializingDatawiththeSerializableInterfaceTheC++clientAPIprovidesa Serializable interfacethatyoucanuseforfastandcompactdataserialization.ThissectiondiscussestheGemFireserializableinterface,andpresentsimplementationexamples.
SerializingObjectGraphsIfyouhaveagraphofobjectswhereeachnodecanbeserializable,theparentnodecancall DataOutput::writeObject todelegatetheserializationresponsibilitytoitschildnodes.Similarly,yourapplicationcancall DataInput::readObject todeserializetheobjectgraph.
SerializingandAccessingDataasaBlobIfyouhavedatathatisbesthandledasablob,suchasstructsthatdonotcontainpointers,usetheserializabletype CacheableBytes . CacheableBytes isablobclassthatimplementstheserializationforyou.
©CopyrightPivotalSoftwareInc,2013-2019 104 9.1
Page 105
LATESTVERSION:9.1.1- RELEASENOTES
RegionDataRequiringSerializationCertainregiontypes(includingclientregions)requireserialization.
Regiondatainthefollowingtypesofregionsmustbeserializable:
Partitionedregions(exceptfunctionsthatadddatalocallytoapartitionedregionusethedeserializedform).
Distributedregions.
Regionsthatarepersistedoroverflowedtodisk.
Serverorclientregionsinaclient/serverinstallation.
Regionsdistributedbetweengatewaysinamulti-siteinstallation.
Regionsthatreceiveeventsfromremotecaches.
Regionsthatprovidefunctionargumentsandresults.
Tominimizethecostofserializationanddeserialization,GemFireavoidschangingthedataformatwheneverpossible.Thismeansyourdatamaybestoredinthecacheinserializedordeserializedform,dependingonhowyouuseit.Forexample,ifaserveractsonlyasastoragelocationfordatadistributionbetweenclients,itmakessensetoleavethedatainserializedform,readytobetransmittedtoclientsthatrequestit.Partitionedregiondataisalwaysstoredinserializedformwithoneexception—functionsthatadddatatoapartitionedregionlocallyusethedeserializedform.
©CopyrightPivotalSoftwareInc,2013-2019 105 9.1
Page 106
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationOptionsTheC++clientAPIgivestwoserializationoptions:the apache::geode::client::Serializable interfaceandGemFirePDXserialization.
GemFirePortableDataeXchange(PDX)serializationistherecommendedoption.PDXserializationprovidesportabilityforPDXserializableobjectssothatclientscansharedatawithJavaserversandothernon-C++clients.PDXisacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.PDXstoresdatainnamedfieldsthatyoucanaccessindividuallyinordertoavoidthecostofdeserializingtheentiredataobject.PDXalsoallowsyoutomixversionsofobjectswhereyouhaveaddedorremovedfields.
WhenusingPDXserialization,youcanuseeither PdxSerializer (forallyourdomainobjects)or PdxSerializable (foraspecificdomainobject).
PdxSerializer isusedwhenauserhasregisteredadomainclassforserializationinthecacheusingthe registerPdxSerializer API.
PdxSerializable isusedwhenthedomainclassthatauserwantstoserialize/deserializeisinheritedfromthe PdxSerializable interface,andtheuserhasregisteredthedomainclassusingthe registerPdxType(domainClass) API.
Thenon-PDXserializationoptionistousethe apache::geode::client::Serializable interface.This Serializable interfacecanbeagoodoptionperformance-wiseifthesizeofyourobjectsissmall.Serializable isusedwheneverauserdomainclassisnotinheritedby PdxSerializable ,buttheuserhasregisteredtheclasswiththe registerType API.SeeSerializingDatawiththeSerializableInterfaceformoreinformation.
Table1.SerializationOptions—ComparisonofFeatures
Handlesmultipleversionsofdomainobjects* X
Providessinglefieldaccessonserversofserializeddata,withoutfulldeserialization.SupportedalsoforOQLqueries. X
AutomaticallyportedtootherlanguagesbyGemFire-noneedtoprogramJava-sideimplementation X
WorkswithGemFiredeltapropagation X X**
Table1.SerializationOptions—ComparisonofFeatures
*Youcanmixdomainobjectversionswherethedifferencesbetweenversionsaretheadditionandremovalofobjectfields.
**SeeUsingPDXSerializationwithDeltaPropagationforrequirements.
©CopyrightPivotalSoftwareInc,2013-2019 106 9.1
Page 107
LATESTVERSION:9.1.1- RELEASENOTES
SerializingDatawithPDXSerializationPDXisacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.PDXstoresdatainnamedfieldsthatyoucanaccessindividuallytoavoidthecostofdeserializingtheentiredataobject.WhenyouusePDXserializationwiththeC++clientAPI,youcanregistera PdxSerializer fortheentirecache,implementPDXserializationforeachdomainobjectoruseautomaticPDXserializationbyrunningthe pdxautoserializer tool.
Youcanalsosettheobjectpreferenceofthecachetothe PdxInstance type,whichallowsyoutoaccessfieldsofaPDXobjectwithoutdeserializingtheentireobject.
WhenusingtheC++clientAPI,youcanopttousePDXautoserialization.Thecommandlinetool pdxautoserializer willautomaticallygenerateC++codetoPDXserializetheclassyouwanttoserialize.
SerializeYourDomainObjectswithPdxSerializerandPdxWrapperFordomainobjectsthatyoucannotordonotwanttomodify,usethe PdxSerializer andthe PdxWrapper classestoserializeanddeserializetheobject’sfields.
SerializeUsingthePdxSerializableClassDomainclassesneedtoinheritthe PdxSerializable abstractclasstoserializeandde-serializetheobject.WhenyouwriteobjectsusingPDXserialization,theyaredistributedtotheservertierinPDXserializedform.
UsingAutomaticPDXSerializationYoucanallowyourC++clientapplicationstoautomaticallyPDXserializeanddeserializedomainobjectswithouthavingtoaddanyextracodebyusingthepdxautoserializer
linetool.
ProgrammingYourApplicationtoUsePdxInstancesA PdxInstance isalightweightwrapperaroundtherawbytesofthePDXserializedobjectskeptinthecache.Itprovidesapplicationswithrun-timeaccesstofilesofaPDXserializedobject.GemFireprovidestheimplementationofthe PdxInstance class.
ConfiguringPDXtoIgnoreUnreadFieldsDuringDeserializationUsethe setPdxIgnoreUnreadFields APItocontrolwhetherPDXignoresfieldsthatwereunreadduringdeserialization.
UsingPdxInstanceFactorytoCreatePdxInstancesYoucanusethe PdxInstanceFactory APItocreatea PdxInstance fromrawdatawhenthedomainclassisnotavailableontheserver.
UsingC++EnumTypewithPDXSerializationBecausethereisno“object”basetypeinC++,enumscannotbedirectlypassedasparameterstothe writeObject and readObject API.
UsingPDXSerializationwithDeltaPropagationTousedeltapropagationwithPDXserialization,youmustimplementthe Delta interfacemethods.
©CopyrightPivotalSoftwareInc,2013-2019 107 9.1
Page 108
LATESTVERSION:9.1.1- RELEASENOTES
SerializeYourDomainObjectswithPdxSerializerandPdxWrapperFordomainobjectsthatyoucannotordonotwanttomodify,usethe PdxSerializer andthe PdxWrapper classestoserializeanddeserializetheobject’sfields.
Youregistera PdxSerializer implementationfortheentirecache,programmingitforallofthedomainobjectsthatyouhandleinthisway.ThiswayyoudonothavetoimplementthePdxSerializable interfaceforeachdomainclass.
The PdxSerializer allowsdomainclassestobeserializedanddeserializedasPDXswithoutmodificationofthedomainclass.Itrequiresonlythatthedomainclasshaveaconstructoraccessibletothe PdxSerializer tocreateaninstance.Thedomainclasswillbeheldinawrapperclass, PdxWrapper .
PdxSerializer hasthefollowingmethods:
The toData methodreturnstrueifthePdxSerializerwasabletoserializetheuserobject,falseifnot.
IfthePdxSerializerwasabletodeserializetheobject,the fromData methodreturnsavoidpointertotheuserobjecttobewrappedina PdxWrapper .
Whenyoulaterreferencetheuserobject,usethe PdxWrapper class. PdxWrapper holdsasharedreferencetotheobjectinthelocalcacheandisusedduringserializationanddeserialization. PdxWrapper actsasacontainerfortheuserdomainobjectandneedstowrapeveryinstanceoftheobjectthatusesaregistered PdxSerializer .Theobjectinstancewillnotbemodified.Inaddition,whenusing PdxWrapper ,youwillneedtoprovideafunctionpointertoa“de-allocator”,whichwilldeletetheuserobjectwhenthereferenceisnolongerheld.
Thefollowingcodeexampledefinesauserobjectanda PdxSerializer .Itthenregistersthenew PdxSerializer andthenuses PdxWrapper toputtheobjectinaregionandretrievetheobjectfromaregion.
©CopyrightPivotalSoftwareInc,2013-2019 108 9.1
Page 109
classUserClass{public:
intm_int;stringm_string;
UserClass(intintVal,stringstringVal){m_int=intVal;m_string=stringVal;}
staticvoiddeallocate(void*object,char*className){if(strcmp(className,"com.example.UserClass")==0){UserClass*userObject=reinterpret_cast<UserClass*>(object);deleteuserObject;}}};
classUserPdxSerializer:publicPdxSerializer{public:
void*fromData(char*className,PdxReaderPtrpdxReader){if(strcmp(className,"com.example.UserClass")!=0){returnNULL;}
intintVal=pdxReader->readInt("m_int");stringstringVal=pdxReader->readString("m_string");
UserClass*userObject=newUserClass(intVal,stringVal);
return(void*)userObject;}
booltoData(void*object,char*className,PdxWriterPtrpdxWriter){if(strcmp(className,"com.example.UserClass")!=0){returnfalse;}
UserClass*userObject=reinterpret_cast<UserClass*>(object);
pdxWriter->writeInt("m_int",userObject->m_int);pdxWriter->writeString("m_string",userObject->m_string);
returntrue;}
UserDeallocatorgetDeallocator(char*className){if(strcmp(className,"com.example.UserClass")==0){returnUserClass::deallocate;}else{returnNULL;}}};
//RegisterauserPDXserializer
Serializable::registerPdxSerializer(newUserPdxSerializer);
//Putauserobjectintoaregion.
UserClass*userObject=newUserClass(123,"someValue");PdxWrapperPtrpdxWrapper=newPdxWrapper(userObject,"com.example.UserClass",UserClass::deallocate);region->put("key",pdxWrapper);
//Getauserobjectfromaregion.
pdxWrapper=dynCast<PdxWrapperPtr>(region->get("key"));UserClass*userObject=reinterpret_cast<UserClass*>(pdxWrapper->getObject());
©CopyrightPivotalSoftwareInc,2013-2019 109 9.1
Page 110
LATESTVERSION:9.1.1- RELEASENOTES
SerializeUsingthePdxSerializableClassDomainclassesneedtoinheritthe PdxSerializable abstractclasstoserializeandde-serializetheobject.WhenyouwriteobjectsusingPDXserialization,theyaredistributedtotheservertierinPDXserializedform.
Whenyourunqueriesagainsttheobjectsontheservers,onlythefieldsyouspecifyaredeserialized.Adomainclassshouldserializeandde-serializeallitsmemberfieldsinthesameorderinits toData and fromData method.
UsethisproceduretoprogramyourdomainobjectforPDXserializationusingthe PdxSerializable abstractclass.
1. Inyourdomainclass,implement PdxSerializable .Example:
classPdxObject:publicPdxSerializable
2. Programthe toData functiontoserializeyourobjectasrequiredbyyourapplication.IfyoualsousePDXserializationinJavaor.NETfortheobject,serializetheobjectinthesamewayforeachlanguage.Serializethesamefieldsinthesameorderandmarkthesameidentityfields.
3. Programthe fromData methodtoreadyourdatafieldsfromtheserializedformintotheobject’sfields.Inyour fromData implementation,usethesamenameasyoudidin toData andcallthereadoperationsinthesameorderasyoucalledthewriteoperationsinyourimplementation.
4. Optionally,programyourdomainobject’shashCodeandequalitymethods.Usethe markIdentityField methodtoindicatethatthegivenfieldnameshouldbeincludedinhashCodeandequalitychecksofthisobjectonaserver.ThefieldsthataremarkedasidentityfieldsareusedtogeneratethehashCodeandequalitymethodsofPdxInstance.Becauseofthis,theidentityfieldsshouldthemselveseitherbeprimitives,orimplementhashCodeandequals.Ifnofieldsaresetasidentityfields,thenallfieldswillbeusedinhashCodeandequalitychecks.Theidentityfieldsshouldmakemarkedaftertheyarewrittenusingamethod.
PdxSerializableExample
©CopyrightPivotalSoftwareInc,2013-2019 110 9.1
Page 111
classPdxObject:publicPdxSerializable{
private:uint32_tm_id;char*m_str;
public:PdxObject(){};PdxObject(uint32_tid,char*str);virtual~PdxObject();
uint32_tgetID(){returnm_id;}
char*getStr(){returnm_str;}
virtualvoidtoData(PdxWriterPtrpw)const;virtualvoidfromData(PdxReaderPtrpr);CacheableStringPtrtoString()const;virtualchar*getClassName()const;staticCacheable*createDeserializable(){returnnewPdxObject();}};
PdxObject::PdxObject(uint32_ti,char*str){m_id=i;m_str=str;}
PdxObject::~PdxObject(){}
voidPdxObject::toData(PdxWriterPtrpw)const{pw->writeInt("id",m_id);pw->markIdentityField("id");pw->writeString("str",m_str);}
voidPdxObject::fromData(PdxReaderPtrpr){m_id=pr->readInt("id");m_str=pr->readString("str");}
char*getClassName()const{{return"com.example.PdxType";}
CacheableStringPtrPdxObject::toString()const{charidbuf[1024];sprintf(idbuf,"PdxObject:[ID=%d]",m_id);returnCacheableString::create(idbuf);}
©CopyrightPivotalSoftwareInc,2013-2019 111 9.1
Page 112
LATESTVERSION:9.1.1- RELEASENOTES
Performingput,get,andlocalDestroyOperationswithaPDXDomainObjectThistopicdemonstrateshowyoucanperformoperationsonaPDXdomainobjectafteryouhaveimplementedPDXserializableinyourdomainclass.
Forexample,youcanperformoperationslikeput,get,andlocalDestroywiththedomainclassyoudefinedforPDXserializationinthePdxSerializableExample.
Toperformoperations,youcouldwritethefollowingapplicationcode:
1. RegisterthePDXdomainclass.
Serializable::registerPdxType(PdxObject::createDeserializable);
2. CreatethePDXdomainobject PdxObject .
CacheablePtrpdxobj(newPdxObject(100,"Value-1"));CacheableKeyPtrkeyport=CacheableKey::create("ABC");
3. Here’sanexampleofaputoperation.
rptr->put(keyport,pdxobj);
4. Here’sanexampleoflocallydestroyingtheentry.
rptr->localDestroy(keyport);
5. Here’sanexampleofagetoperation.
PdxObject*obj2=dynamic_cast<PdxObject*>((rptr->get(keyport)).ptr());LOGINFO("Debug:ReturnedID=%d",obj2->getID());
©CopyrightPivotalSoftwareInc,2013-2019 112 9.1
Page 113
LATESTVERSION:9.1.1- RELEASENOTES
UsingAutomaticPDXSerializationYoucanallowyourC++clientapplicationstoautomaticallyPDXserializeanddeserializedomainobjectswithouthavingtoaddanyextracodebyusingtheprovidedpdxautoserializercommandlinetool.
WhenusingtheC++clientAPI,youcanautomaticallyserializeanddeserializedomainobjectswithoutmakinganycodechangestothoseobjectsorhavingtoimplementaPdxSerializable interfaceandtheirrelated fromData and toData methods.The pdxautoserializer command-lineutilityallowsyoutogenerateC++codethatwillserializeyourdomainobjectsinthePDXformatforyou.
HowtoUseAutomaticPDXSerializationTheprocedurebelowusesthefollowingsampleclass:
classPortfolioPdx{private:int32_tid;char*pkid;PositionPdxPtrposition1;PositionPdxPtrposition2;CacheableHashMapPtrpositions;char**names;int8_t*newVal;CacheableDatePtrcreationDate;int8_t*arrayNull;int8_t*arrayZeroSize;public://CTOR//DTORS//OtherMethodsdeclarations
Foreachdomainclassyouprovide,allfieldsareconsideredforserializationexceptthosedefinedasstaticortransientandthoseyouexplicitlyexcludeusingmacros.
1. Inherityourclassfrom apache::geode::client::PdxSerializable .
classPortfolioPdx:publicPdxSerializable
2. Addthefollowingmethoddeclarationsinthepublicpartoftheclass.
constchar*getClassName()const;virtualvoidtoData(apache::geode::client::PdxWriterPtrpw);virtualvoidfromData(apache::geode::client::PdxReaderPtrpr);staticPdxSerializable*createDeserializable();
3. Inyourpre-buildenvironment(forexampleinyourmakefiles),call pdxautoserializer asfollows:
<GFCPP>/bin/pdxautoserializer.exe--outDir=<locationtogeneratefiles><SOURCE_DIR>/PortfolioPdx.hpp
4. Includethegeneratedfileinyourprojectandcompile.
Thefollowingisanexampleofageneratedfile:
©CopyrightPivotalSoftwareInc,2013-2019 113 9.1
Page 114
#include"PortfolioPdx.hpp"#include<geode/PdxWriter.hpp>#include<geode/PdxReader.hpp>#include<geode/PdxAutoSerializer.hpp>namespacetestobject{voidPortfolioPdx::toData(apache::geode::client::PdxWriterPtrvar){apache::geode::client::PdxAutoSerializable::writePdxObject(var,"id",id);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"pkid",pkid);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"position1",position1);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"position2",position2);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"positions",positions);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"status",status);apache::geode::client::PdxAutoSerializable::writePdxObject(var,"creationDate",creationDate);}
voidPortfolioPdx::fromData(PdxReaderPtrvar){apache::geode::client::PdxAutoSerializable::readPdxObject(var,"id",id);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"pkid",pkid);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"position1",position1);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"position2",position2);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"positions",positions);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"status",status);apache::geode::client::PdxAutoSerializable::readPdxObject(var,"creationDate",creationDate);}
constchar*PortfolioPdx::getClassName()const{return"PortfolioPdx";}}
HandlingArrays1. Definethefollowingmacroinyourheaderfile:
#defineGFARRAYSIZE(x)
2. Assumingthatthefollowingistheclassmemberoftypearray:
int8_t*newVal;
Thendefineanewvariablewhichsetsthelengthofthearray:
int32_tnewValSize;
3. Tagthenewvariablewiththe GFARRAYSIZE macroasfollows:
GFARRAYSIZE(newVal)int32_tnewValSize;
UsingaSingleVariableasLengthforMultipleArraysYoucanusetheGFARRAYSIZEStohavesinglelengthformultiplearrays.
DefinetheGFARRAYSIZESmacroasfollows:
#defineGFARRAYSIZES(x)
Thefollowingisanexampleusage:
©CopyrightPivotalSoftwareInc,2013-2019 114 9.1
Page 115
classArrayOfSizes?{public:int32_t*array1;int32_t*array2;int32_t*array3;int32_t*array4;int32_t*array5;
GFARRAYSIZE(array1)int32_tsingleSize;GFARRAYSIZES("array2,array3,array4,array5")int32_tSingleSizeToMultipleArrays?;};
ExcludingMemberVariablesfromSerialization1. Definethefollowingmacroinyourheaderfile:
#defineGFEXCLUDE
2. Tagyourmembervariablewiththismacro:
GFEXCLUDEchar*type;
MarkingIdentityFieldsIdentityfieldsareusedwhencomparingobjectsusingthe hashCode and equals methods.
1. Definethefollowingmacroinyourheaderfile.
#defineGFID(x)
2. AssumingthatthefollowingistheclassmemberyouwanttouseasIdentityField:
int8_t*newVal;
TagthememberwiththeGFIDmacroasfollows:
GFID(newVal)int8_t*newVal;
IgnoringUserDefinedKeywordsYoumighthavecertainuserdefinedkeywordsaftertheclassname.CurrentC++grammardoesnotsupportthis.IfyouhavesomekeywordsuserwillhavetoignorethembyusingtheGFIGNORE macro.
Forexample,considerthefollowingclassdefinition:
#ifdef_WIN32#ifdefBUILD_TESTOBJECT#defineTESTOBJECT_EXPORTLIBEXP#else#defineTESTOBJECT_EXPORTLIBIMP#endif#else#defineTESTOBJECT_EXPORT#endif
namespacePdxAutoTests{classTESTOBJECT_EXPORTPdxAutoMegaType:publicPdxSerializable{}
Currently,the pdxautoserializer toolwillfailtorecognize TESTOBJECT_EXPORT .Changeyourclassbyaddingthe GFIGNORE macroasfollows:
©CopyrightPivotalSoftwareInc,2013-2019 115 9.1
Page 116
#ifdef_WIN32#ifdefBUILD_TESTOBJECT#defineTESTOBJECT_EXPORTLIBEXP#else#defineTESTOBJECT_EXPORTLIBIMP#endif#else#defineTESTOBJECT_EXPORT#endif
usingnamespaceapache::geode::client;
#defineGFIGNORE(X)X#defineGFID
namespacePdxAutoTests{classGFIGNORE(TESTOBJECT_EXPORT)PdxAutoMegaType:publicPdxSerializable{
AdditionalUsageInformationforthepdxautoserializerToolThe pdxautoserializer tooltakesclassesasinputandgeneratescodethatwillserializetheclassintothePDXformatforyou.
The pdxautoserializer toolislocatedin $GEODE/bin where $GEODE correspondstotheinstallationlocationoftheclient.
Someadditionalnotesaboutusingthe pdxautoserializer tool:
Anyconsttypeintheclassmembersareignoredbythe pdxserializer tool.
Generatedfileswillhavenamespaceinthefilename.
Toviewthecommand-linehelpforthetool,type:
prompt>pdxautoserializer.exe--help
Helpreturnsthefollowingsyntaxandusageinformation:
Usage:pdxautoserializer.exe[OPTIONS]<resourcese.g.header>...
Resourcenameshouldbethepathtotheheadercontainingtheclassestobeauto-serialized.
[OPTIONS]maybeoneofthosegivenbelow.
SINGLEdenotesthattheoptionshouldbespecifiedonlyonce.MULTIPLEdenotesthattheoptioncanbespecifiedmorethanonce.OPTIONALdenotesthattheoptionmaybeskippedinwhichcasethedefaultforthatshallbechosen.
--className=VALUENameoftheclassforwhichtogenerateauto-serializationcode(MULTIPLE,OPTIONAL)--classNameStr=VALUENameoftheclassinstring(MULTIPLE,OPTIONAL)--helpThishelpmessage.--outDirTheoutputdirectoryofthegeneratedfiles(SINGLE,OPTIONAL)--suffixThesuffixofthegeneratedfilenames--defaultis'Serializable'(SINGLE,OPTIONAL)--usageThisusagemessage.
Examples:pdxautoserializer-outDir=<DIRNAME><RESOURCE>pdxautoserializer-outDir=<DIRNAME>--className=<CLASSNAME1>--className=<CLASSNAME2><RESOURCE>pdxautoserializer-outDir=<DIRNAME>--classNameStr=<CLASSNAME1:UserdefinedString>--classNameStr=<CLASSNAME:UserdefinedString><RESOURCE>
HelperMacrostobedefinedinInputHeaderFile:GFINCLUDEforincludingaspecificmemberforserializationGFEXCLUDEforexcludingaspecificmemberforserializationGFIDforconsideringamemberasIdentifyFieldGFARRAYSIZEforspecifyingaarraylengthmemberGFIGNOREforignoringcertainkeywordsFormoredetailsrefertodocumentationonthisutility.
GeneratingAutomaticCodeforaSingleClassManytimestherearemultipleclassesinasingleheaderfile.Forexample:
©CopyrightPivotalSoftwareInc,2013-2019 116 9.1
Page 117
#ifndefHEADER_HEADER#defineHEADER_HEADER
classclass1{};classclass2{};classclass3:publicPdxSerializable{};#endif
Ifyouwanttogeneratecodeforonlyoneoftheclasses,thenusethe --className option.Forexample,ifyouonlywanttogeneratecodeforclass3,thenyouwouldusethefollowingcommand:
pdxautoserializer--outDir=<outDir>--className=class3
ChoosingYourOwnSuffixtoIdentifytheGeneratedFiles.The pdxserializer toolalsoprovidestheoptiontochooseyourownsuffixforthegeneratedC++files.Thiscanhelpyouwritelesscodeinyourmakefiles.Here’sanexamplecommand:
pdxautoserializer--outDir=<outDir>--className=CharTypes--suffix="generated"
ExampleofUsingPDXSerializationinYourApplication
CacheFactoryPtrcacheFactory=CacheFactory::createCacheFactory();//Createacachewiththe"clientPdxRemoteQuery.xml"CacheXMLfile.CachePtrcachePtr=cacheFactory->set("cache-xml-file","XMLs\\clientPdxRemoteQuery.xml")->create();
LOGINFO("CreatedtheCache");
//GettheexampleRegionfromtheCachewhichisdeclaredintheCacheXMLfile.RegionPtrregionPtr=cachePtr->getRegion("Portfolios");
LOGINFO("ObtainedtheRegionfromtheCache");
//RegisterourSerializable/CacheableQueryobjects,viz.PortfolioPdxandPositionPdx.Serializable::registerPdxType(PortfolioPdx::createDeserializable);PortfolioPdxPtrport1Ptr(newPortfolioPdx(1/*ID*/,10/*size*/));PortfolioPdxPtrport2Ptr(newPortfolioPdx(2/*ID*/,20/*size*/));PortfolioPdxPtrport3Ptr(newPortfolioPdx(3/*ID*/,30/*size*/));regionPtr->put("Key1",port1Ptr);regionPtr->put("Key2",port2Ptr);regionPtr->put("Key3",port3Ptr);
//GettheQueryServicefromtheCache.QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");
LOGINFO("GottheQueryServicefromtheCache");
//ExecuteaQuerywhichreturnsaResultSet.QueryPtrqryPtr=qrySvcPtr->newQuery("SELECTDISTINCT*FROM/Portfolios");SelectResultsPtrresultsPtr=qryPtr->execute();
LOGINFO("ResultSetQueryreturned%drows",resultsPtr->size());
©CopyrightPivotalSoftwareInc,2013-2019 117 9.1
Page 118
LATESTVERSION:9.1.1- RELEASENOTES
ProgrammingYourApplicationtoUsePdxInstancesA PdxInstance isalightweightwrapperaroundtherawbytesofthePDXserializedobjectskeptinthecache.Itprovidesapplicationswithrun-timeaccesstofilesofaPDXserializedobject.GemFireprovidestheimplementationofthe PdxInstance class.
Youcanconfigureyourcachetoreturna PdxInstance whenaPDXserializedobjectisdeserializedinsteadofdeserializingtheobjecttoadomainclass.Preventingdeserializationsavesbothtimeandmemoryanddoesnotrequireyoudeserializetheobjecttothedomainclass.
Thisconfigurationcanbedoneincache.xmlbysettingtheattribute read-serialized to true onthe<pdx>element.OritcanbedoneprogrammaticallyusingtheCacheFactory::setPdxReadSerialized(bool) method.
Afterthispreferenceisconfigured,anytimeaPDXobjectisdeserialized,itisdeserializedintoa PdxInstance .
ThefollowingisacodesampleofusingthesetFieldAPIofPdxInstancetomodifyfields:
RegionPtrrptr=getHelper()->getRegion(regionNames[0]);CacheableKeyPtrkeyport=CacheableKey::create("pdxput");CacheableKeyPtrkeyport1=CacheableKey::create("pdxput2");
PdxInstancePtrpIPtr=dynCast<PdxInstancePtr>(rptr->get(keyport));LOG("modifyPdxInstancegetcomplete.");
WritablePdxInstancePtrwpiPtr(pIPtr->createWriter());
ASSERT(pIPtr!=NULLPTR,"pIPtr!=NULLPTRexpected");intval=0;intnewVal=0;ASSERT(pIPtr->hasField("m_int32")==true,"m_id1=trueexpected");pIPtr->getField("m_int32",val);wpiPtr->setField("m_int32",val+1);rptr->put(keyport,wpiPtr);PdxInstancePtrnewPiPtr=dynCast<PdxInstancePtr>(rptr->get(keyport));ASSERT(newPiPtr->hasField("m_int32")==true,"m_int32=trueexpected");newPiPtr->getField("m_int32",newVal);ASSERT(val+1==newVal,"val+1==newValexpected");ASSERT((*pIPtr.ptr()==*newPiPtr.ptr())==false,"PdxInstanceshouldnotbeequal");
Inadditiontofieldaccess, PdxInstance alsosupportsfieldmodificationusingthe setField(fieldName) method.The setField methodhascopy-on-writesemantics.Soforthemodificationstobestoredinthecache,the PdxInstance mustbeputintoaregionafter setField hasbeencalledoneormoretimes.
©CopyrightPivotalSoftwareInc,2013-2019 118 9.1
Page 119
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringPDXtoIgnoreUnreadFieldsDuringDeserializationUsethe setPdxIgnoreUnreadFields APItocontrolwhetherPDXignoresfieldsthatwereunreadduringdeserialization.
Thedefaultistopreserveunreadfieldsbyincludingtheirdataduringserialization.However,ifyouconfigurethecachetoignoreunreadfieldsthentheirdatawillbelostduringserialization.
Youshouldonlysetthisattributeto true ifyouknowthismemberwillonlybereadingcachedata.InthisusecaseyoudonotneedtopaythecostofpreservingunreadfieldssinceyouwillneverreserializethePDXdata.
Forexample:
CacheFactoryPtrcfPtr=CacheFactory::createCacheFactory(PropertiesObj);cfPtr->setPdxReadSerialized(tue);cfPtr->setPdxIgnoreUnreadFields(false);cachePtr=cfPtr->create();
©CopyrightPivotalSoftwareInc,2013-2019 119 9.1
Page 120
LATESTVERSION:9.1.1- RELEASENOTES
UsingPdxInstanceFactorytoCreatePdxInstancesYoucanusethe PdxInstanceFactory APItocreatea PdxInstance fromrawdatawhenthedomainclassisnotavailableontheserver.
Creatinga PdxInstance canbeparticularlyusefulwhenyouneedaninstanceofadomainclassforplug-incodesuchasafunctionoraloader.Ifyouhaverawdataforthedomainobject(theclassnameandeachfield’stypeanddata),thenyoucanexplicitlycreatea PdxInstance .The PdxInstanceFactory APIisverysimilartothe PdxWriter APIexceptthatafterwritingeachfield,youneedtocallthecreatemethodwhichreturnsthecreated PdxInstance .
PdxInstanceExampleThefollowingisacodeexampleofcreatinga PdxInstance .
classPerson{private:char*m_name;intm_id;intm_age;
public:Person(){}
Person(char*name,intid,intage){m_name=name;m_id=id;m_age=age;}
char*getName()const{returnm_name;}intgetID(){returnm_id;}intgetAge(){returnm_age;}};
intmain(intargc,char**argv){try{//CreateaCache.CacheFactoryPtrcacheFactory=CacheFactory::createCacheFactory();
CachePtrcachePtr=cacheFactory->set("cache-xml-file","XMLs/clientPdxInstance.xml")->create();
LOGINFO("CreatedtheGemFireCache");
//GettheexampleRegionfromtheCachewhichisdeclaredinthe//CacheXMLfile.RegionPtrregionPtr=cachePtr->getRegion("Person");
LOGINFO("ObtainedtheRegionfromtheCache.");
Person*p=newPerson("Jack",7,21);
//PdxInstanceFactoryforPersonclassPdxInstanceFactoryPtrpif=cachePtr->createPdxInstanceFactory("Person");LOGINFO("CreatedPdxInstanceFactoryforPersonclass");
pif->writeString("m_name",p->getName());pif->writeInt("m_id",p->getID());pif->markIdentityField("m_id");pif->writeInt("m_age",p->getAge());
PdxInstancePtrpdxInstance=pif->create();
LOGINFO("CreatedPdxInstanceforPersonclass");
regionPtr->put("Key1",pdxInstance);
©CopyrightPivotalSoftwareInc,2013-2019 120 9.1
Page 121
regionPtr->put("Key1",pdxInstance);
LOGINFO("PopulatedPdxInstanceObject");
PdxInstancePtrretPdxInstance=regionPtr->get("Key1");
LOGINFO("GotPdxInstanceObject");
intid=0;retPdxInstance->getField("m_id",id);
intage=0;retPdxInstance->getField("m_age",age);
char*name=NULL;retPdxInstance->getField("m_name",&name);
if(id==p->getID()&&age==p->getAge()&&strcmp(name,p->getName())==0&&retPdxInstance->isIdentityField("m_id")==true)LOGINFO("PdxInstancereturnsallfieldsvalueexpected");elseLOGINFO("PdxInstancedoesn'treturnsallfieldsvalueexpected");
deletep;
//ClosetheCache.cachePtr->close();
LOGINFO("ClosedtheCache");
}//Anexceptionshouldnotoccurcatch(constException&geodeExcp){LOGERROR("PdxInstanceException:%s",geodeExcp.getMessage());}}
©CopyrightPivotalSoftwareInc,2013-2019 121 9.1
Page 122
LATESTVERSION:9.1.1- RELEASENOTES
UsingC++EnumTypewithPDXSerializationBecausethereisno“object”basetypeinC++,enumscannotbedirectlypassedasparameterstothe writeObject and readObject API.
TousetheC++enumtypewithPDXserialization,youhavetowrapthe enum inthe CacheableEnum classtypebyspecifyingclassname,enumnameandordinal.
enumenumQuerytest{id1,id2,id3};classTESTOBJECT_EXPORTPdxEnumTestClass:publicPdxSerializable{private:intm_id;CacheableEnumPtrm_enumid;
public:intgetID(){returnm_id;}
CacheableEnumPtrgetEnumID(){returnm_enumid;}
PdxEnumTestClass(intid){m_id=id;switch(m_id){case0:m_enumid=CacheableEnum::create("enumQuerytest","id1",id1);break;case1:m_enumid=CacheableEnum::create("enumQuerytest","id2",id2);break;case2:m_enumid=CacheableEnum::create("enumQuerytest","id3",id3);break;default:m_enumid=CacheableEnum::create("enumQuerytest","id1",id1);break;}}
PdxEnumTestClass(){}
voidtoData(PdxWriterPtrpw){pw->writeInt("m_id",m_id);pw->writeObject("m_enumid",m_enumid);}
voidfromData(PdxReaderPtrpr){m_id=pr->readInt("m_id");m_enumid=pr->readObject("m_enumid");}
CacheableStringPtrtoString()const{returnCacheableString::create("PdxEnumTestClass");}
char*GetClassName()const{return"com.example.PdxEnumTestClass";}
staticPdxSerializable*createDeserializable(){returnnewPdxEnumTestClass();}};
HowPutsandQueriesWorkonEnumsThefollowingcodesampledemonstrateshowputandqueryoperationsworkwhenusingtheC++enumTypewithPDXserialization:
©CopyrightPivotalSoftwareInc,2013-2019 122 9.1
Page 123
//CreatingobjectsoftypePdxEnumTestClassPdxEnumTestClassPtrpdxobj1(newPdxEnumTestClass(0));PdxEnumTestClassPtrpdxobj2(newPdxEnumTestClass(1));PdxEnumTestClassPtrpdxobj3(newPdxEnumTestClass(2));
RegionPtrrptr=getHelper()->getRegion("DistRegionAck");
//PUTOperationsrptr->put(CacheableInt32::create(0),pdxobj1);LOG("pdxPut1completed");
rptr->put(CacheableInt32::create(1),pdxobj2);LOG("pdxPut2completed");
rptr->put(CacheableInt32::create(2),pdxobj3);LOG("pdxPut3completed");
//Querytry{Serializable::registerPdxType(PdxEnumTestClass::createDeserializable);LOG("PdxEnumTestClassRegisteredSuccessfully....");}catch(geode::IllegalStateException&/*ex*/){LOG("PdxEnumTestClassIllegalStateException");}
RegionPtrrptr=getHelper()->getRegion("DistRegionAck");SelectResultsPtrresults=rptr->query("m_enumid.name='id2'");ASSERT(results->size()==1,"queryresultshouldhaveoneitem");ResultSetPtrrsptr=dynCast<ResultSetPtr>(results);SelectResultsIteratoriter=rsptr->getIterator();while(iter.moveNext()){PdxEnumTestClassPtrre=dynCast<PdxEnumTestClassPtr>(iter.current());ASSERT(re->getID()==1,"queryshouldhavereturnedid1");}
©CopyrightPivotalSoftwareInc,2013-2019 123 9.1
Page 124
LATESTVERSION:9.1.1- RELEASENOTES
UsingPDXSerializationwithDeltaPropagationYoucanincludedeltapropagationsupportwithPDXserializationbyimplementingthe Delta interfacemethods.However,usingdeltapropagationwithPDXwillrequirethatyouimplementJavasideclasses.TheobjectswillremainindeserializedformatalltimesontheserverandyouwillloseoneofthemainbenefitsofPDX.
Inaddition,youmustset read-serialized to false .Otherwise,Javaobjectswillbedeserializedtoinstancesof PdxInstance ,whichneverimplementsdeltas.
ThefollowingcodesnippetisasampleimplementationoftheDeltainterfacemethodsforusingwithPDXserialization.
classPdxWithDelta:publicPdxSerializable,publicDelta{public:
boolhasDelta();voidtoDelta(DataOutput&output);voidfromDelta(DataInput&input);DeltaPtrclone();
//otherPdxSerializablemethodshere...
};
©CopyrightPivotalSoftwareInc,2013-2019 124 9.1
Page 125
LATESTVERSION:9.1.1- RELEASENOTES
SerializingDatawiththeSerializableInterfaceTheC++clientAPIprovidesa Serializable interfacethatyoucanuseforfastandcompactdataserialization.ThissectiondiscussestheGemFireserializableinterface,andpresentsimplementationexamples.
HowSerializationWorksWhenyourapplicationputsanobjectintothecacheforsubsequentdistribution,GemFireserializesthedatabytakingthesesteps:
1. Callstheappropriate classId function.
2. Writesthefull typeId usingthe classId fortheinstance.
3. Invokestheinstance’s toData function.
Whenyourapplicationsubsequentlyreceivesabytearray,GemFiretakesthefollowingsteps:
1. Decodesthe typeId ,extractsthe classId fromthe typeId ,thencreatesanobjectofthedesignatedtypeusingtheregisteredfactoryfunctions.
2. Invokesthe fromData functionwithinputfromthedatastream.
3. Decodesthedata,thenpopulatesthedatafields.
ImplementingtheSerializableInterfaceTostoreyourowndatatypesinthecache,youneedtoderiveanewsubclassfromtheSerializable interface.Inpracticalterms,thismeansthatyouneedtoimplementasmallsetofhelperfunctions:
1. Writea toData functionthatserializesyourdata.
voidtoData(DataOutput&output)
The toData functionisresponsibleforcopyingalloftheobject’sdatafieldstotheobjectstream.The DataOutput classrepresentstheoutputstreamandprovidesmethodsforwritingtheprimitivesinanetworkbyteorder.
2. Writea fromData functionthatconsumesadatainputstreamandrepopulatestheobject’sdatafields.
voidfromData(DataInput&input)
The DataInput classrepresentstheinputstreamandprovidesmethodsforreadinginputelements.The fromData functionmustreadtheelementsoftheinputstreaminthesameorderthattheywerewrittenby toData .
Example1.TheSimpleClassBankAccountThisexampledemonstratesasimple BankAccount classthatencapsulatestwo ints , ownerId and accountId :
©CopyrightPivotalSoftwareInc,2013-2019 125 9.1
Page 126
classBankAccount{private:intm_ownerId;intm_accountId;public:BankAccount(intowner,intaccount):m_ownerId(owner),m_accountId(account){}intgetOwner(){returnm_ownerId;}intgetAccount(){returnm_accountId;}};
Tomake BankAccount serializable,youwouldneedtoderivetheclassfrom Serializable andimplementthefollowing:
toData —afunctiontoserializethedata.
fromData —afunctiontodeserializethedata.
classId —afunctiontoprovideauniqueintegerfortheclass.
TypeFactoryMethod —apointertoafunctionthatreturnsa Serializable* toanuninitializedinstanceofthetype.
Example2.ImplementingaSerializableClassThisexampleshowsacodesamplethatdemonstrateshowtoimplementaserializableclass.
©CopyrightPivotalSoftwareInc,2013-2019 126 9.1
Page 127
classBankAccount:publicSerializable{private:intm_ownerId;intm_accountId;public:BankAccount(intowner,intaccount):m_ownerId(owner),m_accountId(account){}
intgetOwner(){returnm_ownerId;}
intgetAccount(){returnm_accountId;}
//AddthefollowingfortheSerializableinterface//OurTypeFactoryMethodstaticSerializable*createInstance(){returnnewBankAccount(0,0);}
int32_tclassId(){return10;//mustbeuniqueperclass.}
virtualuint32_tobjectSize()const{return10;}
voidtoData(DataOutput&output){output.writeInt(m_ownerId);output.writeInt(m_accountId);}
Serializable*fromData(DataInput&input){input.readInt(&m_ownerId);input.readInt(&m_accountId);returnthis;}};
RegisteringtheTypeTobeabletousethe BankAccount type,youmustregisteritwiththetypesystemsothatwhenanincomingstreamcontainsa BankAccount ,itcanbemanufacturedfromtheassociatedTypeFactoryMethod .
Serializable::registerType(BankAccount::createInstance);
Typically,youwouldregisterthetypebeforecallingthefunction DistributedSystem::connect .
Note:TypeIDsmustbeuniquetoonlyoneclass.
CustomKeyTypesIfyourapplicationuseskeytypesthataretoocomplextoeasilyforceinto CacheableString ,youcanlikelyimproveperformancebyderivinganewclassfrom CacheableKey .Ifyouhavehybriddatatypesyoucanimplementyourownderivationof CacheableKey thatencapsulatesthedatatype.
SeebelowforinformationaboutimplementingkeytypesforaclientthatisusedwithaJavacacheserver.
Toextenda Serializable classtobea CacheableKey ,youneedtomodifytheclassdefinitionasfollows:
Changetheclasssothatitderivesfrom CacheableKey ratherthan Serializable .
©CopyrightPivotalSoftwareInc,2013-2019 127 9.1
Page 128
Implement operator== and hashcode functions.
Example3.ExtendingaSerializableClassToBeaCacheableKeyThisexampleshowshowtoextendaserializableclasstobeacacheablekey.
classBankAccount:publicCacheableKey{private:intm_ownerId;intm_accountId;public:BankAccount(intowner,intaccount):m_ownerId(owner),m_accountId(account){}
intgetOwner(){returnm_ownerId;}
intgetAccount(){returnm_accountId;}
//OurTypeFactoryMethodstaticSerializable*createInstance(){returnnewBankAccount(0,0);}
int32_ttypeId(){return1000;//mustbeuniqueperclass.}
voidtoData(DataOutput&output){output.writeInt(m_ownerId);output.writeInt(m_accountId);}
Serializable*fromData(DataInput&input){input.readInt(&m_ownerId);input.readInt(&m_accountId);returnthis;}
//AddthefollowingfortheCacheableKeyinterfacebooloperator==(constCacheableKey&other)const{constBankAccount&otherBA=static_cast<constBankAccount&>(other);return(m_ownerId==otherBA.m_ownerId)&&(m_accountId==otherBA.m_accountId);}
uint32_thashcode()const{returnm_ownerId;}
virtualint32_tclassId()const{return10;//mustbeuniqueperclass.}virtualuint32_tobjectSize()const{return10;}};
SerializationinNativeClientModewithaJavaServer
©CopyrightPivotalSoftwareInc,2013-2019 128 9.1
Page 129
Primitiveobjecttypessupportedinalllanguages( CacheableInt32 , CacheableString , CacheableBytes )functionwithoutrequiringcustomdefinitionswiththeJavacacheserver.Forthekeys,theJavacacheserverhastodeserializethemandlocatethehashcodetobeabletoinserttheinternalmaps.Becauseofthis,keytypesforC++clientsusedwithaJavaserverarerequiredtoberegisteredontheJavaserver,butthevaluetypesdonotneedtoberegistered.ThisneedstobedoneeveniftherearenoJavaclients.
©CopyrightPivotalSoftwareInc,2013-2019 129 9.1
Page 130
LATESTVERSION:9.1.1- RELEASENOTES
SerializingObjectGraphsIfyouhaveagraphofobjectswhereeachnodecanbeserializable,theparentnodecancall DataOutput::writeObject todelegatetheserializationresponsibilitytoitschildnodes.Similarly,yourapplicationcancall DataInput::readObject todeserializetheobjectgraph.
©CopyrightPivotalSoftwareInc,2013-2019 130 9.1
Page 131
LATESTVERSION:9.1.1- RELEASENOTES
SerializingandAccessingDataasaBlobIfyouhavedatathatisbesthandledasablob,suchasstructsthatdonotcontainpointers,usetheserializabletype CacheableBytes . CacheableBytes isablobclassthatimplementstheserializationforyou.
CacheableBytes alsoprovidesdirectaccesstotheblobdata.Becauseitisnotderivedfromthe CacheableKey interface, CacheableBytes enablesyoutomodifydatainplaceandthenputitintotheregionagaintodistributethechange.
©CopyrightPivotalSoftwareInc,2013-2019 131 9.1
Page 132
LATESTVERSION:9.1.1- RELEASENOTES
ImplementingUser-DefinedObjectsinJavaClientsYoucanuseoneoftwomethodstoimplementauser-definedobjectinaJavaclientthatworkswithC++clients: Instantiator.register and DataSerializable .
Instantiator.registerWiththe Instantiator.register method,aclientsendsa RegistrationMessage toeveryJavaVMinitsdistributedsystem.Themessageannouncesthemappingbetweenauser-definedclassIdandclassname.TheotherJVMscandeserializethebytearraywiththecorrectclass.
DataSerializableUsingthe DataSerializable method,theuser-definedobjectisserializedintothefollowingbytearray:
45<2-byte-length><class-name>
AJavaclientcandeserializethebytearray,butaC++clientcannotconverttheJavaclassnametoaC++classname.
ImplementationThe DataSerializable methoddoesnotsupportusinganestedobject,while Instantiator.register doessupporttheuseofnestedobjects.AworkaroundistoleteachJavaclientmanuallyinitiateanobjectforeachpossibleuserobjectclassaC++clientprovides,usingthefollowingcode:
Useru=newUser("",0);
SeeJavaSerializationExampleforacodesamplethatshowshowtosetupuserobjectclassesinaJavaclient.
©CopyrightPivotalSoftwareInc,2013-2019 132 9.1
Page 133
LATESTVERSION:9.1.1- RELEASENOTES
UsingaCustomClassThisexampleshowshowtousethedefined BankAccount customkeytypeandthe AccountHistory valuetype.
Theexampletakesyouthroughthesebasicoperations:registering,creatingacache,connectingtothedistributedsystem,puttingdata,gettingdata,andclosingthecache.
UsingaBankAccountObject
#include<geode/GeodeCppCache.hpp>#include"BankAccount.hpp"#include"AccountHistory.hpp"usingnamespaceapache::geode::client;/*Thisexampleconnects,registerstypes,createsthecache,createsaregion,andthenputsandgetsuserdefinedtypeBankAccount.*/intmain(intargc,char**argv){//Registertheuser-definedserializabletype.Serializable::registerType(AccountHistory::createDeserializable);Serializable::registerType(BankAccount::createDeserializable);CacheFactoryPtrcacheFactory=CacheFactory::createCacheFactory();//Createacache.CachePtrcachePtr=cacheFactory->setSubscriptionEnabled(true)->addServer("localhost",24680)->create();//Createaregion.RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);RegionPtrregionPtr=regionFactory->create("BankAccounts");//PlacesomeinstancesofBankAccountcacheregion.BankAccountPtrKeyPtr(newBankAccount(2309,123091));AccountHistoryPtrValPtr(newAccountHistory());ValPtr->addLog("Createdaccount");regionPtr->put(KeyPtr,ValPtr);printf("PutanAccountHistoryincachekeyedwithBankAccount.\n");//CallcustombehavioroninstanceofBankAccount.KeyPtr->showAccountIdentifier();//CallcustombehavioroninstanceofAccountHistory.ValPtr->showAccountHistory();//Getavalueoutoftheregion.AccountHistoryPtrhistoryPtr=dynCast<AccountHistoryPtr>(regionPtr->get(KeyPtr));if(historyPtr!=NULLPTR){printf("FoundAccountHistoryinthecache.\n");historyPtr->showAccountHistory();historyPtr->addLog("debit$1,000,000.");regionPtr->put(KeyPtr,historyPtr);printf("UpdatedAccountHistoryinthecache.\n");}//Lookupthehistoryagain.historyPtr=dynCast<AccountHistoryPtr>(regionPtr->get(KeyPtr));if(historyPtr!=NULLPTR){printf("FoundAccountHistoryinthecache.\n");historyPtr->showAccountHistory();}//ClosethecacheanddisconnectfromtheserverscachePtr->close();return0;}
©CopyrightPivotalSoftwareInc,2013-2019 133 9.1
Page 134
LATESTVERSION:9.1.1- RELEASENOTES
CreatingNewStatisticsThisexampleprovidesaprogrammaticcodesampleforcreatingandregisteringnewstatistics.
Forinformationaboutthe geode_statistics API,seeStatisticsAPI.
CreatingNewStatisticsProgrammatically
//GetStatisticsFactoryStatisticsFactory*factory=StatisticsFactory::getExistingInstance();//DefineeachStatisticDescriptorandputeachinanarrayStatisticDescriptor**statDescriptorArr=newStatisticDescriptor*[6];statDescriptorArr[0]=statFactory->createIntCounter("IntCounter","TestStatisticDescriptorIntCounter.","TestUnit");statDescriptorArr[1]=statFactory->createIntGauge("IntGauge","TestStatisticDescriptorIntGauge.","TestUnit");statDescriptorArr[2]=statFactory->createLongCounter("LongCounter","TestStatisticDescriptorLongCounter.","TestUnit");statDescriptorArr[3]=statFactory->createLongGauge("LongGauge","TestStatisticDescriptorLongGauge.","TestUnit");statDescriptorArr[4]=statFactory->createDoubleCounter("DoubleCounter","TestStatisticDescriptorDoubleCounter.","TestUnit");statDescriptorArr[5]=statFactory->createDoubleGauge("DoubleGauge","TestStatisticDescriptorDoubleGauge.","TestUnit");//CreateaStatisticsTypeStatisticsType*statsType=statFactory->createType("TestStatsType","StatisticsforUnitTest.",statDescriptorArr,6);//CreateStatisticsofagiventypeStatistics*testStat=factory->createStatistics(statsType,"TestStatistics");//Statisticsarecreatedandregistered.SetandincrementindividualvaluesIntstatIdIntCounter=statsType->nameToId("IntCounter");testStat->setInt(statIdIntCounter,10);testStat->incInt(statIdIntCounter,1);intcurrentValue=testStat->getInt(statIdIntCounter);
©CopyrightPivotalSoftwareInc,2013-2019 134 9.1
Page 135
LATESTVERSION:9.1.1- RELEASENOTES
.NETClientAPIThissectiondescribestheprimaryclasses,usageconventions,andC++to.NETclassmappingsofthe.NETclientAPI.ItdemonstrateshowtousetheAPItocreatecachesandperformdataserialization.
Seethe.NETAPI documentationforAPIdetails.
Aboutthe.NETClientAPITheMicrosoft.NETFrameworkinterfacefortheclientprovidescompleteaccesstotheC++clientfunctionalityfromany.NETFrameworklanguage(C#,C++/CLI,VB.NET,andJ#).ThisenablesclientsusingC#andother.NETlanguagestousethecapabilitiesprovidedbytheC++API.
C++Classto.NETClassMappings
WhereverthenativeC++classmethodsusepass-by-referencesemanticstoreturndata,thecorresponding.NETmethodsreturntheobjectinsteadofusingpass-by-referencesemantics.
Javato.NETTypeMappingTable
ThefollowingtableprovidesamappingbetweenJavaand.NETtypes.
ObjectLifetimesThe.NETAPIprovidesamanagedsetofassembliesfortheC++API.TheunderlyingC++objectwillstayinmemoryuntilthe.NETobjectisgarbage-collected.
.NETApplicationDomainsApplicationdomains,or AppDomain s,areunitsofisolation,securityboundaries,andloadingandunloadingforapplicationsinthe.NETruntime.Multipleapplicationdomainscanruninasingleprocess.Eachcanhaveoneormanythreads,andathreadcanswitchapplicationdomainsatruntime.
CreatingaCacheYoucreateacacheusingtheGemFire CacheFactory.Create call.Cachecreationinitializesthedistributedsystemandcreatesthecacheusingyour geode.properties and cache.xml
settingsandanyadditionalpropertiesyouprovidetothecall.
CreatingaRegionTocreatearegion,youcreatea RegionFactory usingthe RegionShortcut thatmostcloselyfitsyourregionconfiguration.
AddinganEntrytotheCacheYoupopulateanativeclientregionwithcacheentriesbyusingthegeneric IDictionary APIorbyusingthe.NET Region.Put orthe Region.Create APIfunctions.
AccessinganEntryTheregionentryretrievalmethodsreturnthevalueassociatedwiththespecifiedkey,andpassthecallbackargumenttoanycacheloadersorcachewritersthatareinvokedduringtheoperation.
RemovinganEntryThestandard Region::Remove APIremovestheentrywithspecifiedkeyandprovidesauser-definedparameterobjecttoany CacheWriter or CacheListener invokedintheprocess.
DataSerializationAlldatathatGemFiremovesoutofthelocalcachemustbeserializable.
ApplicationCallbacksForregion-levelevents,anapplicationcanuse AttributesFactory.SetCache* methodstoimplementandregisterthe ICacheLoader , ICacheWriter ,and ICacheListener interfacestoperformcustomactions.
ASimpleC#ExampleAnexampleshowshowtoconnecttoGemFire,createacacheandregion,putandgetkeysandvalues,anddisconnect.
Troubleshooting.NETApplicationsThe.NETFrameworkdoesnotfindmanagedDLLsusingtheconventional PATH environmentvariable.InorderforyourassemblytofindandloadamanagedDLL,itmusteitherbeloadedasaprivateassemblyusing assemblyBinding ,oritmustbeinstalledintotheGlobalAssemblyCache(GAC).
©CopyrightPivotalSoftwareInc,2013-2019 135 9.1
Page 136
LATESTVERSION:9.1.1- RELEASENOTES
Aboutthe.NETClientAPITheMicrosoft.NETFrameworkinterfacefortheclientprovidescompleteaccesstotheC++clientfunctionalityfromany.NETFrameworklanguage(C#,C++/CLI,VB.NET,andJ#).ThisenablesclientsusingC#andother.NETlanguagestousethecapabilitiesprovidedbytheC++API.
The.NETclientusesasetofassembliesmanagedbytheC++CommonLanguageInfrastructure(C++CLI).C++CLIincludesthelibrariesandobjectsnecessaryforcommonlanguagetypes,anditistheframeworkfor.NETapplications.
The.NETAPIadds.NETFrameworkCLIlanguagebindingforthenativeclientproduct.
UsingC#,youcanwritecallbacksanddefineuserobjectsinthecache.ThefollowingfigureshowsanoverviewofhowaC#applicationaccessestheC++clientAPIfunctionalitythroughC++/CLI.
Figure:C#.NETApplicationAccessingtheC++API
Note:ThischapterusesC#asthereferencelanguage,butother.NETlanguagesworkthesameway.
The.NETAPIisprovidedinthe Apache.Geode.Client namespace.Thisnamespaceallowsyoutomanageyourcache,regions,anddata.UsetheGemFire.NETAPItoprogrammaticallycreate,populate,andmanageadistributedsystem.
Note:The.NETlibraryisthread-safeexceptwhereotherwiseindicatedintheAPIdocumentation.
©CopyrightPivotalSoftwareInc,2013-2019 136 9.1
Page 137
LATESTVERSION:9.1.1- RELEASENOTES
.NETNamingandUsageConventionsUnlessnoted,the.NETAPIclassesandfunctionshavethesamenamesastheirC++counterpartsinthenamespace Apache.Geode.Client .In.NET,allmethodnamesstartwithacapitalletter.
The.NETinterfacenamesmatchthoseofcomparableC++interfaces,butwithan’I’prependedtosatisfy.NETnamingconventions.Forexample,the.NETequivalentoftheC++CacheLoader interfaceis ICacheLoader .
ThenameoftheGemFire Serializable interfaceis IGeodeSerializable because ISerializable isa.NETbuilt-intype.
Wherepossible,get*andset*functionsarereplacedby.NETproperties.
Youcanimplementthe.NETinterfaces.Youcannotextendanyoftheclassesbecausetheyaremarkedassealed.
©CopyrightPivotalSoftwareInc,2013-2019 137 9.1
Page 138
LATESTVERSION:9.1.1- RELEASENOTES
PrimaryAPIsThesearethemainAPIswithin Apache.Geode.Client usedforcache,region,anddataentrymanagement.
Note:DeclarativeconfigurationviaXMLofapplicationplug-inssuchascachelistener,cachewriter,cacheloaderandpartitionresolverisnotsupportedwhenclientsareoperatedinthenew.NETGenericAPI.
CacheAPIsThissectiondescribesthe CacheFactory and Cache classes.
RegionandEntryAPIsThissectiondescribesclassesforworkingwithregionsandregionentries.
DataSerializationAPIsUseeither IPdxSerializable or IGeodeSerializable foreachregion.Donotmixthetwo.
EventHandlingAPIsCodeyoureventhandlerstodominimalworkbeforereturningcontroltoGemFire.
PropertyCollectionsandLoggingAPIsThissectiondescribesclassesforpropertycollectionsandlogging.
©CopyrightPivotalSoftwareInc,2013-2019 138 9.1
Page 139
LATESTVERSION:9.1.1- RELEASENOTES
CacheAPIsThissectiondescribesthe CacheFactory and Cache classes.
CacheFactoryclass.Createsa Cache instancebasedontheprovideddistributedsystemandcacheconfiguration.Any geode.properties and cache.xml filesprovidedtotheapplicationareusedtoinitializethesystemandcache.SeeSettingSystemandCacheProperties.Ifa cache.xml fileisusedtocreateacacheandsomeoftheregionsalreadyexist,awarningstatesthattheregionsexistandthecacheiscreated.
Cacheclass.ThisclassistheentrypointtotheGemFirecachingAPI.Thisclassallowsyoutocreateregions.Thecacheiscreatedbycallingthe create functionoftheCacheFactory class.Whencreatingacache,youspecifya DistributedSystem thattellsthenewcachewheretofindothercachesonthenetworkandhowtocommunicatewiththem.
©CopyrightPivotalSoftwareInc,2013-2019 139 9.1
Page 140
LATESTVERSION:9.1.1- RELEASENOTES
RegionandEntryAPIsThissectiondescribesclassesforworkingwithregionsandregionentries.
RegionFactoryclass.Createsa Region instancebasedontheprovidedconfiguration.
IRegionclass.Providesfunctionsformanagingregionsandcacheddata.The Region interfaceimplementsthegeneric.NET IDictionary interface. IRegion implementsIDictionary and Region inherits IRegion ,givingyouaccesstothefullrangeof.NET Generic collectionfunctions.Usethefunctionsinthisclasstoperformthefollowingactions:
Retrieveinformationabouttheregion,suchasitsparentregionandregionattributeobjects.Invalidateordestroytheregion.Add,update,invalidate,andremoveregionentries.Determine,individuallyorasentiresets,theregion’sentrykeys,entryvalues,and RegionEntry objects.
RegionEntryclass.Containsthekeyandvaluefortheentry,andprovidesallnon-distributedentryoperations.Theoperationsofthisobjectarenotdistributedanddonotaffectstatistics.
RegionShortcutclass.Holds enum definitionsforthemostcommonregionconfigurations.Startyourregionconfigurationwithashortcutsettingintheregionattribute,Thencustomizefurtherusingthe RegionAttributes .
RegionAttributesclass.Holdsallattributevaluesforaregionandprovidesfunctionsforretrievingallattributesettings.Thisclasscanonlybemodifiedbythe AttributesFactoryclassbeforeregioncreation,andthe AttributesMutator classafterregioncreation.
AttributesMutatorclass.Allowsmodificationofanexistingregion’sattributesforapplicationplug-insandexpirationactions.Eachregionhasan AttributesMutator
©CopyrightPivotalSoftwareInc,2013-2019 140 9.1
Page 141
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationAPIsUseeither IPdxSerializable or IGeodeSerializable foreachregion.Donotmixthetwo.
Formoreinformationontheseoptions,seeDataSerialization.
IPdxSerializableinterface.Providesaflexiblewaytoserializeyourdomainobjectsforcachestorageandtransfertotheservers.ThisisaGemFirebuilt-inserializationframework.
IPdxReader.SuppliesoperationsforreadingdatafromGemFireIPDXSerializabletypes.
IPdxWriter.ProvidesoperationsforwritingdataintoGemFireIPDXSerializabletypes.
IPdxInstance.InstanceofaPDXserializedobjectthatyoucanusetoaccesstheobject’sdatawithouthavingtodeserializetheobjectfirst.
IPdxInstanceFactory.AllowsyoutobuildanIPdxInstanceusingrawdata.
IPdxTypeMapperinterface.Allowsyoutomap.NETtypenamestoJavatypenameswhenusingPDXserialization.
IGeodeSerializableinterface.Superclassofonesetofuserobjectsthatcanbeserializedandstoredinthecache.TheseareGemFirebuilt-inserializabletypes.
Serializableclass.WrapstheC++ apache::geode::client::Serializable objectsasmanaged IGeodeSerializable objects.WheneverC++clientsand.NETclientsinteroperateandarepartofthesamedistributedsystem,theuser-definedtypesthatareputbytheC++clientsthathavenotbeendefinedin.NETarereturnedasobjectsofthisclass.TheAPIcontainsoverloadsformostRegionmethodsandothermethodsthattake Serializable asavalueandthataremoreoptimizedthanthemoregeneric IGeodeSerializable
overloads.Theapplicationprefersusingtheseoverloadswheneverthebaseclassofanobjectis Serializable .
DataInput.Suppliesoperationsforreadingprimitivedatavaluesanduser-definedobjectsfromabytestream.
DataOutput.Providesoperationsforwritingprimitivedatavaluesanduser-definedobjectsimplementing IGeodeSerializable toaninteger.
©CopyrightPivotalSoftwareInc,2013-2019 141 9.1
Page 142
LATESTVERSION:9.1.1- RELEASENOTES
EventHandlingAPIsCodeyoureventhandlerstodominimalworkbeforereturningcontroltoGemFire.
Forexample,alistenerimplementationmayhandofftheeventtoathreadpoolthatprocessestheeventonitsthreadratherthanthelistenerthread.ExceptionsthrownbythelistenersarecaughtbyGemFireandlogged.
RegionEventclass.Providesinformationabouttheevent,suchaswhatregiontheeventoriginatedin,whethertheeventoriginatedinacacheremotetotheeventhandler,andwhethertheeventresultedfromadistributedoperation.
EntryEventclass.Providesallavailableinformationforthe RegionEvent .Italsoprovidesentry-specificinformation,suchastheoldandnewentryvaluesandwhethertheeventresultedfromaloadoperation.
ICacheLoaderapplicationcallbackinterface.Loadsdataintoaregion.
ICacheWriterapplicationcallbackinterface.Synchronouslyhandlesregionandentryeventsbeforetheeventsoccur.Entryeventsare create , update , invalidatedestroy .Regioneventsareinvalidateanddestroy.Thisclasshastheabilitytoabortevents.
ICacheListenerapplicationcallbackinterface.Asynchronouslyhandlesregionandentryevents.Listenersreceivenotificationswhenentriesinaregionchange,orwhenchangesoccurtotheregionattributesthemselves.Entryeventsare create , update , invalidate ,and destroy .Regioneventsare invalidate and destroy .Multipleeventscancauseconcurrentinvocationof ICacheListener methods.IfeventAoccursbeforeeventB,thereisnoguaranteethattheircorrespondingICacheListenermethodinvocationswilloccurinthesameorder.
©CopyrightPivotalSoftwareInc,2013-2019 142 9.1
Page 143
LATESTVERSION:9.1.1- RELEASENOTES
PropertyCollectionsandLoggingAPIsThissectiondescribesclassesforpropertycollectionsandlogging.
Propertiesclass.Providesacollectionofproperties,eachofwhichisakey/valuepair.Eachkeyisastring,andthevaluecanbeastringoraninteger.
Logclass.DefinesmethodsavailabletoclientsthatneedtowritealogmessagetotheirGemFiresystemsharedlogfile.AnyattempttouseaninstanceafteritsconnectionisdisconnectedthrowsaNotConnectedException.Foranyloggedmessagethelogfilecontains:
Theloglevelofthemessage.Thetimethemessagewaslogged.TheIDoftheconnectionandthreadthatloggedthemessage.Themessageitself,possiblywithanexceptionincludingitsstacktrace.
©CopyrightPivotalSoftwareInc,2013-2019 143 9.1
Page 144
LATESTVERSION:9.1.1- RELEASENOTES
C++Classto.NETClassMappingsWhereverthenativeC++classmethodsusepass-by-referencesemanticstoreturndata,thecorresponding.NETmethodsshowninthefollowingtablereturntheobjectinsteadofusingpass-by-referencesemantics.
class apache::geode::client::AttributesFactory Sealedclass AttributesFactory
class apache::geode::client::AttributesMutator Sealedclass AttributesMutator
class apache::geode::client::Cache Sealedclass Cache
abstractclass apache::geode::client::Cacheable Interface IPdxSerializable orinterface IGeodeSerializable
class apache::geode::client::CacheableBytes Byte[] or ArrayList<Byte>
class apache::geode::client::Cacheableint32 Int32
class apache::geode::client::CacheableString String
abstractclass apache::geode::client::CacheableKeyYoucanuseanytypethatimplements hashcode and equals .Thegeneric.NETbuilt-intypesareallsuitable.
abstractclass apache::geode::client::CacheListener Interface ICacheListener
class apache::geode::client::CacheLoader Interface ICacheLoader plusstaticclass CacheLoader
class apache::geode::client::CacheWriter Interfaceclass ICacheWriter
class apache::geode::client::CacheFactory Sealedclass CacheFactory
class apache::geode::client::DataInputWith IPdxSerializable , IPdxReader.
With IGeodeSerializable ,sealedclass DataInput .
class apache::geode::client::DataOutputWith IPdxSerializable , IPdxWriter.
With IGeodeSerializable ,sealedclass DataOutput .
class apache::geode::client::DiskPolicyTypeenum DiskPolicyType plusstaticclass DiskPolicy containingconveniencemethodsforDiskPolicyType enumeration
class apache::geode::client::DistributedSystem Sealedclass DistributedSystem
class apache::geode::client::EntryEvent Sealedclass EntryEvent
class apache::geode::client::Exception Class GeodeException
©CopyrightPivotalSoftwareInc,2013-2019 144 9.1
Page 145
allotherexceptionsderivingfrom apache::geode::client::Exception Correspondingexceptionsderivingfrom GeodeException
class apache::geode::client::ExpirationActionenum ExpirationAction plusstaticclass Expiration containingconveniencemethodsforExpirationAction enumeration
class apache::geode::client::Log
Staticclass Log .Thenative Log::log methodismappedto Log.Write toavoidtheconflictwiththeclassnamewhichisreservedfortheconstructorsofLogclass.Thevariousloglevel Throw or Catch methodsarenotimplemented,sincetheyareredundantto Log::Log , Log::LogThrow ,and Log::LogCatch methodsthattakeasaparameter.
enum apache::geode::client::MemberType enum MemberType
abstractclass apache::geode::client::PersistanceManagerNotprovided.YoucanregisteraC++implementationusingAttributesFactory.SetPersistenceManager butyoucannotimplementanewonein.NET
class apache::geode::client::Properties Sealedclass Properties
class apache::geode::client::Properties::Visitor Delegate PropertiesVisitor
abstractclass apache::geode::client::Region Class IRegion
class apache::geode::client::RegionAttributes Sealedclass RegionAttributes
class apache::geode::client::ScopeTypeenum ScopeType plusstaticclass Scope containingconveniencemethodsforenumeration+
abstractclass apache::geode::client::Serializable
Twooptions:
Interface IPdxSerializable
Interface IGeodeSerializable pluswrapper Serializable classfornative SerializableUserData objects.Thenative toString methodisnotprovided,sincethemethodofthebaseobjectclassprovidesthesamefunctionality.
class apache::geode::client::SystemProperties Sealedclass SystemProperties
class apache::geode::client::UserData
Twooptions:
Interface IPdxSerializable
Interface IGeodeSerializable
class apache::geode::client::VectorT<T> Arrayofthegiventype,suchasT[]
Table1.C++Classto.NETClassMappings
©CopyrightPivotalSoftwareInc,2013-2019 145 9.1
Page 146
LATESTVERSION:9.1.1- RELEASENOTES
Javato.NETTypeMappingTableThefollowingtableprovidesamappingbetweenJavaand.NETtypes.
instancesof PdxSerializable .NETclassofsamename
instancesof PdxInstance .NETclassofsamename
instancesserializedbya PdxSerializer .NETclassofsamename
java.lang.Byte System.SByte
java.lang.Boolean System.Boolean
java.lang.Character System.Char
java.lang.Short System.Int16
java.lang.Integer System.Int32
java.lang.Long System.Int64
java.lang.Float System.Float
java.lang.Double System.Double
java.lang.String System.String
java.util.Date System.DateTime
byte[] System.Byte[]
boolean[] System.Boolean[]
char[] System.Char[]
short[] System.Int16[]
int[] System.Int32[]
long[] System.Int64[]
float[] System.Float[]
©CopyrightPivotalSoftwareInc,2013-2019 146 9.1
Page 147
float[] System.Float[]
double[] System.Double[]
String[] System.String[]
byte[][] System.Byte[][]
Object[] system.Collections.Generic.List<Object>
java.util.HashMap System.Collections.Generics.IDictionary<Object,Object>
java.util.Hashtable System.Collections.Hashtable
java.util.ArrayList System.Collections.Generic.IList<Object>
java.util.Vector Collections.ArrayList
java.util.HashSet CacheableHashSet
java.util.LinkedHashSet CacheableLinkedHashSet
Table1.Javatypesand.NETtypes
©CopyrightPivotalSoftwareInc,2013-2019 147 9.1
Page 148
LATESTVERSION:9.1.1- RELEASENOTES
ObjectLifetimesThe.NETAPIprovidesamanagedsetofassembliesfortheC++API.TheunderlyingC++objectwillstayinmemoryuntilthe.NETobjectisgarbage-collected.
TheunderlyingC++APIemploysreferencecountingusingsmartpointersformostclasses.ThismeansthatallAPIoperationswiththoseobjectsreturnareferencetotheunderlyingobjectandnotacopy.Consequently,theunderlyingobjectwillnotbefreedaslongasthe.NETapplicationholdsareferencetoanobject.Inotherwords,theunderlyingobjectwillstayinmemoryuntilthe.NETobjectisgarbage-collected.Aslongasareferencetoanobjectisalive,theartifactsitmaintainswillalsobealive.
Forexample,aslongasa Region objectisnotgarbage-collected,thenthedestructoroftheC++persistencemanager(ifany)fortheregionisnotinvoked.
IntheC++API,thereferencestoanobjectarereducedwhentheobjectgoesoutofscopeforstackallocation,orisdeletedexplicitlyforheapallocation.Theobjectisdestroyedwhenitsreferencecountreacheszero.Inthe.NETAPI,thereferencesarereducedwhentheobjectisgarbage-collectedorisexplicitlydisposedwiththe.NET using statement.
Becauseareferencetotheobjectisreturned,anychangetotheobjectalsoimmediatelychangestheobjectasstoredinternally.Forexample,ifanobjectisputintothecacheusingRegion.Put ,areferenceoftheobjectisstoredintheinternalstructures.Ifyoumodifytheobject,theinternalobjectalsochanges.However,itisnotdistributedtoothermembersofthedistributedsystemuntilanother Region.Put isdone.
Tofindoutifaclassisreferencecounted,lookattheAPIdocumentationfortheclass.Iftheclassiswrappedby UMWrap or SBWrap ,theclassisreferencecounted.
Theseareexamplesofclassesthatarereferencecounted:
Cache
CacheStatistics
DistributedSystem
Properties
RegionAttributes
AttributesMutator
RegionEntry
Region
EntryEvent
RegionEvent
Theseareexamplesofclassesthatarenotreferencecounted:
AttributesFactory
DataInput
DataOutput
SystemProperties
©CopyrightPivotalSoftwareInc,2013-2019 148 9.1
Page 149
LATESTVERSION:9.1.1- RELEASENOTES
.NETApplicationDomainsApplicationdomains,or AppDomain s,areunitsofisolation,securityboundaries,anddotheloadingandunloadingforapplicationsinthe.NETruntime.Multipleapplicationdomainscanruninasingleprocess.Eachcanhaveoneormanythreads,andathreadcanswitchapplicationdomainsatruntime.
The.NETmanagedassembliesrequireinterfacemethodsinvokedbytheC++layertobeinthesame AppDomain asthatofthe.NETDLL.Ifnot,anexceptionisthrownbecausethethreadisunabletocross AppDomain boundaries.
©CopyrightPivotalSoftwareInc,2013-2019 149 9.1
Page 150
LATESTVERSION:9.1.1- RELEASENOTES
ProblemScenariosThesescenariosdescribeprocessesandimplementationsthatshouldbeavoidedwhenusingthe AppDomain class.
UsingApplicationCallbacksScenario:A.NETthreadloadstheGemFireDLLinapplicationdomain AD1 .Thisthreadmayhaveaccesstotheotherdomainsintheapplicationifcodeaccesssecurityallowsit.Thisthreadcanthencall AppDomain.CreateInstance tocreateacallbackobject( ICacheListener , ICacheLoader ,or ICacheWriter )inanotherdomaincalled AD2 .Ifthecallbackobjectismarshaledbyreference,thecallbackisexecutedinthedomainwhereitiscreated( AD2 ).ThethreadthatloadstheGemFireDLLindomain AD1 runsthecallbackmethodsintheseconddomain,AD2 .Anexceptionisthrownwhenthecallbackmethodisinvokedbecausethecodethatinvokesthecallbackisnotallowedtocrossthe AppDomain boundary.
Resolution:WhenanapplicationcreatesandunloadsapplicationdomainsitshouldensurethattheapplicationdomainwheretheGemFire.NETDLLisloadedisthesamedomainwheretheapplicationcallbackand IGeodeSerializable objectsarecreated.
LoadinganApplicationDLLinMultipleAppDomainsScenario:TheapplicationloadstheGemFireDLLinoneapplicationdomain,thenreloadstheGemFireDLLinanotherapplicationdomain(withorwithoutunloadingthepreviousAppDomain ).Thecallbacks,aswellasotherinterfaceimplementations,like IPdxSerializable and IGeodeSerializable ,throwexceptionsbecausetheC++codedoesnotknowabouttheAppDomain andisloadedonlyonceintheinitial AppDomain .
Resolution:Theapplicationshouldalwaysusethefirst AppDomain toloadtheGemFireDLL,oritshouldnotloadtheGemFireDLLmultipletimes.
InsideIISScenario:WhenyoudeploymorethanonewebapplicationinsideanInternetInformationService(IIS),theIIScreatesanappdomainsubprocessforeachwebapplicationinthesingleprocess,buttheC++clientcacheinstanceremainsasingletonintheprocess.Becauseofthis,youcanrunintoconflictsbetweencachecreationandclosurebythedifferentappdomains.Forexample,ifoneappdomaincalls cache.close ,itclosesthecachefortheentireprocess.Anyfurthercacheaccessoperationsbytheotherappdomainsreturncacheclosedexceptions.
Resolution: Cachecreate / close providesreferencecountingof Cache create and close .Eachprocesscanusethecountertomakesureitcreatesthe Cache onceandclosesitonce.Toenablethis,settheGemFiresystemproperty, appdomain-enabled totrue.
©CopyrightPivotalSoftwareInc,2013-2019 150 9.1
Page 151
LATESTVERSION:9.1.1- RELEASENOTES
CreatingaCacheCreateacacheusingthe CacheFactory.Create call.Cachecreationinitializesthedistributedsystemandcreatesthecacheusingthe geode.properties and cache.xml filesettingsandanyadditionalpropertiesyouprovidetothecall.
SeeSettingSystemandCachePropertiesandseeCacheInitializationFile.
ConnectingandCreatingtheCacheInthisexample,theapplicationconnectstothedistributedsystemandcreatesthecacheusingtheavailableconfigurationfiles.
TheapplicationbecomesadistributedsystemmemberinthecacheCreatecall.
CacheFactorycacheFactory=CacheFactory.CreateCacheFactory();Cachecache=cacheFactory.Create();
ProvidingPropertiestotheCacheCreationYoucanalsocreateacachebyreferencinga cache.xml file,asshowninthefollowingexample.Youcanusethe Properties objecttochangeanyofthe geode.properties settings.
Propertiesprop=Properties.Create();prop.Insert("cache-xml-file","cache.xml");CacheFactorycacheFactory=CacheFactory.CreateCacheFactory(prop);Cachecache=cacheFactory.Create();
Forsystemswithsecurityenabled,thecredentialsforajoiningmemberareauthenticatedwhenthecacheiscreatedandthesystemconnectionismade.Formoreinformationaboutsecureconnectionstoadistributedsystem,seeSecurity.
©CopyrightPivotalSoftwareInc,2013-2019 151 9.1
Page 152
LATESTVERSION:9.1.1- RELEASENOTES
CreatingaRegionTocreatearegion,use RegionFactory withthe RegionShortcut thatmostcloselyfitstheregionconfiguration.
Fromthatpoint,customizethesettingsforregionattributesasneeded.
CreatingaregionusingtheclientAPIonlycreatesaproxyclientsideregion.Acorrespondingregionwiththesamenameandpathmustalsoexistontheserversthathavebeenconfiguredforclientconnectionsanduponwhichtheclientwillperformitsoperations.
CreatingaCACHING_PROXYRegionThisexamplecreatesaregionusingtheCACHING_PROXYshortcutwithnofurthermodifications:
RegionFactoryregionFactory=cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY);
IRegion<string,string>region=regionFactory.Create<string,string>("exampleRegion");
CreatingaCACHING_PROXYRegionwithLRUThisexamplecreatesaregionbasedontheCACHING_PROXYshortcut,modifyingvaluesfortworegionattributes.Forinformationonthesettings,seeRegionAttributesDescriptions
RegionFactoryregionFactory=cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY);
IRegion<string,string>region=regionFactory.SetLruEntriesLimit(20000).SetInitialCapacity(20000).Create<string,string>("exampleRegion");
©CopyrightPivotalSoftwareInc,2013-2019 152 9.1
Page 153
LATESTVERSION:9.1.1- RELEASENOTES
AddinganEntrytotheCachePopulateaclientregionwithcacheentriesbyusingthegeneric IDictionary APIorbyusingthe.NET Region.Put orthe Region.Create APIfunctions.
The Put functionplacesanewvalueintoaregionentrywiththespecifiedkey,whilethe Create functioncreatesanewentryintheregion.The Put and Create functionsprovideauser-definedparameterobjecttoanycachewriterinvokedintheprocess.
Ifavaluefortheentrykeyalreadyexistsinthecachewhenyouaddanentry,GemFireoverwritesthepreviouslycachedvalue.Newvaluesinthecachearepropagatedtotheconnectedcacheserver.
The.NETGenericsprovidetypesafety,soyoucannotchangeyourentrykeyandvaluetypesonceyouhavebeguntopopulatetheregion.Ifyouneedtousedifferenttypesforthesameregion,storethemallinsideobjectsintheregion.
UsingtheAPItoPutValuesIntotheCacheInthisexample,theprogramputsentriesintothecachewithstringvalues.
region1["Key1"]="Value1";region1["Key2"]="Value2";
region2["KeyA"]=123;region2["KeyB"]=100;region3.Put(111,"Value1",null);region3.Put(222,"Value2",null);
BatchOperations—UsingPutAlltoAddMultipleEntriesYoucanbatchupmultiplekey/valuepairsintoahashmapandputthemintothecachewithasingleoperationusingthe.NETRegion.PutAll APIfunction.Eachentryisprocessedforinterestregistrationontheserver,soeachentryrequiresitsownuniqueeventID.Updatesandcreatescanbemixedina PutAll operation,sothoseeventsneedtobeaddressedonthecacheserverforappropriatecachelistenerinvocationondistributedsystemmembers.Mapentriesretaintheiroriginalorderwhentheyareprocessedattheserver.
©CopyrightPivotalSoftwareInc,2013-2019 153 9.1
Page 154
LATESTVERSION:9.1.1- RELEASENOTES
AccessinganEntryTheregionentryretrievalmethodsreturnthevalueassociatedwiththespecifiedkey,andpassthecallbackargumenttoanycacheloadersorcachewritersthatareinvokedduringtheoperation.
Ifthevalueisnotavailablelocally,itisrequestedfromtheserver.Iftheserverrequestisunsuccessful,alocalcacheloaderisinvoked,ifoneisavailable.TheoperationthrowskeyNotFoundException ifthe Region isunabletoretrieveavaluethroughanyofthesemeans.
UsingtheRegionAPItoRetrieveValuesFromtheCacheHere,thecodefragmentaccomplishesentryretrievalintwoways.
stringvalue1=region1["Key1"];stringvalue2=region1["Key2"];
stringvalueQ=region.Get(111,null);stringvalueR=region.Get(222,null);
BatchOperations—UsinggetAlltoReturnValuesfromMultipleEntriesThe GetAll regionAPIreturnsvaluesforcollectionofkeysfromthelocalcacheorserver.
Ifvalueforakeyisnotpresentlocally,thenitisrequestedfromtheJavaserver.Thevaluereturnedisnotcopied,somulti-threadedapplicationsshouldnotmodifythevaluedirectlybutshouldusetheupdatemethods.
Thismethodisnotapplicabletolocalregioninstances.
Thisoperationupdatesthe CacheStatistics.LastAccessedTime , CacheStatistics.HitCount statisticsand CacheStatistics.MissCount forthisregionandthereturnedentries.
©CopyrightPivotalSoftwareInc,2013-2019 154 9.1
Page 155
LATESTVERSION:9.1.1- RELEASENOTES
RemovinganEntryThe Region.Remove functionremovestheentrywithspecifiedkeyandprovidesauser-definedparameterobjecttoany CacheWriter or CacheListener invokedintheprocess.
The Remove callnotonlyremovesthevalue,butalsothekeyandentryfromthisregion.Theremoveoperationispropagatedtotheserverthattheclientisconnectedto.Ifthedestroyoperationfailsduetoanexceptionontheserver(forexample,a CacheServerException orsecurityexception),thenthelocalentryisstillremoved.
The Remove operationupdates CacheStatistics.LastAccessedTime , CacheStatistics.HitCount ,and CacheStatistics.MissCount forthisregionandtheentry.
The Remove APIreturnstrueiftheentry(key,value)hasbeenremovedorfalseiftheentry(key,value)hasnotbeenremoved.
BulkRemoveOperationsUsingRemoveAllYoucanusethe Region.RemoveAll APItoremoveallentriesforacollectionofspecifiedkeysfromtheregion.TheeffectofthiscallisequivalenttothatofcallingRemove onthisregiononceforeachkeyinthespecifiedcollection.Ifanentrydoesnotexist,thenthatkeyisskipped.Notethatan EntryNotFoundException isnotthrown.
The RemoveAll operationupdates CacheStatistics.LastAccessedTime , CacheStatistics.HitCount ,and CacheStatistics.MissCount forthisregionandtheentriesthatareremoved.
The RemoveAll APIalsosupportsprovidingacallbackargumenttoanycacheloadersorcachewritersthatareinvokedintheoperation.
©CopyrightPivotalSoftwareInc,2013-2019 155 9.1
Page 156
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationAlldatamovingoutoftheclientcachemustbeserializable.
Regiondatathatmustbeserializablefallsunderthefollowingcategories:
Partitionedregions(exceptfunctionsthatadddatalocallytoapartitionedregionusethedeserializedform).
Distributedregions.
Regionsthatarepersistedoroverflowedtodisk.
Serverorclientregionsinaclient/serverinstallation.
Regionsdistributedbetweengatewaysinamulti-siteinstallation.
Regionsthatreceiveeventsfromremotecaches.
Regionsthatprovidefunctionargumentsandresults.
Tominimizethecostofserializationanddeserialization,GemFireavoidschangingthedataformatwheneverpossible.Thismeansyourdatamaybestoredinthecacheinserializedordeserializedform,dependingonhowyouuseit.Forexample,ifaserveractsonlyasastoragelocationfordatadistributionbetweenclients,itmakessensetoleavethedatainserializedform,readytobetransmittedtoclientsthatrequestit.Partitionedregiondataisalwaysstoredinserializedformwithoneexception—functionsthatadddatatoapartitionedregionlocallyusethedeserializedform.
©CopyrightPivotalSoftwareInc,2013-2019 156 9.1
Page 157
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationOptionsBuilt-in.NETtypesareserializedautomaticallyintothecacheandcanberetrievedbyJavaserversandotherGemFireclients.Fordomainobjectsthatarenotsimpletypes,youhavethreeGemFireserializationoptions.
Theoptionsgivegoodperformanceandflexibilityfordatastorage,transfers,andlanguagetypes.TheGemFireoptionscanalsoimproveperformanceinserializinganddeserializingbuilt-intypes.
ThesimplestoptionistouseperformautomaticserializationbyregisteringtheGemFire.NETPDXreflection-basedautoserializerinyourapplication.Whenyouhavethisregistered,GemFireusesitforalldomainobjectsthatarenotcustomserialized.
YoucanalsocustomserializeyourobjectsbyimplementingoneoftheGemFire.NETinterfaces,Apache.Geode.Client.IPdxSerializable or Apache.Geode.Client.IGeodeSerializable .
Youalsohavetheoptionofusingdefault.NETserialization,butyoucannotuseitunlessyoualsousehelperclasses.ThehelperclassesyoumustuseareCacheableObject andCacheableObjectXml .
GemFire.NETPDXserializationhasmorebytesinoverheadthanGemFire.NETDataserialization,butusingPDXserializationhelpsyouavoidtheperformancecostsofdeserializationwhenperformingqueries.Applicationscanuse PdxInstances infunctionstoavoidthedeserializationofentireobjects.
Table1.SerializationOptions—ComparisonofFeatures
Handlesmultipleversionsofdomainobjects* X
Providessinglefieldaccessonserversofserializeddata,withoutfulldeserialization.SupportedalsoforOQLqueries.
X
AutomaticallyportedtootherlanguagesbyGemFire-noneedtoprogramJava-sideimplementation X
WorkswithGemFiredeltapropagation X X(Seeexplanationbelow.)
*Youcanmixdomainobjectversionswherethedifferencesbetweenversionsaretheadditionandremovalofobjectfields.
Bydefault,youcanuseGemFiredeltapropagationwithPDXserialization.However,deltapropagationwillnotworkifyouhavesettheGemFirepropertyread-serializedto“true”.Intermsofdeserialization,toapplyachangedeltapropagationrequiresadomainclassinstanceandthe fromDelta method.Ifyouhavesetread-serializedtotrue,youwillreceiveanIPdxInstance insteadofadomainclassinstanceand IPdxInstance doesnothavethe fromDelta methodrequiredfordeltapropagation.YouwillalsorequiretheJavadomainclassontheserversimilartotheyouwouldneedthe.NETPDXDeltadomainclass.
©CopyrightPivotalSoftwareInc,2013-2019 157 9.1
Page 158
LATESTVERSION:9.1.1- RELEASENOTES
SerializewithPDXSerializationGemFire’sPortableDataeXchange(PDX)isacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.PDXstoresdatainnamedfieldsthatyoucanaccessindividually,toavoidthecostofdeserializingtheentiredataobject.PDXalsoallowsyoutomixversionsofobjectswhereyouhaveaddedorremovedfields.
YouhavetwooptionsforGemFirePDXserializationwhenusingthe.NETcachingAPI.Youcanprogramyourdomainobjectsusingthe IPdxSerializable interface,oryoucanuseGemFire’sreflection-basedautoserializer.
©CopyrightPivotalSoftwareInc,2013-2019 158 9.1
Page 159
LATESTVERSION:9.1.1- RELEASENOTES
GemFirePDXSerializationFeaturesGemFirePDXserializationoffersseveraladvantages.
ApplicationVersioningofPDXDomainObjectsDomainobjectsevolvealongwithyourapplicationcode.Youmaycreateanaddressobjectwithtwoaddresslines,thenrealizelaterthatathirdlineisrequiredforsomesituations.Oryoumayrealizethataparticularfieldisnotusedandwanttogetridofit.
WithPDX,youcanuseoldandnewversionsofdomainobjectstogetherinadistributedsystemiftheversionsdifferbytheadditionorremovaloffields.Thiscompatibilityletsyougraduallyintroducemodifiedcodeanddataintothesystem,withoutbringingthesystemdown.
GemFiremaintainsacentralregistryofthePDXdomainobjectmetadata.Usingtheregistry,GemFirepreservesfieldsineachmember’scacheregardlessofwhetherthememberhasthefielddefined.Whenamemberreceivesanobjectthathasafieldregisteredthatthememberisnotawareof,thememberdoesnotaccessthefield,butpreservesitandpassesitalongwiththerestoftheobjecttoothermembers.Whenamemberreceivesanobjectthatismissingoneormorefieldsaccordingtothemember’sversion,GemFireassignsthe.NETdefaultvaluesforthefieldtypestothemissingfields.
PortabilityofPDXSerializableObjectsWhenyoucreatean IPdxSerializable object,GemFirestorestheobject’stypeinformationinacentralregistry.Theinformationispassedbetweenpeers,betweenclientsandservers,andbetweendistributedsystems.
Thisoffersanotableadvantagetothe.NETclient,whichsharesdatawithJavacacheservers.Clientsautomaticallypassregistryinformationtoserverswhentheystoreanobject.Clientscanrunqueriesandfunctionsagainstthedataintheserverswithouttheserversneedingtoknowanythingaboutthestoredobjects.Oneclientcanstoredataontheservertoberetrievedbyanotherclient,withtheserverneverneedingtoknowtheobjecttype.Thismeansyoucancodeyour.NETclientstomanagedatausingJavaserverswithouthavingtocreateJavaimplementationsofyour.NETdomainobjects.
ReducedDeserializationofSerializedObjectsTheaccessmethodsfor IPdxSerializable objectsallowyoutoexaminespecificfieldsofyourdomainobjectwithoutdeserializingtheentireobject.Thiscanreduceserializationanddeserializationcostssignificantly..NETclientscanrunqueriesandexecutefunctionsagainsttheobjectsintheservercacheswithoutdeserializingtheentireobjectontheserverside.ThequeryengineautomaticallyrecognizesPDXobjectsandusesonlythefieldsitneeds.
ClientscanexecuteJavafunctionsonserverdatathatonlyaccesspartsofthedomainobjectsbyusing PdxInstance.
Likewise,peerscanaccessjustthefieldsneededfromtheserializedobject,keepingtheobjectstoredinthecacheinserializedform.
©CopyrightPivotalSoftwareInc,2013-2019 159 9.1
Page 160
LATESTVERSION:9.1.1- RELEASENOTES
SerializeUsingtheGemFirePDXAutoserializerWhenyouregisterthereflection-basedserializer,GemFireusesittoserializeallobjectsthatdonotimplement IPdxSerializable or IGeodeSerializable .Youcancustomizetheauto-serializationbehaviorforyourdomainobjectsbyaddingserializationattributestoyourobject’sfields.
Procedure
1. IfyouhavenotalreadyregisteredthePDXreflection-basedautoserializer,addtheregistrationcodetoyourapplication.Forexample:
usingApache.Geode.Client;...//Registerreflection-basedautoserializertoserialize//domainobjectsusingPDXserializationSerializable.RegisterPdxSerializer(newReflectionBasedAutoSerializer());
Thiscanonlybeconfiguredintheapplicationcode.Itcannotbeconfigureddeclarativelyin cache.xml .
2. (Optional)Foreachobjectyouintendtohaveautoserialized,customizetheserializationasneeded.Note:IfyoualsousePDXserializationinJavafortheobject,customizeyourserializationthesameforbothlanguages.
a. Thefollowingextensionmethodsapplytoautoserialization:
WriteTransform.Controlswhatfieldvalueiswrittenduringautoserialization.ReadTransform.Controlswhatfieldvalueisreadduringautodeserialization.GetFieldType.Definesthespecificfieldnamesthatwillbegeneratedduringautoserialization.IsIdentityField.Controlswhichfieldismarkedastheidentityfield.Identityfieldsareusedwhena PdxInstance computesitshashcodetodeterminewhetheritisequaltoanotherobject.GetFieldType.Determinesthefieldtypethatwillbeusedwhenautoserializingthegivenfield.IsFieldIncluded.Specifieswhichfieldsofaclasstoautoserialize.
SeeExtendingtheAutoserializerforsampleusage.b. IfyouarewritingaJavaapplication,youcanusethe IPdxType MappertomapJavatypesto.NETtypes.Notethatyouonlyneedtousethe IPdxTypeMapper ifyouarewritingJavaapplications.SeeMap.NETDomainTypeNamestoPDXTypeNameswithIPdxTypeMapperforsampleusage.
c. Tospecifyanidentifierfieldinyourdomainobject,addtheattribute PdxIdentityField tothefield.Forexample:
[PdxIdentityField]privateintid;
d. Toexcludeafieldfromserialization,addthe.NETattribute NonSerialized tothefield.Forexample:
[NonSerialized]privateintmyLocalData;
ForeachdomainclassGemFireserializesusingtheautoserializer,allfieldsareconsideredforserializationexceptthosedefinedas static , literal or readonly andthoseyouexplicitlyexcludeusingthe.NET NonSerialized attribute.
©CopyrightPivotalSoftwareInc,2013-2019 160 9.1
Page 161
LATESTVERSION:9.1.1- RELEASENOTES
ExtendthePDXAutoserializerThisexamplecodedemonstrateshowtoextendtheautoserializertocustomizeserialization.
ExtendingtheAutoserializer
publicclassAutoSerializerEx:ReflectionBasedAutoSerializer{publicoverrideobjectWriteTransform(FieldInfofi,Typetype,objectoriginalValue){if(fi.FieldType.Equals(Type.GetType("System.Guid"))){returnoriginalValue.ToString();}elseif(fi.FieldType.Equals(Type.GetType("System.Decimal"))){returnoriginalValue.ToString();}elsereturnbase.WriteTransform(fi,type,originalValue);}
publicoverrideobjectReadTransform(FieldInfofi,Typetype,objectserializeValue){if(fi.FieldType.Equals(Type.GetType("System.Guid"))){Guidg=newGuid((string)serializeValue);returng;}elseif(fi.FieldType.Equals(Type.GetType("System.Decimal"))){returnConvert.ToDecimal((string)serializeValue);}elsereturnbase.ReadTransform(fi,type,serializeValue);}
publicoverrideFieldTypeGetFieldType(FieldInfofi,Typetype){if(fi.FieldType.Equals(Type.GetType("System.Guid"))||fi.FieldType.Equals(Type.GetType("System.Decimal")))returnFieldType.STRING;returnbase.GetFieldType(fi,type);}
publicoverrideboolIsIdentityField(FieldInfofi,Typetype){if(fi.Name=="_identityField")returntrue;returnbase.IsIdentityField(fi,type);}
publicoverridestringGetFieldName(FieldInfofi,Typetype){if(fi.Name=="_nameChange")returnfi.Name+"NewName";returnfi.Name;}
publicoverrideboolIsFieldIncluded(FieldInfofi,Typetype){if(fi.Name=="_notInclude")returnfalse;returnbase.IsFieldIncluded(fi,type);}}
©CopyrightPivotalSoftwareInc,2013-2019 161 9.1
Page 162
LATESTVERSION:9.1.1- RELEASENOTES
SerializeYourDomainObjectswithIPdxSerializerFordomainobjectsthatyoucannotordonotwanttomodify,usethe IPdxSerializer classtoserializeanddeserializetheobject’sfields.
Youuseone IPdxSerializer implementationfortheentirecache,programmingitforallofthedomainobjectsthatyouhandleinthisway.ThiswayyoudonothavetoimplementtheIPdxSerializable interfaceforeachdomainclass.
With IPdxSerializer ,youleaveyourdomainobjectas-isandhandletheserializationanddeserializationintheseparateserializer.YouregistertheserializerinyourcachePDXconfiguration.Thenprogramtheserializertohandleallofthedomainobjectsyouneed.
Ifyouwriteyourown IPdxSerializer andyoualsousethe ReflectionBasedAutoSerializer ,thenthe IPdxSerializer needstoownthe ReflectionBasedAutoSerializer anddelegatetoit.Acachecanonlyhaveasingle IPdxSerializer instance.
Note:The IPdxSerializer toData and fromData methodsdifferfromthosefor IPdxSerializable .Theyhavedifferentparametersandresults.
Toregisteran IPdxSerializer ,youcanusethefollowingcode.Notethatyoucanonlyregisterthe IPdxSerializer intheapplicationcode.Itcannotbeconfigureddeclarativelyin
Example:
usingApache.Geode.Client;...//RegisteraPdxSerializertoserialize//domainobjectsusingPDXserialization
Serializable.RegisterPdxSerializer(newMyPdxSerializer());
©CopyrightPivotalSoftwareInc,2013-2019 162 9.1
Page 163
LATESTVERSION:9.1.1- RELEASENOTES
SerializeUsingtheIPdxSerializableInterfaceUsethisproceduretoprogramyourdomainobjectforPDXserializationusingthe IPdxSerializable Interface.WhenyouwriteobjectsusingPDXserialization,theyaredistributedtotheservertierinPDXserializedform.Whenyourunqueriesagainsttheobjectsontheservers,onlythefieldsyouspecifyaredeserialized.
Procedure
1. Inyourdomainclass,implement Apache.Geode.Client.IPdxSerializable .Example:
usingApache.Geode.Client;...publicclassPortfolioPdx:IPdxSerializable
2. Ifyourdomainclassdoesnothaveazero-argconstructor,createoneforit.IfyoualsousePDXserializationinJavafortheobject,serializetheobjectinthesamewayforeachlanguage.Serializethesamefieldsinthesameorderandmarkthesameidentifyfields.
3. Programthe IPdxSerializableToData functiontoserializeyourobjectasrequiredbyyourapplication.
a. Writeyourdomainclass’sstandard.NETdatafieldsusingthe IPdxWriter writemethods.GemFireautomaticallyprovides IPdxWriter tothe ToData functionforIPdxSerializable objects.
b. Callthe ToDatamarkIdentifyField functionforeachfieldGemFireshouldusetoidentifyyourobject.Thisisusedtocompareobjectsforoperationslike DISTINCTmarkIdentifyField callmustcomeaftertheassociatedfieldwritemethods.Example:
//objectfieldsprivateintm_id;privatestringm_pkid;privatePositionPdxm_position1;privatePositionPdxm_position2;privateHashtablem_positions;privatestringm_type;privatestringm_status;privatestring[]m_names;privatebyte[]m_newVal;privateDateTimem_creationDate;privatebyte[]m_arrayZeroSize;privatebyte[]m_arrayNull;//ToDatapublicvoidToData(IPdxWriterwriter){writer.WriteInt("id",m_id)//identityfield.MarkIdentityField("id").WriteString("pkid",m_pkid).WriteObject("position1",m_position1).WriteObject("position2",m_position2).WriteObject("positions",m_positions).WriteString("type",m_type).WriteString("status",m_status).WriteStringArray("names",m_names).WriteByteArray("newVal",m_newVal).WriteDate("creationDate",m_creationDate).WriteByteArray("arrayNull",m_arrayNull).WriteByteArray("arrayZeroSize",m_arrayZeroSize);}
4. Program IPdxSerializableFromData toreadyourdatafieldsfromtheserializedformintotheobject’sfieldsusingthe IPdxReader readmethods.GemFireautomaticallyprovidesIPdxReader tothe FromData functionfor IPdxSerializable objects.Usethesamenamesasyoudidin ToData andcallthereadoperationsinthesameorderasyoucalledthewriteoperationsinyour ToData implementation.Example:
©CopyrightPivotalSoftwareInc,2013-2019 163 9.1
Page 164
publicvoidFromData(IPdxReaderreader){m_id=reader.ReadInt("id");
boolisIdentity=reader.IsIdentityField("id");
if(isIdentity==false)thrownewIllegalStateException("Portfolioidisidentityfield");
boolisId=reader.HasField("id");
if(isId==false)thrownewIllegalStateException("Portfolioidfieldnotfound");
boolisNotId=reader.HasField("ID");
if(isNotId==true)thrownewIllegalStateException("PortfolioisNotIdfieldfound");
m_pkid=reader.ReadString("pkid");m_position1=(PositionPdx)reader.ReadObject("position1");m_position2=(PositionPdx)reader.ReadObject("position2");m_positions=(Hashtable)reader.ReadObject("positions");m_type=reader.ReadString("type");m_status=reader.ReadString("status");m_names=reader.ReadStringArray("names");m_newVal=reader.ReadByteArray("newVal");m_creationDate=reader.ReadDate("creationDate");m_arrayNull=reader.ReadByteArray("arrayNull");m_arrayZeroSize=reader.ReadByteArray("arrayZeroSize");}
5. Optionally,programyourdomainobject’sequalsandhashcodemethods.
©CopyrightPivotalSoftwareInc,2013-2019 164 9.1
Page 165
LATESTVERSION:9.1.1- RELEASENOTES
ProgramYourApplicationtoUseIPdxInstanceAn IPdxInstance isalightweightwrapperaroundPDXserializedbytes.Itprovidesapplicationswithrun-timeaccesstofieldsofaPDXserializedobject.
Youcanconfigureyourcachetoreturnan IPdxInstance whenaPDXserializedobjectisdeserializedinsteadofdeserializingtheobjecttoadomainclass.Youcanthenprogramyourapplicationcodethatreadsyourentriestohandle IPdxInstances fetchedfromthecache.
Note:Thisoptionappliesonlytoentryretrievalthatyouexplicitlycodeusingmethodslike EntryEvent.getNewValue and Region.get ,asyoudoinsidefunctionsorincachelistenercode.Thisdoesnotapplytoqueryingbecausethequeryengineretrievestheentriesandhandlesobjectaccessforyou.
Note: IPdxInstance overridesanycustomimplementationyoumighthavecodedforyourobject’s equals and hashcode methods.
Procedure
1. Inthe cache.xml fileoftheservermemberwhereentryfetchesarerun,setthe <pdx> read-serializedattributetotrue.Dataisnotnecessarilyaccessedonthememberthatyouhavecodedforit.Forexample,ifaclientapplicationrunsafunctiononaserver,theactualdataaccessisdoneontheserver,soyousetread-serializedtotrueontheserver.Forexample:
//CacheconfigurationsettingPDXreadbehavior<cache><pdxread-serialized="true"/>...</cache>
2. Writetheapplicationcodethatfetchesdatafromthecachetohandlea IPdxInstance .Ifyouaresureyouwillonlyretrieve IPdxInstances fromthecache,youcancodeonlyforthat.Inmanycases,a IPdxInstance oradomainobjectmaybereturnedfromyourcacheentryretrievaloperation,soyoushouldchecktheobjecttypeandhandleeachpossibletype.SeeCreatinganIPdxInstancewithIPdxInstanceFactoryforanexampleofthis.
IfyouconfigureyourcachetoallowPDXserializedreads,cachefetchesreturnthedataintheformitisfound.Iftheobjectisnotserialized,thefetchreturnsthedomainobject.Iftheobjectisserialized,thefetchreturnsthe PdxInstance fortheobject.
Note:Ifyouareusing IPdxInstances ,youcannotusedeltapropagationtoapplychangestoPDXserializedobjects.
Forexample,inclient/serverapplicationsthatareprogrammedandconfiguredtohandlealldataactivityfromtheclient,PDXserializedreadsdoneontheserversidewillalwaysreturnthe IPdxInstance .Thisisbecauseallofdataisserializedfortransferfromtheclientandyouarenotperforminganyserver-sideactivitiesthatwoulddeserializetheobjectsintheservercache.
Inmixedsituations,suchaswhereaservercacheispopulatedfromclientoperationsandalsofromdataloadsdoneontheserverside,fetchesdoneontheservercanreturnamixofIPdxInstances anddomainobjects.
WhenfetchingdatainacachewithPDXserializedreadsenabled,thesafestapproachistocodetohandlebothtypes,receivinganObjectfromthefetchoperation,checkingthetypeandcastingasappropriate.
©CopyrightPivotalSoftwareInc,2013-2019 165 9.1
Page 166
LATESTVERSION:9.1.1- RELEASENOTES
UsetheIPdxInstanceFactorytoCreateIPdxInstancesYoucanusethe IPdxInstanceFactory tocreatean IPdxInstance fromrawdatawhenthedomainclassisnotavailableontheserver.
Thisoptioncanbeusefulwhenyouneedaninstanceofadomainclassforplug-incodesuchasafunctionoraloader.Ifyouhavetherawdataforthedomainobject(theclassnameandeachfield’stypeanddata),thenyoucanexplicitlycreatea IPdxInstance .The IPdxInstanceFactory isverysimilartothe IPdxWriter exceptthatafterwritingeachfield,youneedtocallthecreatemethodwhichreturnsthecreated IPdxInstance.
ViewthePdxInstanceQuickStartforanexample.
©CopyrightPivotalSoftwareInc,2013-2019 166 9.1
Page 167
LATESTVERSION:9.1.1- RELEASENOTES
Map.NETDomainTypeNamestoPDXTypeNameswithIPdxTypeMapperPDXserializedinstancesinJavamapto.NETtypeswiththesamename.Ifyouneedtoadjustthe.NETname,thenyouneedtousetheIPdxTypeMapper.
SeetheJavato.NETTypeMappingTable forcurrentmappings.
UsingIPdxTypeMapper
//Thisdemonstrates,howtomap.NETtypetopdxtypeorjavatypepublicclassPdxTypeMapper:IPdxTypeMapper{
publicstringToPdxTypeName(stringlocalTypeName){return"pdx_"+localTypeName;}
publicstringFromPdxTypeName(stringpdxTypeName){returnpdxTypeName.Substring(4);//needtoextract"pdx_"}}
©CopyrightPivotalSoftwareInc,2013-2019 167 9.1
Page 168
LATESTVERSION:9.1.1- RELEASENOTES
SerializewiththeIGeodeSerializableInterfaceThe.NET IGeodeSerializable interfaceprovidesfastandcompactdataserialization.
GenericandCustomSerializableTypesAllbuilt-ingenericsareautomaticallyregisteredatinitialization.Youhaveacoupleofoptionsforcomplexkeytypes.
HowSerializationWorkswithIGeodeSerializableWhenyourapplicationputsanobjectintothecachefordistribution,GemFireserializesthedatabytakingthesesteps.
ImplementtheIGeodeSerializableInterfaceTostoreyourowndatatypesinthecache,youimplementtheGemFire IGeodeSerializable interface.
RegistertheTypeTousethe BankAccount type,youmustregisteritwiththetypesystem.Then,whenanincomingstreamcontainsa BankAccount ,itcanbemanufacturedfromtheassociatedTypeFactoryMethod.
©CopyrightPivotalSoftwareInc,2013-2019 168 9.1
Page 169
LATESTVERSION:9.1.1- RELEASENOTES
GenericandCustomSerializableTypesAllbuilt-ingenericsareautomaticallyregisteredatinitialization.Youhaveacoupleofoptionsforcomplexkeytypes.
Ifyourapplicationusesmorecomplexkeytypesthatyouwanttomakemoreaccessibleoreasiertohandle,youcanderiveanewclassfromIGeodeSerializable .Anotheroptionisfortheapplicationtodoitsownobjectserializationusing Byte[] oracustomtype.
BlobsIfyouhavedatathatisbesthandledasablob,suchasstructsthatdonotcontainpointers,usea Byte[] or,ifyouneedsomethingmorecomplexthan Byte[] ,implementacustomtypeusingeither IPdxSerializable or IGeodeSerializable .
ObjectGraphsIfyouhaveagraphofobjectsinwhicheachnodecanbeserializable,theparentnodecalls DataOutput.WriteObject todelegatetheserializationresponsibilitytoitschildnodes.Similarly,yourapplicationcalls DataInput.ReadObject todeserializetheobjectgraph.
Note:TheGemFire IGeodeSerializable interfacedoesnotsupportobjectgraphswithmultiplereferencestothesameobject.Ifyourapplicationusesthesetypesofcirculargraphs,youmustaddressthisdesignconcernexplicitly.
©CopyrightPivotalSoftwareInc,2013-2019 169 9.1
Page 170
LATESTVERSION:9.1.1- RELEASENOTES
HowSerializationWorkswithIGeodeSerializableWhenyourapplicationputsanobjectintothecachefordistribution,GemFireserializesthedatabytakingthesesteps.
1. Callstheappropriate ClassId functionandcreatesthe TypeId fromit.
2. Writesthe TypeId fortheinstance.
3. Invokesthe ToData functionfortheinstance.
Whenyourapplicationsubsequentlyreceivesabytearray,GemFiretakesthefollowingsteps:
1. Decodesthe TypeId andcreatesanobjectofthedesignatedtype,usingtheregisteredfactoryfunctions.
2. Invokesthe FromData functionwithinputfromthedatastream.
3. Decodesthedataandthenpopulatesthedatafields.
The TypeId isanintegeroffourbytes,whichisacombinationof ClassId integerand 0x27 ,whichisanindicatorofuser-definedtype.
©CopyrightPivotalSoftwareInc,2013-2019 170 9.1
Page 171
LATESTVERSION:9.1.1- RELEASENOTES
ImplementtheIGeodeSerializableInterfaceTostoreyourowndatatypesinthecache,youimplementtheGemFire IGeodeSerializable interface.
Examplesfollowtheprocedure.
Procedure
1. Implementthe ToData functionthatserializesyourdata:
voidToData(DataOutputoutput)
The ToData functionisresponsibleforcopyingallofthedatafieldsfortheobjecttotheobjectstream.TheDataOutput classrepresentstheoutputstreamandprovidesmethodsforwritingtheprimitivesinanetworkbyteorder.
2. Implementthe FromData functionthatconsumesadatainputstreamandrepopulatesthedatafieldsfortheobject:
voidfromData(DataInput&input)
The DataInput classrepresentstheinputstreamandprovidesmethodsforreadinginputelements.The FromData functionmustreadtheelementsoftheinputstreaminthesameorderthattheywerewrittenby ToData .
3. Implementthe ClassId functiontoreturnanintegerwhichisuniqueforyourclass(inthesetofallofyouruser-definedclasses).
SimpleBankAccountClassThisexampleshowsasimpleclass, BankAccount ,thatencapsulatesthetwo ints , customerId and accountId :
publicclassBankAccount{privateintm_customerId;privateintm_accountId;publicintCustomer{get{returnm_customerId;}}publicintAccount{get{returnm_accountId;}}publicBankAccount(intcustomer,intaccount){m_customerId=customer;m_accountId=account;}}
ImplementingaSerializableClassTomake BankAccount serializable,youimplementthe IGeodeSerializable interfaceasshowninthisexample:
©CopyrightPivotalSoftwareInc,2013-2019 171 9.1
Page 172
publicclassBankAccount:IGeodeSerializable{privateintm_customerId;privateintm_accountId;publicintCustomer{get{returnm_customerId;}}publicintAccount{get{returnm_accountId;}}publicBankAccount(intcustomer,intaccount){m_customerId=customer;m_accountId=account;}//OurTypeFactoryMethodpublicstaticIGeodeSerializableCreateInstance(){returnnewBankAccount(0,0);}#regionIGeodeSerializableMemberspublicvoidToData(DataOutputoutput){output.WriteInt32(m_customerId);output.WriteInt32(m_accountId);}publicIGeodeSerializableFromData(DataInputinput){m_customerId=input.ReadInt32();m_accountId=input.ReadInt32();returnthis;}publicUInt32ClassId{get{return11;}}publicUInt32ObjectSize{get{return(UInt32)(sizeof(Int32)+sizeof(Int32));}}}
©CopyrightPivotalSoftwareInc,2013-2019 172 9.1
Page 173
LATESTVERSION:9.1.1- RELEASENOTES
RegistertheTypeTousethe BankAccount type,youmustregisteritwiththetypesystem.Then,whenanincomingstreamcontainsa BankAccount ,itcanbemanufacturedfromtheassociatedTypeFactoryMethod.
Serializable.RegisterType(BankAccount.CreateInstance);
Typically,youwouldregisterthetypebeforecreatingthesystem.
UsingClassIdA ClassId isanintegerthatreturnsthe ClassId oftheinstancebeingserialized.The ClassId isusedbydeserializationtodeterminewhatinstancetypetocreateanddeserializeinto.
UsingDSFIDA DSFID isanintegerthatreturnsthedataserializationfixedIDtype. DSFID isusedtodeterminewhatinstancetypetocreateanddeserializeinto. DSFID shouldnotbeoverriddenbycustomimplementations,anditisreservedonlyforbuilt-inserializabletypes.
UsingCustomKeyTypesIfyourapplicationusesitsownkeytypesthataretoocomplextoeasilyforceintostring,youcanprobablyimproveperformancebyusingacustomtypeandimplementingEquals functions.Forexample,ifyouhavehybriddatatypessuchasfloatingpointnumbers,youcanimplementyourowntypethatencapsulatesthefloatingpointnumber.Comparingfloatingpointnumbersinthiswayprovidesgreaterperformancethancomparingastringrepresentationofthefloatingpointnumbers,withsuchnoticeableimprovementsasfastercacheaccessandsmallerpayloads.
SeeSerializationinNativeClientModewithaJavaServerforinformationaboutimplementingkeytypesforaclientthatisusedwithaJavacacheserver.
Toextendatypethatimplements IPdxSerializable or IGeodeSerializable foryourkey,overrideandimplementthe HashCode and Equals methodsinthekeyasneeded.
©CopyrightPivotalSoftwareInc,2013-2019 173 9.1
Page 174
LATESTVERSION:9.1.1- RELEASENOTES
UsingaCustomClassWithIGeodeSerializableAnexampleshowshowtousethe BankAccount customkeytypeandthe AccountHistory valuetypethatwerepreviouslydefined.
UsingaBankAccountObject
classAccountHistory:IGeodeSerializable{#regionPrivatemembersprivateList<string>m_history;#endregionpublicAccountHistory(){m_history=newList<string>();}publicvoidShowAccountHistory(){Console.WriteLine("AccountHistory:");foreach(stringhistinm_history){Console.WriteLine("\t{0}",hist);}}publicvoidAddLog(stringentry){m_history.Add(entry);}publicstaticIGeodeSerializableCreateInstance(){returnnewAccountHistory();}#regionIGeodeSerializableMemberspublicIGeodeSerializableFromData(DataInputinput){intlen=input.ReadInt32();m_history.Clear();for(inti=0;i<len;i++){m_history.Add(input.ReadUTF());}returnthis;}publicvoidToData(DataOutputoutput){output.WriteInt32(m_history.Count);foreach(stringhistinm_history){output.WriteUTF(hist);}}publicUInt32ClassId{get{return0x05;}}publicUInt32ObjectSize{get{UInt32objectSize=0;foreach(stringhistinm_history){objectSize+=(UInt32)(hist==null?0:sizeof(char)*hist.Length);}returnobjectSize;}}#endregion}publicclassTestBankAccount{publicstaticvoidMain(){//Registertheuser-definedserializabletype.Serializable.RegisterType(AccountHistory.CreateInstance);Serializable.RegisterType(BankAccountKey.CreateInstance);//Createacache.CacheFactorycacheFactory=CacheFactory.CreateCacheFactory(null);Cachecache=cacheFactory.Create();//Createaregion.
©CopyrightPivotalSoftwareInc,2013-2019 174 9.1
Page 175
RegionFactoryregionFactory=cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY);Regionregion=regionFactory.Create("BankAccounts");//PlacesomeinstancesofBankAccountcacheregion.BankAccountKeybaKey=newBankAccountKey(2309,123091);AccountHistoryahVal=newAccountHistory();ahVal.AddLog("Createdaccount");region.Put(baKey,ahVal);Console.WriteLine("PutanAccountHistoryincachekeyedwithBankAccount.");//DisplaytheBankAccountinformation.Console.WriteLine(baKey.ToString());//CallcustombehavioroninstanceofAccountHistory.ahVal.ShowAccountHistory();//Getavalueoutoftheregion.AccountHistoryhistory=region.Get(baKey)asAccountHistory;if(history!=null){Console.WriteLine("FoundAccountHistoryinthecache.");history.ShowAccountHistory();history.AddLog("debit$1,000,000.");region.Put(baKey,history);Console.WriteLine("UpdatedAccountHistoryinthecache.");}//Lookupthehistoryagain.history=region.Get(baKey)asAccountHistory;if(history!=null){Console.WriteLine("FoundAccountHistoryinthecache.");history.ShowAccountHistory();}//Closethecache.cache.Close();}}
//Example5.12UsingICacheLoadertoLoadNewIntegersintheRegionclassExampleLoaderCallback:ICacheLoader{#regionPrivatemembersprivateintm_loads=0;#endregion#regionPublicaccessorspublicintLoads{get{returnm_loads;}}#endregion}
©CopyrightPivotalSoftwareInc,2013-2019 175 9.1
Page 176
LATESTVERSION:9.1.1- RELEASENOTES
ApplicationCallbacksForregion-levelevents,anapplicationcanuse AttributesFactory.SetCache* methodstoimplementandregisterthe ICacheLoader , ICacheWriter ,and ICacheListener interfacestoperformcustomactions.
Youcanuse Region.Put forsimplecachingsituations.Formorecomplexneeds,youshouldimplementthe ICacheLoader interfaceandallowthecachetomanagethecreationandloadingofobjects.Whena Region.Get iscalledforaregionentrywithavalueofnull,the ICacheLoader.Load methodofthecacheloader(ifany)fortheregionisinvoked.AstaticCacheLoader.NetSearch methodisprovidedwhichcanbeusedby ICacheLoader implementationstolocatetherequestedkeyinthedistributedsystem.The ICacheListener interfacecanbeusedtolistentovariousregioneventsaftereventssuchascreate,update,orinvalidateofregionentrieshaveoccurred.The ICacheWriter interfaceisinvokedbeforetheeventshaveoccurred.
UsingICacheLoadertoLoadNewIntegersintheRegionThisexampledemonstratesan ICacheLoader implementationforloadingnewintegersintoaregion.
classSimpleCacheLoader<TKey,TVal>:ICacheLoader<TKey,TVal>{#regionICacheLoaderMemberspublicTValLoad(IRegion<TKey,TVal>region,TKeykey,objecthelper){Console.WriteLine("SimpleCacheLoader:ReceivedLoadeventforregion:{0}andkey:{1}",region.Name,key);returndefault(TVal);}publicvoidClose(IRegion<TKey,TVal>region){Console.WriteLine("SimpleCacheLoader:ReceivedCloseeventofregion:{0}",region.Name);}#endregion}
UsingICacheWritertoTrackCreatesandUpdatesforaRegionThisexampleimplements ICacheWriter totrackregionentry create and update events.Thisexamplejustreportstheeventstothescreen,butyoucandowhateveryouneedtodowiththeevents.
classSimpleCacheWriter<TKey,TVal>:ICacheWriter<TKey,TVal>{#regionICacheWriter<TKey,TVal>MemberspublicboolBeforeUpdate(EntryEvent<TKey,TVal>ev){Console.WriteLine("SimpleCacheWriter:ReceivedBeforeUpdateeventfor:{0}",ev.Key);returntrue;}//...handleotherentryeventsasneededpublicboolBeforeRegionClear(RegionEvent<TKey,TVal>ev){Console.WriteLine("SimpleCacheWriter:ReceivedBeforeRegionCleareventofregion:{0}",ev.Region.Name);returntrue;}//...handleotherregioneventsasneeded#endregion}
ASampleICacheListenerImplementationThisexampleimplements ICacheListener .
©CopyrightPivotalSoftwareInc,2013-2019 176 9.1
Page 177
classSimpleCacheListener<TKey,TVal>:ICacheListener<TKey,TVal>{#regionICacheListener<TKey,TVal>MemberspublicvoidAfterCreate(EntryEvent<TKey,TVal>ev){Console.WriteLine("SimpleCacheListener:ReceivedAfterCreateeventfor:{0}",ev.Key);}//...handleotherentryeventsasneededpublicvoidAfterRegionDestroy(RegionEvent<TKey,TVal>ev){Console.WriteLine("SimpleCacheListener:ReceivedAfterRegionDestroyeventofregion:{0}",ev.Region.Name);}//...handleotherregioneventsasneeded#endregion}
©CopyrightPivotalSoftwareInc,2013-2019 177 9.1
Page 178
LATESTVERSION:9.1.1- RELEASENOTES
ASimpleC#ExampleAnexampleshowshowtoconnecttoGemFire,createacacheandregion,putandgetkeysandvalues,anddisconnect.
SimpleC#Code
classBasicOperations{publicstaticvoidMain(string[]args){try{//1.CreateacacheCacheFactorycacheFactory=CacheFactory.CreateCacheFactory();Cachecache=cacheFactory.Create();
//2.CreatedefaultregionattributesusingregionfactoryRegionFactoryregionFactory=cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY);
//3.CreatearegionIRegion<int,string>region=regionFactory.Create<int,string>("exampleRegion");
//4.Putsomeentriesregion[111]="Value1";region[123]="123";
//5.Gettheentriesstringresult1=region[111];stringresult2=region[123];
//6.Closecachecache.Close();}}}
©CopyrightPivotalSoftwareInc,2013-2019 178 9.1
Page 179
LATESTVERSION:9.1.1- RELEASENOTES
Troubleshooting.NETApplicationsThe.NETFrameworkdoesnotfindmanagedDLLsusingtheconventional PATH environmentvariable.InorderforyourassemblytofindandloadamanagedDLL,itmusteitherbeloadedasaprivateassemblyusing assemblyBinding ,oritmustbeinstalledintotheGlobalAssemblyCache(GAC).
TheGACutilitymustberunoneverymachinethatrunsthe.NETcode.
Ifanassemblyattemptstoloadthe Apache.Geode.Client.dll withoutmeetingthisrequirement,a System.IO.FileNotFoundException willbethrown.
©CopyrightPivotalSoftwareInc,2013-2019 179 9.1
Page 180
LATESTVERSION:9.1.1- RELEASENOTES
ResolvingtheErrorEachcomputerwherethecommonlanguageruntimeisinstalledhasamachine-widecodecachecalledtheGlobalAssemblyCache(GAC).Theglobalassemblycachestoresassembliesspecificallydesignatedtobesharedbyseveralapplicationsonthecomputer.
Asageneralguideline,keepassemblydependenciesprivate,andlocateassembliesintheapplicationdirectoryunlesssharinganassemblyisexplicitlyrequired.Shareassembliesbyinstallingthemintotheglobalassemblycacheonlywhennecessary.
©CopyrightPivotalSoftwareInc,2013-2019 180 9.1
Page 181
LATESTVERSION:9.1.1- RELEASENOTES
UsingApache.Geode.dllAsaPrivateAssemblyToaccess Apache.Geode.dll asaprivateassembly,youneedtospecifya .config fileforyourapplication.
Thefileneedstobethesamenameasyourapplication,witha .config suffix.Forexample,the .config filefor main.exe wouldbe main.exe.config .Thetwofilesmustresideinthesamedirectory.
Followthesestepstocreatea .config file:
1. Copy %GFCPP%/docs/default.exe.config totheappropriatelocation.
2. Rename default.exe.config tothenameofyourapplication.
3. Changethe href attributeofthe CodeBase elementtopointtoyour Apache.Geode.dll file.Anyofthreepathtypes–http,relative,orabsolute–willwork.
ASample.configFileThefollowingexampleshowsanexcerptofa .config file.The PublicKeyToken valueisonlyanexample,andthecodebaseversionvalueisnotsetcorrectly.See%GFCPP%/docs/default.exe.config foranactualexampleforthisrelease.
<configuration><runtime><assemblyBindingxmlns="urn:schemas-microsoft-com:asm.v1"><dependentAssembly><assemblyIdentityname="Apache.Geode"publicKeyToken="126e6338d9f55e0c"culture="neutral"/><codeBaseversion="0.0.0.0"href="../../bin/Apache.Geode.dll"/></dependentAssembly></assemblyBinding></runtime></configuration>
Note:Ifthe .config filecontainerrors,nowarningorerrormessagesareissued.Theapplicationrunsasifno .config fileispresent.
©CopyrightPivotalSoftwareInc,2013-2019 181 9.1
Page 182
LATESTVERSION:9.1.1- RELEASENOTES
ImplementingtheSharedAssemblyFollowthesestepstoinstallthesharedassemblyintotheGlobalAssemblyCache(GAC).
1. Setthedirectory:
cd%GFCPP%
2. RuntheGACutilitytoinstall Apache.Geode.Client.dll intotheGAC.
gacutil.exe/ifApache.Geode.Client.dll
Whenyouarereadytouninstall,usethe /u switch.MoreinformationontheGACutilitycanbefoundathttp://www.msdn.com ,orbyusing gacutil.exe/? .
©CopyrightPivotalSoftwareInc,2013-2019 182 9.1
Page 183
LATESTVERSION:9.1.1- RELEASENOTES
PreservingDataAservermaypreservethedataqueuedandintendedtobesenttoaclient,suchthatthedataisnotdiscardedifcommunicationbetweentheserverandclientisdisrupted.Preservationpreventsmessageloss,whichcancauseaclienttohaveinconsistentdata.Redundantqueuesandahighavailabilityserverimplementationmayfurtherensurethatqueueddataisnotlost.
Thereisatradeoffbetweenthequantityofdatathataservermustqueueandtheamountoftimethattheservermaintainsandcontinuestoqueuedataintendedforaclientthatisnotcommunicatingwiththedistributedsystem.Clientconfigurationspecifiestheamountoftimethattheserveristocontinuequeueingmessages.Highavailabilitypermitsasecondaryservertoassumetheroleofaprimaryserverwithrespecttoqueueddataintheeventthattheprimaryservernolongerfunctions.Designationofprimaryandsecondaryservers,aswellasthenumberofredundantcopiesofthequeueareconfigurable.
HighAvailabilityforClient-ServerCommunicationTheclientprovidesreliableeventmessagingfromcacheservertoclienttopreventdatalossduringserverfailoveroperations.Highavailabilityisimplementedinthecacheserverandisconfiguredintheclient.
EnablingQueueConflationtoImproveUpdatePerformanceConflationofentryupdatemessagescanreducethenumberofupdatemessagesaclientreceives,therebyincreasingperformance.Theclientreceivesonlythemostrecentupdateforaparticularentrykey.
DurableClientMessagingConfiguretheredundancylevelforclientqueuesthatarestoredoncacheservers.Thisensuresthattheclientwillnotlosemessagesifitlosestheconnectiontoitsprimaryserver.
©CopyrightPivotalSoftwareInc,2013-2019 183 9.1
Page 184
LATESTVERSION:9.1.1- RELEASENOTES
HighAvailabilityforClient-ServerCommunicationTheclientprovidesreliableeventmessagingfromcacheservertoclienttopreventdatalossduringserverfailoveroperations.Highavailabilityisimplementedinthecacheserverandisconfiguredintheclient.
SeeserverdocumentationatConfiguringHighlyAvailableServers fordetailsaboutconfiguringaserverforhighavailability.
ConfiguringClientsforHighAvailabilityConfigurehighavailabilitybysettingthepoolattribute subscription-redundancy tothenumberofcopiesmaintained.
SendingPeriodicAcknowledgmentServersuseperiodicacknowledgmenttoreducethelikelihoodofduplicatenotifications,andtoreduceresourceusage.
©CopyrightPivotalSoftwareInc,2013-2019 184 9.1
Page 185
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringClientsforHighAvailabilityConfigurehighavailabilitybysettingthepoolattribute subscription-redundancy tothenumberofcopiestobemaintained.
Aclientmaintainsitsqueueredundancylevelatthetimeofaprimaryserverfailurebyconnectingtoadditionalsecondaryservers.
Clientscanspecifythenumberofsecondaryserverswheretheclientregistersinterestandmaintainssubscriptionchannels,inadditiontothesubscriptionchannelwiththeprimaryserver.Thesecondaryserversmaintainredundantupdatequeuesfortheclient.Iftheprimaryserverfails,asecondarybecomesaprimarytoprovideuninterruptedmessagingtotheclient.Ifpossible,anothersecondaryistheninitializedsothetotalnumberofsecondariesisnotreducedbythefailover.
SettingtheServerRedundancyLevelincache.xmlThisexamplesetsoneredundantserverasfailoverbackuptotheprimaryserver:
<cache><poolname="examplePool"subscription-enabled="true"subscription-redundancy="1"><serverhost="java_servername1"port="java_port1"/><serverhost="java_servername2"port="java_port2"/></pool><regionname="ThinClientRegion1"><region-attributesrefid="CACHING_PROXY"pool-name="examplePool"/></region></cache>
SettingtheServerRedundancyLevelProgrammaticallyYoucansettheredundancylevelprogrammatically.Thisexamplecreatesaclientcachewithtworedundantcacheserversconfiguredinadditiontotheprimaryserver.
TheserverredundancylevelcanbeconfiguredusingthepoolAPI.FormoreinformationaboutthepoolAPI,seeUsingConnectionPools.
PropertiesPtrpp=Properties::create();systemPtr=CacheFactory::createCacheFactory(pp);//Createacache.cachePtr=systemPtr->setSubscriptionEnabled(true)->addServer("localhost",24680)->addServer("localhost",24681)->addServer("localhost",24682)->setSubscriptionRedundancy(2)->create();
Whenfailovertoasecondaryserveroccurs,anewsecondaryisaddedtotheredundancyset.Ifnonewsecondaryserverisfound,theredundancylevelisnotsatisfiedbutthefailoverprocedurecompletessuccessfully.Anynewliveserverisaddedasasecondaryandinterestisregisteredonit.
©CopyrightPivotalSoftwareInc,2013-2019 185 9.1
Page 186
LATESTVERSION:9.1.1- RELEASENOTES
SendingPeriodicAcknowledgmentServersuseperiodicacknowledgmenttoreducethelikelihoodofduplicatenotifications,andtoreduceresourceusage.
Whenredundancyisenabledforhighavailabilityand redundancy-level issetto1orhigher,clientssend(andserversexpect)periodicacknowledgmentmessagesatconfigurableintervalsfornotificationstheyhavereceived.Aperiodicackisnotsentbytheclientiftherearenounacknowledgednotificationsatthetime.
Usethefollowingsystempropertiesinthe geode.properties filetoconfigureperiodicack.
notify-ack-intervalMinimumperiodbetweentwoconsecutiveacknowledgmentmessagessentfromtheclienttotheserver.Thedefaultsetting(inseconds)is10.
notify-dupcheck-lifeMinimumtimeaclientcontinuestotrackanotificationsourceforduplicateswhennonewnotificationsarrivebeforeexpiringit.Thedefaultsetting(inseconds)is300.
ThePoolAPIalsoprovidesattributestoconfigureperiodicackandduplicatemessagetrackingtimeout.See subscription-message-tracking-timeout and subscription-ack-interval inthelistofpoolattributesunderConfiguringPoolsforServersorLocators.
©CopyrightPivotalSoftwareInc,2013-2019 186 9.1
Page 187
LATESTVERSION:9.1.1- RELEASENOTES
EnablingQueueConflationtoImproveUpdatePerformanceConflationofentryupdatemessagescanreducethenumberofupdatemessagesaclientreceives,therebyincreasingperformance.Theclientreceivesonlythemostrecentupdateforaparticularentrykey.
Conflationisenabledforacacheserverregion,soallclientsreceivingupdatesforaparticularregionbenefitfromtheconflation.Toenableconflation,setthecacheserver’senable-subscription-conflation regionattributeto true .Thisregionattributeis false bydefault.
Thequeuemanagmentcodeconflatesentryupdatesaspartoftheenqueueoperation.Ifthepreviousenqueueditemforthatkeyisalsoan update operation,thequeuemanagementcoderemovesthatpreviouslyenqueuedupdate,leavingonlythelatestupdatetobesentwheneventdistributionoccurs.Forhighavailability,conflationalsooccursforanysecondaryqueues.
Onlyentry update messagesinacacheserverregionwith distributed-no-ack scopeareconflated.Regionoperationsandentryoperationsotherthanupdatesarenotconflated.
Formoreinformation,seetheserverdocumentationatConflatetheServerSubscriptionQueue .
OverridingQueueConflationPer-ClientOverrideconflationonaper-clientbasisbysettingtheconflate-eventspropertyintheclient’s geode.properties file.
Validsettingsare:
server .Usestheserversettings.
true .Conflateseverythingsenttotheclient.
false .Doesnotconflateanythingsenttotheclient.
©CopyrightPivotalSoftwareInc,2013-2019 187 9.1
Page 188
LATESTVERSION:9.1.1- RELEASENOTES
DurableClientMessagingYoucanconfiguretheredundancylevelforclientqueuesthatarestoredoncacheservers.Thisensuresthattheclientwillnotlosemessagesifitlosestheconnectiontoitsprimaryserver.
Durablemessagingallowsadisconnectedclientapplicationtorecoveritssubscribeddatawhenitreconnectstothecacheserverbecausetheservercontinuestoqueuemessagesforwhichtheclienthasregisteredinterest.
DurableClientMessagingRequirementsThemessagingqueuesusedfordurablemessagingarethesameregularmessagingqueuesusedforbasicserver-to-clientmessaging,withadditionalrequirements.
Client-SideConfiguration
SendingCacheReadyMessagestotheServerAfteradurableclientconnectsandinitializesitscache,regions,cachelisteners,andanyinterestregistration,itinvokes readyForEvents toindicatetotheserversthattheclientisreadytoreceiveanymessagesaccumulatedforit.
DisconnectingfromtheServerWhenadurableclientclosesitscacheanddisconnects,ittellstheserverswhethertomaintainitsqueues.
LifeCycleofaDurableClientThissectiondiscussesthehigh-leveloperationofadurableclientthroughinitialstartup,disconnection,andreconnection.
ImplementingCacheListenersforDurableClientsAcachelistenerfordurableclientsrequiresallcallbackmethodstobehaveproperlywhenstoredeventsarereplayed.Acachelistenerhasacallbackmethod, afterRegionLive
specificallyfordurableclientsaspects.
©CopyrightPivotalSoftwareInc,2013-2019 188 9.1
Page 189
LATESTVERSION:9.1.1- RELEASENOTES
DurableClientMessagingRequirementsThemessagingqueuesusedfordurablemessagingarethesameregularmessagingqueuesusedforbasicserver-to-clientmessaging,withadditionalrequirements.
SeetheserverdocumentationatImplementingDurableClient/ServerMessaging forrequirements,options,andfunctionalityofmessagingqueues.Ifyouareusinghighlyavailableservers,seeHighAvailabilityforClient-ServerCommunicationforadditionalrequirements.
Fordurableclientmessaging,youalsoneedthefollowing:
Durableclients.Iftheclientisdurable,theservercontinuestomaintaintheclientqueueswhentheclientdisconnects.Note:Redundancymanagementishandledbytheclient,sowhentheclientisdisconnectedfromtheservertheredundancyofclienteventsisnotmaintained.Eveniftheserversfailoneatatime,sothatrunningclientshavetimetofailoverandpicknewsecondaryservers,anofflinedurableclientcannotfailover.Asaresult,theclientlosesitsqueuedmessages.
Durableinterestregistration.Adurableclient’sinterestregistrationsspecifywhetheritsinterestinakeyisdurable.Ifitis,theserverscontinuequeuingmessagesforthatkeywhiletheclientisdisconnected.
Reconnectionconditions.Youcanprogramthedurableclienttodetectwhetherthepreviouslyregisteredsubscriptionqueueisavailableuponreconnectionanddetermineanapproximatecountofpendingeventsinthequeue.Basedontheresults,youcanthendecidewhethertoreceivetheremainingevents( Cache.readyForEvents )orclosethecacheifthenumberistoolarge.
Cachereadymessage.Whenitisreadytoreceivethestoredmessages,adurableclientmustcall Cache.readyForEvents tosendacachereadymessagetotheserver.
Disconnectkeepalivespecification.Whenadurableclientdisconnectsnormally,theclientmusttelltheserverwhethertomaintainthemessagequeueordeleteit.
Durableclientcallbackmethod.Ifyouusecachelistenersonthedurableclients,youhavetheoptiontoimplementthe afterRegionLive callbackmethod.Thiscallbackisinvokedafterthedurableclientconnectstoitsservers,whenithasreceivedallofitsstoredmessagesandreplayedtheevents.
©CopyrightPivotalSoftwareInc,2013-2019 189 9.1
Page 190
LATESTVERSION:9.1.1- RELEASENOTES
Client-SideConfigurationAlldurablemessagingconfigurationsareperformedontheclient.
ConfiguringaDurableClientThedurableclientcanbeconfiguredinthe geode.properties file,orinthe CacheFactory::set(name,value) call.
ConfiguringDurableInterestinKeysWhenadurableclientdisconnects,itsserverskeepqueuingmessagesforselectedkeys.Theclientindicateswhichkeysbyregisteringdurableinterestforthosekeys.
ConfiguringDurableClientReconnectionYoucanconfigurethedurableclienttoobtainanapproximatecountofpendingeventsupondurableclientreconnection.Basedonthereturnednumber,youcandeterminewhethertoproceedandreceivethependingeventsortoclosethecache.
©CopyrightPivotalSoftwareInc,2013-2019 190 9.1
Page 191
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringaDurableClientThedurableclientcanbeconfiguredinthe geode.properties file,orinthe CacheFactory::set(name,value) call.
DurableclientID—Indicatethattheclientisdurablebygivingita durable-client-ID .TheserversusethisIDtoidentifytheclient.Foranon-durableclient,the durable-client-ID
emptystring.TheIDcanbeanynumberthatisuniqueamongtheclientsattachedtoserversinthesamedistributedsystem.
Durabletimeout—The durable-timeout settingspecifieshowlongthisclient’sserversshouldwaitaftertheclientdisconnectsbeforeterminatingitsmessagequeue.Duringthattime,theserversconsidertheclientaliveandcontinuetoaccumulatemessagesforit.Thedefaultis300seconds.
The durable-timeout settingisatuningparameter.Whensettingthetimeout,takeintoaccountthenormalactivityofyourapplication,theaveragesizeofyourmessages,andthelevelofriskyoucanhandle.Assumingthatnomessagesarebeingremovedfromthequeue,howlongcantheapplicationrunbeforethequeuereachesthemaximummessagecount?Inaddition,howlongcanitrunbeforethequeuedmessagesconsumeallthememoryontheclienthost?Howseriousiseachofthosefailurestoyouroperation?
Toassistwithtuning,GemFirestatisticstrackmessagequeuesfordurableclientsthroughthedisconnectandreconnectcycles.
Whenthequeueisfull,itblocksfurtheroperationsthataddmessagesuntilthequeuesizedropstoanacceptablelevel.Serverconfigurationsetstheactiontotake.SeedetailsonserverconfigurationofthequeueintheserverdocumentationsectionImplementingDurableClient/ServerMessaging .
ConfiguringaDurableClientUsinggeode.propertiesThefollowingexampleshows geode.properties settingstomaketheclientdurableandsetthedurabletimeoutto200seconds.
durable-client-id=31durable-timeout=200
ConfiguringaDurableClientThroughtheAPI(C++)Thisprogrammaticexamplecreatesadurableclientusingthe CacheFactory::set(name,
value).
//Createdurableclient'spropertiesusingtheC++apiPropertiesPtrpp=Properties::create();pp->insert("durable-client-id","DurableClientId");pp->insert("durable-timeout",200);cacheFactoryPtr=CacheFactory::createCacheFactory(pp);
©CopyrightPivotalSoftwareInc,2013-2019 191 9.1
Page 192
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringDurableInterestinKeysWhenadurableclientdisconnects,itsserverskeepqueuingmessagesforselectedkeys.Theclientindicateswhichkeysbyregisteringdurableinterestforthosekeys.
Thisfine-grainedcontrolhandlestheconstraintsofqueuesizeandmemorybysavingonlythecriticalmessages.
Youstillregisterinterestforotherkeys,butnotdurableinterest.Whentheclientisconnectedtoitsservers,itreceivesmessagesforthosenon-durablekeys.Whentheclientisdisconnected,itsnon-durableinterestregistrationsaredeletedbutmessagesthatarealreadyinthequeueremainthere.
Fordurableclients,allinterestregistrationisdoneimmediatelyaftertheregionsarecreated.Thisisrequiredwhetherinterestregistrationisdurableornotdurable.AnextraregisterInterest parameterspecifiedfordurableclientsindicateswhethertheregistrationisdurable(true)ornot(false).
APIClientDurableInterestListRegistration(C++)ThefollowingprogrammaticexampleregistersdurableinterestinKey-1.Theinterestregistrationhappensimmediatelyafterregioncreationandbeforeanythingelse.
//Durableclientinterestregistrationcanbe//durable(true)ornondurable(default).VectorOfCacheableKeykeys;keys.push_back(CacheableString::create("Key-1"));regionPtr->registerKeys(keys,true);
Youusethetypicalmethodsforinterestregistrationandconfigurenotificationbysubscriptionontheserverasusual.Fordetails,seeRegisteringInterestforEntries.
Note:Changinginterestregistrationafterthedurableclientconnectsthefirsttimecancausedatainconsistencyandisnotrecommended.
Atrestart,iftheclientdoesn’tregisterdurableinterestforexactlythesamekeysasbeforethentheentriesintheinterestlistarenotcopiedfromtheserverduringtheregistration.Instead,theclientcachestartsoutemptyandentriesareaddedduringupdates.Ifnoupdatescomeinforanentry,itnevershowsupintheclientcache.
©CopyrightPivotalSoftwareInc,2013-2019 192 9.1
Page 193
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringDurableClientReconnectionYoucanconfigureadurableclienttoobtainanapproximatecountofpendingeventsupondurableclientreconnection.Basedonthereturnednumber,youcandeterminewhethertoproceedandreceivethependingeventsortoclosethecache.
Usethe getPendingEventCount (C++API)andthe PendingEventCount (.NETAPI)propertytodetectwhetherthepreviouslyregisteredsubscriptionqueueisavailableupondurableclientreconnectionandthecountofpendingeventsinthequeue.Basedonthereturnedresults,youcanthendecidewhethertoreceivetheremainingeventsorclosethecacheifthenumberistoolarge.
Forexample,considerthiscodefragmentforaclientwithonlythedefaultpoolcreated:
Poolpool=PoolManager.Find("PoolName");intpendingEvents=pool.PendingEventCount;if(pendingEvents==-2){//clientconnectedforthefirsttime…//continue}elseif(pendingEvents==-1){//clientreconnectedbutafterthetimeoutperiod…//handlepossibledataloss}else{//pendingEvents>=0//decidetoinvokereadyForEvents()orCache.close(false)/Pool.destroy()}
Foraclientwithmultiplepools:
intpendingEvents=0;intpendingEvents1=PoolManager.Find(“pool1”).PendingEventCount;pendingEvents+=(pendingEvents1>0)?pendingEvents1:0;intpendingEvents2=PoolManager.Find(“pool2”).PendingEventCount;pendingEvents+=(pendingEvents2>0)?pendingEvents2:0;//processindividualpoolcountsseparately
The getPendingEventCount methodandPendingEventCountpropertycanreturnthefollowingpossiblevalues:
Avaluerepresentingacountofeventspendingattheserver.Notethatthiscountisanapproximatevaluebasedonthetimethedurableclientpoolconnectedorreconnectedtotheserver.Anynumberofinvocationswillreturnthesamevalue.
Azerovalueiftherearenoeventspendingatserverforthisclientpool
Anegativevalueindicatesthatnoqueueisavailableattheserverfortheclientpool.
Avalueof-1indicatesthattheclientpoolhasreconnectedtotheserverafteritsdurable-client-timeoutperiodhaselapsed.Thepool’ssubscriptionqueuehasbeenremovedpossiblycausingdataloss.Avalueof-2indicatesthatthisclientpoolhasconnectedtoserverforthefirsttime.
©CopyrightPivotalSoftwareInc,2013-2019 193 9.1
Page 194
LATESTVERSION:9.1.1- RELEASENOTES
SendingCacheReadyMessagestotheServerAfteradurableclientconnectsandinitializesitscache,regions,cachelisteners,andanyinterestregistration,itinvokes readyForEvents toindicatetotheserversthattheclientisreadytoreceiveanymessagesaccumulatedforit.
DurableClientCacheReadyNotification(C++)Thefollowingexampleshowshowtocall readyForEvents .
//Sendreadyforeventmessagetoserver(onlyfordurableclients).//Serverwillsendqueuedeventstoclientafterreceivingthis.cachePtr->readyForEvents();
Tokeeptheclientfromlosingevents,donotcallthismethoduntilallregionsandlistenersarecreated.Formoreinformation,seeReconnection.
©CopyrightPivotalSoftwareInc,2013-2019 194 9.1
Page 195
LATESTVERSION:9.1.1- RELEASENOTES
DisconnectingfromtheServerWhenadurableclientclosesitscacheanddisconnects,ittellstheserverswhethertomaintainitsqueues.
Forthispurpose,usetheversionof Cache::close withtheboolean keepalive parameterset,asshowninthefollowingexample.Ifthesettingistrue,theserverskeepthedurableclient’squeuesanddurablesubscriptionsaliveforthetimeoutperiod.Inadditiontoin-memoryqueueretention,theserverscanevictthemostrecentdurableclientqueueupdatestodisktoreducememoryconsumption.
Onlytheresourcesanddatarelatedtothesessionareremoved,suchasportnumbersandnon-durablesubscriptions.Ifthesettingisfalse,theserversdothesamecleanupthattheywoulddoforanondurableclient.
//ClosetheCacheanddisconnectwithkeepalive=true.//ServerwillqueueeventsfordurableregistrationsandCQs//Whentheclientreconnects(withinatimeoutperiod)andsends//"readyForEvents()",theserverwilldeliverallstoredeventscachePtr->close(true);
©CopyrightPivotalSoftwareInc,2013-2019 195 9.1
Page 196
LATESTVERSION:9.1.1- RELEASENOTES
LifeCycleofaDurableClientThissectiondiscussesthehigh-leveloperationofadurableclientthroughinitialstartup,disconnection,andreconnection.
InitialOperationTheinitialstartupofadurableclientissimilartothestartupofanyotherclient,exceptthatitspecificallycallstheCache.readyForEvents methodwhenallregionsandlistenersontheclientarereadytoprocessmessagesfromtheserver.
DisconnectionWhiletheclientandserversaredisconnected,theiroperationvariesdependingonthecircumstances.
ReconnectionDuringinitialization,operationsontheclientcachecancomefrommultiplesources.
DurableMessageReplayWhentheprimaryserverreceivesthecachereadymessage,theserversandclientexecuteaproceduretoupdatethequeueandreplaytheeventsfromthestoredmessages.
ApplicationOperationsDuringInterestRegistrationAssoonastheclientcreatesitsregions,theapplicationhostingtheclientcanstartcacheoperations,evenwhiletheclientisstillreceivingitsinterestregistrationresponses.
©CopyrightPivotalSoftwareInc,2013-2019 196 9.1
Page 197
LATESTVERSION:9.1.1- RELEASENOTES
InitialOperationTheinitialstartupofadurableclientissimilartothestartupofanyotherclient,exceptthatitspecificallycallstheCache.readyForEvents methodwhenallregionsandlistenersontheclientarereadytoprocessmessagesfromtheserver.
SeeSendingtheCacheReadyMessagetotheServer.
©CopyrightPivotalSoftwareInc,2013-2019 197 9.1
Page 198
LATESTVERSION:9.1.1- RELEASENOTES
DisconnectionWhiletheclientandserversaredisconnected,theiroperationvariesdependingonthecircumstances.
NormaldisconnectWhenadurableclientdisconnectsnormally,the Cache.close requeststateswhethertomaintaintheclient’smessagequeueanddurablesubscriptions.Theserversstopsendingmessagestotheclientandreleaseitsconnection.SeeDisconnectingFromtheServerformoreinformation.
Ifrequested,theserversmaintainthequeuesanddurableinterestlistuntiltheclientreconnectsortimesout.Thenon-durableinterestlistisdiscarded.Theserverscontinuetoqueueupincomingmessagesforentriesonthedurableinterestlist.Allmessagesthatwereinthequeuewhentheclientdisconnectedremaininthequeue,includingmessagesforentriesonthenon-durablelist.
Iftheclientrequeststonothaveitssubscriptionsmaintained,oriftherearenodurablesubscriptions,theserversunregistertheclientandperformthesamecleanupasforanon-durableclient.
AbnormaldisconnectIftheclientcrashesorlosesitsconnectionstoallservers,theserversautomaticallymaintainitsmessagequeueanddurablesubscriptionsuntiltheclientreconnectsortimesout.
ClientdisconnectedbutoperationalIftheclientoperateswhileitisdisconnected,itgetswhatdataitcanfromthelocalcache.Sinceupdatesarenotallowed,thedatacanbecomestale.AnUnconnectedExceptionupdateisattempted.
TimingoutwhiledisconnectedTheserverstrackhowlongtokeepadurableclientqueuealivebasedonthe durable-client-timeout setting.Iftheclientremainsdisconnectedlongerthanthetimeout,theserversunregistertheclientanddothesamecleanupthatisperformedforanon-durableclient.Theserversalsologanalert.Whenatimed-outclientreconnects,theserverstreatitasanewclientmakingitsinitialconnection.
©CopyrightPivotalSoftwareInc,2013-2019 198 9.1
Page 199
LATESTVERSION:9.1.1- RELEASENOTES
ReconnectionDuringinitialization,operationsontheclientcachecancomefrommultiplesources.
Cacheoperationsbytheapplication.
Resultsreturnedbythecacheserverinresponsetotheclient’sinterestregistrations.
Callbackstriggeredbyreplayingoldeventsfromthequeue.
Theseprocedurescanactonthecacheconcurrently,andthecacheisneverblockedfromdoingoperations.
GemFirehandlestheconflictsbetweentheapplicationandinterestregistration,butyouneedtopreventthecallbackproblem.Writingcallbackmethodsthatdocacheoperationsisneverrecommended,butitisaparticularlybadideafordurableclients,asexplainedinImplementingCacheListenersforDurableClients.
Programthedurableclienttoperformthesesteps,inorder,whenitreconnects:
1. Createthecacheandregions.Thisensuresthatallcachelistenersareready.Atthispoint,theapplicationhostingtheclientcanbegincacheoperations.
2. Issueitsregisterinterestrequests.Thisallowstheclientcachetobepopulatedwiththeinitialinterestregistrationresults.Theprimaryserverrespondswiththecurrentstateofthoseentriesiftheystillexistintheserver’scache.
3. Call Cache.readyForEvents .Thistellstheserversthatallregionsandlistenersontheclientarenowreadytoprocessmessagesfromtheservers.Thecachereadymessagetriggersthequeuedmessagereplayprocessontheprimaryserver.
Foranexamplethatdemonstrates Cache.readyForEvents ,seeSendingtheCacheReadyMessagetotheServer.
Thisfigureshowstheconcurrentproceduresthatoccurduringtheinitializationprocess.Theapplicationbeginsoperationsimmediatelyontheclient(step1),whiletheclient’scachereadymessage(alsostep1)triggersaseriesofqueueoperationsonthecacheservers(startingwithstep2ontheprimaryserver).Atthesametime,theclientregistersinterest(step2ontheclient)andreceivesaresponsefromtheserver.
MessageB2appliestoanentryinRegionA,sothecachelistenerhandlesB2’sevent.BecauseB2comesbeforethemarker,theclientdoesnotapplytheupdatetothecache.
Figure:InitializationofaReconnectedDurableClient
Onlyoneregionisshownforsimplicity,butthemessagesinthequeuecouldapplytomultipleregions.Also,thefigureomitstheconcurrentcacheupdatesontheservers,whichwouldnormallybeaddingmoremessagestotheclient’smessagequeue.
©CopyrightPivotalSoftwareInc,2013-2019 199 9.1
Page 200
LATESTVERSION:9.1.1- RELEASENOTES
DurableMessageReplayWhentheprimaryserverreceivesthecachereadymessage,theserversandclientexecuteaproceduretoupdatethequeueandreplaytheeventsfromthestoredmessages.
Durablemessagereplayproceedsasfollows.Toavoidoverwritingcurrententrieswitholddata,theclientdoesnotapplytheupdatestoitscache.
1. TheserverfindsthequeueforthisdurableclientIDandupdatesitsinformation,includingtheclient’ssocketandremoteports.Iftheclienthastimedoutwhileitwasdisconnected,itsqueuesaregoneandtheserverthentreatsitasanewclient.SeeInitialOperation.
2. Allserversthathaveaqueueforthisclientplaceamarkerinthequeue.Messagesinthequeuebeforethemarkerareconsideredtohavecomewhiletheclientwasdisconnected.Messagesafterthemarkerarehandlednormally.
3. Thecacheserversendsthequeuedmessagestotheclient.Thisincludesanymessagesthatwereevictedtodisk.
4. Theclientreceivesthemessagesbutdoesnotapplytheupdatestoitscache.Ifcachelistenersareinstalled,theyhandletheevents.Forimplications,seeImplementingCacheListenersforDurableClients.
5. Theclientreceivesthemarkermessageindicatingthatallpasteventshavebeenplayedback.
6. Thecacheserversendsthecurrentlistofliveregions.
7. Ineachliveregionontheclient,themarkereventtriggersthe afterRegionLive callback.Afterthecallback,theclientbeginsnormalprocessingofeventsfromtheserverandappliestheupdatestoitscache.
Evenwhenanewclientstartsupforthefirsttime,thecachereadymarkersareinsertedinthequeues.Ifmessagesstartcomingintothenewqueuesbeforetheserversinsertthemarker,thosemessagesareconsideredashavinghappenedwhiletheclientwasdisconnected,andtheireventsarereplayedthesameasinthereconnectcase.
©CopyrightPivotalSoftwareInc,2013-2019 200 9.1
Page 201
LATESTVERSION:9.1.1- RELEASENOTES
ApplicationOperationsDuringInterestRegistrationAssoonastheclientcreatesitsregions,theapplicationhostingtheclientcanstartcacheoperations,evenwhiletheclientisstillreceivingitsinterestregistrationresponses.
Inthatcase,applicationoperationstakeprecedenceoverinterestregistrationresponses.
Whenaddingregisterinterestresponsestothecache,thefollowingrulesareapplied:
Iftheentryalreadyexistsinthecachewithavalidvalue,itisnotupdated.
Iftheentryisinvalidandtheregisterinterestresponseisvalid,thevalidvalueisputintothecache.
Ifanentryismarkeddestroyed,itisnotupdated.Destroyedentriesareremovedfromthesystemaftertheregisterinterestresponseiscompleted.
Iftheinterestresponsedoesnotcontainanyresultsbecauseallofthosekeysareabsentfromtheserver’scache,theclient’scachecanstartoutempty.Ifthequeuecontainsoldmessagesrelatedtothosekeys,theeventsarestillreplayedintheclient’scache.
©CopyrightPivotalSoftwareInc,2013-2019 201 9.1
Page 202
LATESTVERSION:9.1.1- RELEASENOTES
ImplementingCacheListenersforDurableClientsAcachelistenerfordurableclientsrequiresallcallbackmethodstobehaveproperlywhenstoredeventsarereplayed.Acachelistenerhasacallbackmethod, afterRegionLivefordurableclientsaspects.
Forgeneralinstructionsonimplementingacachelistener,seeCacheListener.
WritingCallbacksforUseWithDurableMessagingDurableclientsrequirespecialattentiontocachecallbacksgeneratedbythecachelistener.Duringtheinitializationwindowwhenareconnectingclienthasafunctioningcachebutisstillreceivingthestoredmessagesfromthequeue,theclientcanreplayeventsthatarelongpast.Theseeventsarenotappliedtothecache,buttheyaresenttothecachelistener.Ifthelistener’scallbacksinvokedbytheseeventsmakechangestothecache,thatcouldconflictwithcurrentoperationsandcreatedatainconsistencies.
Consequently,youneedtokeepyourcallbackimplementationslightweightandnotdoanythinginthecachethatcouldproduceincorrectresultsduringthiswindow.FordetailsonimplementingcallbacksforGemFireeventhandlers,seeImplementingCacheEventHandlers .
ImplementingtheafterRegionLiveMethodIfyouareusingcachelisteners,youcanimplementthe afterRegionLive callbackmethodprovidedfordurableclients.Thiscallbackisinvokedwhentheclienthasreceivedalltheoldmessagesthatwerestoredinitsqueuewhileitwasdisconnected.Implementingthismethodenablesyoutodoapplication-specificoperationswhentheclienthasreplayedalloftheseoldevents.
Ifyoudonotwishtousethiscallback,andyourlistenerisaninstanceof CacheListener (nota CacheListenerAdapter ),youmustimplement afterRegionLive asanon-operationalmethod.
©CopyrightPivotalSoftwareInc,2013-2019 202 9.1
Page 203
LATESTVERSION:9.1.1- RELEASENOTES
SecuritySecuritydescribeshowtoimplementthesecurityframeworkfortheGemFirenativeclient,includingauthentication,authorization,encryption,andSSLclient/servercommunication.
ThesecurityframeworkauthenticatesclientsthatattempttoconnecttoaGemFirecacheserverandauthorizesclientcacheoperations.Youcanalsoconfigureitforclientauthenticationofservers,andyoucanpluginyourownimplementationsforauthenticationandauthorization.
AuthenticationAclientisauthenticatedwhenitconnects,withvalidcredentials,toaGemFirecacheserverthatisconfiguredwiththeclientAuthenticator callback.
EncryptedAuthenticationYoucansetupencryptedauthenticationusingDiffe-HellmanorthesamplePKCSimplementation.
ClientAuthorizationUsingaprovidedcallbackthatimplementsthe AccessControl interface,youcanconfigureeachservertoauthorizesomeorallcacheoperations.
Security-RelatedSystemProperties(geode.properties)Thetabledescribesthesecurity-relatedsystempropertiesinthe geode.properties filefornativeclientauthenticationandauthorization.
SSLClient/ServerCommunicationThissectiondescribeshowtoconfigureOpenSSL;implementSSL-basedcommunicationbetweenyourclientsandservers;andrunclientsandserverswithSSLenabled.
©CopyrightPivotalSoftwareInc,2013-2019 203 9.1
Page 204
LATESTVERSION:9.1.1- RELEASENOTES
AuthenticationAclientisauthenticatedwhenitconnects,withvalidcredentials,toaGemFirecacheserverthatisconfiguredwiththeclientAuthenticator callback.
Oncetheclientisauthenticated,theserverassignstheclientauniqueIDandprincipal,usedtoauthorizeoperations.Theclientmusttrustallcacheserversintheserversystemasitmayconnecttoanyoneofthem.Forinformationonconfiguringclient/server,seeClient/ServerConfiguration .
ProcessandMultiuserAuthenticationClientconnectionscanbeauthenticatedattwolevels,processandmultiuser.
ConfiguringCredentialsforAuthenticationThenativeclientusessystempropertiestoacquirevalidcredentialsforauthenticationbytheserver.Youdefinethesepropertiesinthegeode.properties file,whichthenativeclientaccessesduringstartup.
ConfiguringAuthenticationbytheCacheServerWhenthecacheserverreceivesclientcredentialsduringthehandshakeoperation,theserverauthenticatestheclientwiththecallbackconfiguredinthe security-client-authenticator
systemproperty.Thehandshakesucceedsorfailsdependingontheresultsoftheauthenticationprocess.
ServerAuthenticationErrors
CreatingMultipleSecureUserConnectionsTocreatemultiple,secureconnectionstoyourserversfromasingleclient,sotheclientcanservicedifferentusertypes,youcreateanauthenticatedRegionService foreachuser.
UsinganLDAPServerforClientAuthenticationAnLDAPservercanbeusedbyaGemFirecacheserverusingthesampleLDAPimplementationprovidedwiththeGemFireserver.
©CopyrightPivotalSoftwareInc,2013-2019 204 9.1
Page 205
LATESTVERSION:9.1.1- RELEASENOTES
ProcessandMultiuserAuthenticationClientconnectionscanbeauthenticatedattwolevels,processandmultiuser.
Process.Eachpoolcreatesaconfiguredminimumnumberofconnectionsacrosstheservergroup.Thepoolaccessestheleast-loadedserverforeachcacheoperation.Process-levelconnectionsrepresenttheoverallclientprocessandarethestandardwayaclientaccessestheservercache.
Multi-user.Eachuser/poolpaircreatesaconnectiontooneserverandthenstickswithitforoperations.Iftheserverisunabletorespondtoarequest,thepoolselectsanewonefortheuser.Typically,applicationserversorwebserversthatactasclientstoGemFireserversmakemulti-userconnections.Multi-userallowsasingleapplicationorwebserverprocesstoservicealargenumberofuserswithvariedaccesspermissions.
Bydefault,serverpoolsuseprocess-levelauthentication.Enablemulti-userauthenticationbysettingapool’s multi-user-secure-mode-enabled attributeto true .
CredentialscanbesentinencryptedformusingtheDiffie-Hellmankeyexchangealgorithm.SeeEncryptCredentialswithDiffe-Hellmanformoreinformation.
©CopyrightPivotalSoftwareInc,2013-2019 205 9.1
Page 206
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringCredentialsforAuthenticationTheclientusessystempropertiestoacquirevalidcredentialsforauthenticationbytheserver.Youdefinethesepropertiesinthegeode.properties file,whichtheclientaccessesduringstartup.
security-client-auth-factorySystempropertyforthefactoryfunctionoftheclassimplementingthe AuthInitialize interface( IAuthInitialize in.NET).The.NETclientscanloadbothC++and.NETimplementations.For.NETimplementations,thispropertyisthefullyqualifiednameofthestaticfactoryfunction(includingthenamespaceandclass).
security-client-auth-librarySystempropertyforthelibrarywherethefactorymethodsreside.Thelibraryisloadedexplicitlyandthefactoryfunctionsareinvokeddynamically,returninganobjectoftheclassimplementingthe AuthInitialize interface.
Otherimplementationsofthe AuthInitialize interfacemayberequiredtobuildcredentialsusingpropertiesthatarealsopassedassystemproperties.Thesepropertiesalsostartwiththesecurity-prefix.Forexample,thePKCSimplementationrequiresanaliasnameandthecorrespondingkeystorepath,whicharespecifiedas security-alias and security-keystorepathrespectively.Similarly, UserPasswordAuthInit requiresausernamespecifiedin security-username ,andthecorrespondingpasswordisspecifiedinthe security-password systemproperty.
The getCredentials functionforthe AuthInitialize interfaceiscalledtoobtainthecredentials.Allsystempropertiesstartingwithsecurity-arepassedtothiscallbackasthefirstargumenttothe getCredentials function,usingthisprototype:
PropertiesPtrgetCredentials(PropertiesPtr&securityprops,constchar*server);
ImplementingtheFactoryMethodforAuthentication(C++and.NET)ThefollowingexamplesshowhowtoimplementthefactorymethodinbothC++and.NET.C++Implementation
LIBEXPAuthInitialize*createPKCSAuthInitInstance(){returnnewPKCSAuthInit();}
.NETImplementation
publicstaticIAuthInitializeCreate(){returnnewUserPasswordAuthInit();}
Implementationsofthefactorymethodareuser-provided.Credentialsintheformofpropertiesreturnedbythisfunctionaresentbytheclienttotheserverforauthenticationduringtheclient’shandshakeprocesswiththeserver.
Theclientinstallationprovidessamplesecurityimplementationsinits templates/security folder.
AcquiringCredentialsProgrammatically(C++and.NET)ThisexampleshowsaC++clientconnectingwithcredentials.
PropertiesPtrsecProp=Properties::create();secProp->insert("security-client-auth-factory","createPKCSAuthInitInstance");secProp->insert("security-client-auth-library","securityImpl");secProp->insert("security-keystorepath","keystore/geode.keystore");secProp->insert("security-alias","geode");secProp->insert("security-keystorepass","geodepass");CacheFactoryPtrcacheFactoryPtr=CacheFactory::createCacheFactory(secProp);
Thisexampleshowsa.NETclient.
©CopyrightPivotalSoftwareInc,2013-2019 206 9.1
Page 207
PropertiessecProp=Properties.Create();secProp.Insert("security-client-auth-factory","Apache.Geode.Templates.Cache.Security.UserPasswordAuthInit.Create");secProp.Insert("security-client-auth-library","securityImpl");secProp.Insert("security-username","geode");secProp.Insert("security-password","geodePass);
©CopyrightPivotalSoftwareInc,2013-2019 207 9.1
Page 208
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringAuthenticationbytheCacheServerWhenthecacheserverreceivesclientcredentialsduringthehandshakeoperation,theserverauthenticatestheclientwiththecallbackconfiguredinthe security-client-authenticatorproperty.Thehandshakesucceedsorfailsdependingontheresultsoftheauthenticationprocess.
Hereisanexampleofhowyoucouldconfigure security-client-authenticator inthe geode.properties file:
security-client-authenticator=templates.security.PKCSAuthenticator.create
Intheprecedingconfigurationsample, PKCSAuthenticator isthecallbackclassimplementingthe Authenticator interfaceand create isitsfactorymethod.
Thefollowingexampleshowsanimplementationofthestatic create method:
publicstaticAuthenticatorcreate(){returnnewPKCSAuthenticator();}
©CopyrightPivotalSoftwareInc,2013-2019 208 9.1
Page 209
LATESTVERSION:9.1.1- RELEASENOTES
ServerAuthenticationErrorsAn AuthenticationRequiredException isthrownwhentheserverisconfiguredwithsecurityandtheclientdoesnotpresentitscredentialswhileattemptingtoconnect.Thiscanoccurifthesecurityclient-auth-factory and security-client-auth-library propertiesarenotconfiguredontheclient.
©CopyrightPivotalSoftwareInc,2013-2019 209 9.1
Page 210
LATESTVERSION:9.1.1- RELEASENOTES
CreatingMultipleSecureUserConnectionsTocreatemultiple,secureconnectionstoyourserversfromasingleclient,sotheclientcanservicedifferentusertypes,youcreateanauthenticatedRegionService foreachuser.
Typically,aGemFireclientembeddedinanapplicationserversupportsdatarequestsfrommanyusers.Eachusercanbeauthorizedtoaccessasubsetofdataontheservers.Forexample,customerusersareallowedtoseeandupdateonlytheirownordersandshipments.
TheauthenticatedusersallaccessthesameCachethroughinstancesofthe RegionService interface.SeeRegionService.
Toimplementmultipleuserconnectionsinyourclientcache,createyourCacheasusual,withtheseadditions:
1. Configureyourclient’sserverpoolformultiplesecureuserauthentication.Example:
<poolname="serverPool"multiuser-authentication="true"><locatorhost="host1"port="44444"/></pool>
Thisenablesaccessthroughthepoolforthe RegionService instancesanddisablesitfortheCacheinstance.
2. Afteryoucreateyourcache,foreachuser,callyourCacheinstance createAuthenticatedView method,providingtheuser’sparticularcredentials.Thesearecreatemethodcallsfortwousers:
PropertiesPtrcredentials1=Properties::create();credentials1->insert("security-username","root1");credentials1->insert("security-password","root1");RegionServicePtruserCache1=cachePtr->createAuthenticatedView(credentials1);
PropertiesPtrcredentials2=Properties::create();credentials2->insert("security-username","root2");credentials2->insert("security-password","root2");RegionServicePtruserCache2=cachePtr->createAuthenticatedView(credentials2);
Foreachuser,doallofyourcachingandregionworkthroughtheassignedregionservicepointer.Usetheregionservicetogetyourregions,andthequeryservice,ifyouneedthat,andthendoyourworkwiththem.Accesstotheservercachewillbegovernedbytheserver’sconfiguredauthorizationrulesforeachindividualuser.
3. Tocloseyourcache,closetheCacheinstance.
RequirementsandCaveatsforRegionService
©CopyrightPivotalSoftwareInc,2013-2019 210 9.1
Page 211
LATESTVERSION:9.1.1- RELEASENOTES
RequirementsandCaveatsforRegionServiceForeachregion,youcanperformoperationsthroughthe Cache instanceorthe RegionService instances,butnotboth.
Note:Throughthe Cache youcancreatearegionthatusesapoolconfiguredformulti-userauthentication,thenaccessanddoworkontheregionusingyour RegionService
Touse RegionService :
ConfigureregionsasEMPTY.Dependingonyourdataaccessrequirements,thisconfigurationmightaffectperformance,becausetheclientgoestotheserverforevery
IfyouarerunningdurableCQsthroughtheregionservices,stopandstarttheofflineeventstoragefortheclientasawhole.Theservermanagesonequeuefortheentireclientprocess,soyouneedtorequestthestopandstartofdurableclientqueue(CQ)eventmessagingforthecacheasawhole,throughtheClientCacheinstance.IfyouclosedtheRegionService instances,eventprocessingwouldstop,buttheeventsfromtheserverwouldcontinue,andwouldbelost.Stopwith:
cachePtr->close(true);
Startupagaininthisorder:
1. Createthecache.2. Createallregionserviceinstances.InitializeCQlisteners.3. Callthecache readyForEvents method.
©CopyrightPivotalSoftwareInc,2013-2019 211 9.1
Page 212
LATESTVERSION:9.1.1- RELEASENOTES
UsinganLDAPServerforClientAuthenticationAnLDAPservercanbeusedbyaGemFirecacheserverusingthesampleLDAPimplementationprovidedintheserverdistribution.
SeeSecurity intheservermanualtoverifyauthenticationcredentialsforclientsattemptingtoconnecttothecacheserversandsendingusernameandpasswordsusingthesampleUserPasswordscheme.
Note:Theusernameandpasswordwiththissampleimplementationissentoutinplaintext.Forbettersecurity,eitherturnoncredentialencryptionusingDiffie-Hellmankeyexchange,oruseaschemelikePKCS.
Whenaclientinitiatesaconnectiontoacacheserver,theclientsubmitsitscredentialstotheserverandtheserversubmitsthosecredentialstotheLDAPserver.Tobeauthenticated,thecredentialsfortheclientneedtomatchoneofthevalidentriesintheLDAPserver.Thecredentialscanconsistoftheentrynameandthecorrespondingpassword.IfthesubmittedcredentialsresultinaconnectiontotheLDAPserverbecausethecredentialsmatchtheappropriateLDAPentries,thentheclientisauthenticatedandgrantedaconnectiontotheserver.IftheserverfailstoconnecttotheLDAPserverwiththesuppliedcredentialsthenan AuthenticationFailedException issenttotheclientanditsconnectionwiththecacheserverisclosed.
ConfigurationSettings
Inthe geode.properties filefortheclient,specifythe UserPasswordAuthInit callback,theusername,andthepassword,likethis:
security-client-auth-library=securityImplsecurity-client-auth-factory=createUserPasswordAuthInitInstancesecurity-username=<username>security-password=<password>
ForserversidesettingsandLDAPserverconfiguration,seetheserver’ssecuritydocumentation.
©CopyrightPivotalSoftwareInc,2013-2019 212 9.1
Page 213
LATESTVERSION:9.1.1- RELEASENOTES
EncryptedAuthenticationYoucansetupencryptedauthenticationusingDiffe-HellmanorthesamplePKCSimplementation.
EncryptCredentialswithDiffe-HellmanForsecuretransmissionofsensitivecredentialslikepasswords,encryptcredentialsusingtheDiffie-Hellmankeyexchangealgorithm.WithDiffie-Hellmanenabled,youcanhaveyourclientauthenticateitsservers.
UsingPKCSforEncryptedAuthenticationThissectiondiscussestheconceptsandconfigurationsforthesampleUserPasswordandPKCSimplementations.Descriptionsoftheirinterfaces,classes,andmethodsareavailableintheAPI.
©CopyrightPivotalSoftwareInc,2013-2019 213 9.1
Page 214
LATESTVERSION:9.1.1- RELEASENOTES
EncryptCredentialswithDiffe-HellmanForsecuretransmissionofsensitivecredentialssuchaspasswords,encryptcredentialsusingtheDiffie-Hellmankeyexchangealgorithm.WithDiffie-Hellmanenabled,youcanhaveyourclientauthenticateitsservers.
EnablingDiffe-HellmanSetthe security-client-dhalgo systempropertyinthe geode.properties filetothepasswordforthepublickeyfilestoreontheclient(thenameofavalidsymmetrickeyciphersupportedbytheJDK).
Valid security-client-dhalgo propertyvaluesare DESede , AES ,and Blowfish ,whichenabletheDiffie-Hellmanalgorithmwiththespecifiedciphertoencryptthecredentials.
Forthe AES and Blowfish algorithms,optionallyspecifythekeysizeforthe security-client-dhalgo property.Validkeysizesettingsforthe AES algorithmare AES:128 , AES:192AES:256 .Thecolonseparatesthealgorithmnameandthekeysize.Forthe Blowfish algorithm,keysizesfrom128to448bitsaresupported.Forexample:
security-client-dhalgo=Blowfish:128
For AES algorithms,youmayneedJavaCryptographyExtension(JCE)UnlimitedStrengthJurisdictionPolicyFilesfromSunorequivalentforyourJDK.
AddingsettingsforDiffie-Hellmanonclientsalsoenableschallengeresponsefromservertoclientinadditiontoencryptionofcredentialsusingtheexchangedkeytoavoidreplayattacksfromclientstoservers.Clientscanalsoenableauthenticationofservers,withchallenge-responsefromclienttoservertoavoidserver-sidereplayattacks.
ClientAuthenticationofServerWithDiffie-Hellmanenabled,youcanhaveyourclientauthenticateitsservers.
1. Generatea .pem fileforeachpkcs12keystore:
a. Enterthiscommandfromapkcs12fileorapkcskeystore:
user@host:~>opensslpkcs12-nokeys-in<keystore/pkcs12file>-out<outputfilename.pem>
b. Concatenatethegenerated.pemfilesintoasingle.pemfile.Youwillusethisfilenameinthenextstep.
2. Inthe geode.properties file:
a. Set security-client-kspath tothefilenameofthe .pem filepasswordforthepublickeyfilestoreontheclient.b. Set security-client-kspasswd tothepasswordforthepublickeyfilestoreontheclient.
©CopyrightPivotalSoftwareInc,2013-2019 214 9.1
Page 215
LATESTVERSION:9.1.1- RELEASENOTES
UsingPKCSforEncryptedAuthenticationThissectiondiscussestheconceptsandconfigurationsforthesampleUserPasswordandPKCSimplementations.Descriptionsoftheirinterfaces,classes,andmethodsareavailableintheAPI.
Note:Nativeclientsamplesareprovidedinsourceformonlyinthe“templates”directorywithintheproductdirectory.
WithPKCS,clientssendencryptedauthenticationcredentialsintheformofstandardPKCSsignaturestoaGemFirecacheserverwhentheyconnecttotheserver.Thecredentialsconsistofthealiasnameanddigitalsignaturecreatedusingtheprivatekeythatisretrievedfromtheprovidedkeystore.Theserverusesacorrespondingpublickeytodecryptthecredentials.Ifdecryptionissuccessfulthentheclientisauthenticatedanditconnectstothecacheserver.Forunsuccessfuldecryption,theserversendsan AuthenticationFailedException totheclient,andtheclientconnectiontothecacheserverisclosed.
Whenclientsrequireauthenticationtoconnecttoacacheserver,theyusethe PKCSAuthInit classimplementingthe AuthInitialize interfacetoobtaintheircredentials.ForthePKCSsampleprovidedbyGemFire,thecredentialsconsistofanaliasandanencryptedbytearray.TheprivatekeyisobtainedfromthePKCS#12keystorefile.Toaccomplishthis,getsthealiasretrievedfromthe security-alias property,andthekeystorepathfromthe security-keystorepath property. PKCSAuthInit alsogetsthepasswordforthepassword-protectedkeystorefilefromthe security-keystorepass propertysothekeystorecanbeopened.
ThesecurityImplLibrary
TousethePKCSsampleimplementation,youneedtobuildOpenSSLandthenbuildthesecurityImpllibrary.Inthegeode.properties filefortheclient,specifythe PKCSAuthInitthekeystorepath,thesecurityalias,andthekeystorepassword,likethis:
security-client-auth-library=securityImplsecurity-client-auth-factory=createPKCSAuthInitInstancesecurity-keystorepath=<PKCS#12keystorepath>security-alias=<alias>security-keystorepass=<keystorepassword>
ForserversidesettingsandPKCSconfiguration,seetheserver’ssecuritydocumentation.
©CopyrightPivotalSoftwareInc,2013-2019 215 9.1
Page 216
LATESTVERSION:9.1.1- RELEASENOTES
ClientAuthorizationUsingaprovidedcallbackthatimplementsthe AccessControl interface,youcanconfigureeachservertoauthorizesomeorallcacheoperations.
Thecallbackcanalsomodifyorevendisallowthedatabeingprovidedbytheclientintheoperation,suchasaputora putAll operation.Thecallbackcanalsoregisteritselfasapost-processingfilterthatispassedoperationresultslike get , getAll ,and query .
ConfiguringClientAuthorizationYoucanconfigureauthorizationonaper-clientbasisforvariouscacheoperationssuchascreate,get,put,queryinvalidations,interestregistration,andregiondestroys.Ontheserverside,the securityclient-accessor systempropertyintheserver’s geode.properties filespecifiestheauthorizationcallback.
Post-OperativeAuthorizationAuthorizationinthepost-operationphaseoccursontheserveraftertheoperationiscompleteandbeforetheresultsaresenttotheclient.
DeterminingPre-orPost-OperationAuthorizationThe OperationContext objectthatispassedtothe authorizeOperation methodofthecallbackasthesecondargumentprovidesan isPostOperation methodthatreturnstruewhenthecallbackisinvokedinthepost-operationphase.
©CopyrightPivotalSoftwareInc,2013-2019 216 9.1
Page 217
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringClientAuthorizationYoucanconfigureauthorizationonaper-clientbasisforvariouscacheoperationssuchascreate,get,put,queryinvalidations,interestregistration,andregiondestroys.Ontheserverside,the securityclient-accessor systempropertyintheserver’s gemfire.properties filespecifiestheauthorizationcallback.
Forexample:
security-client-accessor=templates.security.XmlAuthorization.create
Inthissystempropertysetting, XmlAuthorization isthecallbackclassthatimplementsthe AccessControl interface.The XmlAuthorization sampleimplementationprovidedwithGeodeexpectsanXMLfilethatdefinesauthorizationprivilegesfortheclients.Fordetailsofthissampleimplementationandthe AccessControl interface,seetheAuthorizationExample
©CopyrightPivotalSoftwareInc,2013-2019 217 9.1
Page 218
LATESTVERSION:9.1.1- RELEASENOTES
Post-OperativeAuthorizationAuthorizationinthepost-operationphaseoccursontheserveraftertheoperationiscompleteandbeforetheresultsaresenttotheclient.
Thecallbackcanmodifytheresultsofcertainoperations,suchas query , get and keySet ,orevencompletelydisallowtheoperation.Forexample,apost-operationcallbackforaqueryoperationcanfilteroutsensitivedataordatathattheclientshouldnotreceive,orevencompletelyfailtheoperation.
The security-client-accessor-pp systempropertyintheserver’s gemfire.properties filespecifiesthecallbacktoinvokeinthepost-operationphase.Forexample:
security-client-accessor-pp=templates.security.XmlAuthorization.create
©CopyrightPivotalSoftwareInc,2013-2019 218 9.1
Page 219
LATESTVERSION:9.1.1- RELEASENOTES
DeterminingPre-orPost-OperationAuthorizationThe OperationContext objectthatispassedtothe authorizeOperation methodofthecallbackasthesecondargumentprovidesan isPostOperation methodthatreturnstruewhenthecallbackisinvokedinthepost-operationphase.
Forexample:
boolauthorizeOperation(Regionregion,OperationContextcontext){if(context.isPostOperation()){//it'sapost-operation}else{//it'sapre-operation}}
Ifanauthorizationfailureoccursinapre-operationorpost-operationcallbackontheserver,theoperationthrowsa NotAuthorizedException ontheclient.
Formoreinformation,seeAuthorization .
©CopyrightPivotalSoftwareInc,2013-2019 219 9.1
Page 220
LATESTVERSION:9.1.1- RELEASENOTES
Security-RelatedSystemProperties(gemfire.properties)Thetabledescribesthesecurity-relatedsystempropertiesinthe gemfire.properties filefornativeclientauthenticationandauthorization.
Table1.SystemPropertiesforClientAuthenticationandAuthorization
security-client-auth-factory Setsthekeyforthe AuthInitialize factoryfunction.
security-client-auth-library Registersthepathtothe securityImpl.dll library.
security-client-dhalgo ReturnstheDiffie-Hellmansecretkeycipheralgorithm.
security-client-kspathPathtoa.pemfile,whichcontainsthepubliccertificatesforallGemFirecacheserverstowhichtheclientcanconnectthroughspecifiedendpoints.
security-client-kspasswd Passwordforthepublickeyfilestoreontheclient.
security-keystorepath Pathtothepublickeystore.
security-alias Aliasnameforthekeyinthekeystore.
security-keystorepass Setsthepasswordforthepassword-protectedkeystore.
ssl-cipher ListofSSLciphersintheformofacomma-separatedlist(default“any”).
ssl-enabled-components
EnablesSSL-basedclient/servercommunicationforthespecifiedcomponents,givenasacomma-separatedlist.Validcomponentsare`all`,`cluster`,`gateway`,`jmx`,`locator`,`server`,`web`.
ssl-keystoreNameofthe.PEMkeystorefile,containingtheclient’sprivatekey.Notsetbydefault.Requiredif ssl-enabled-components isnon-empty.
ssl-keystore-password SetsthepasswordfortheprivatekeyPEMfileforSSL.
ssl-truststoreNameofthe.PEMtruststorefile,containingtheservers’publiccertificate.Notsetbydefault.Requiredif ssl-enabled-components isnon-empty.
©CopyrightPivotalSoftwareInc,2013-2019 220 9.1
Page 221
LATESTVERSION:9.1.1- RELEASENOTES
SSLClient/ServerCommunicationThissectiondescribeshowtoconfigureOpenSSL,implementSSL-basedcommunicationbetweenyourclientsandservers,andrunclientsandserverswithSSLenabled.
SetUpOpenSSL
Theopen-sourceOpenSSLtoolkitprovidesafull-strengthgeneralpurposecryptographylibrarytooperatealongwiththePKCSsampleimplementationforencryptedauthenticationofnativeclientcredentials.
DownloadandinstallOpenSSL1.0.2foryourspecificoperatingsystem.ForWindowsplatforms,youcanuseeithertheregularorthe“Light”version.
NoteforWindowsusers:IfyouuseCygwin,donotusetheOpenSSLlibrarythatcomeswithCygwin,whichisbuiltwith cygwin.dll asadependency.Instead,downloadafreshcopyfromOpenSSL.
Step1.CreatekeystoresTheGemFireserverrequireskeysandkeystoresintheJavaKeyStore(JKS)formatwhilethenativeclientrequiresthemintheclearPEMformat.Thusyouneedtobeabletogenerateprivate/publickeypairsineitherformatandconvertbetweenthetwousingthe keytool utilityandthe openssl command.
Therearepublicthirdpartyfreetoolsandsourcecodeavailabletodownloadsuchasthe“KeyToolIUI”tool.
Step2.ConfigureenvironmentvariablesConfigureyoursystemenvironmenttobuildandrunOpenSSLbyaddingtheappropriateexecutableandlibrarydirectoriestoyourpaths.Forexample,forBourneandKornshells(sh,ksh,bash),environmentsetupwouldlooksomethinglikethis: %LD_LIBRARY_PATH=$LD_LIBRARY_PATH:client-install-dir/lib:client-install-dir/ssl_libs:openssl-install-dir/lib
%exportLD_LIBRARY_PATH%CLASSPATH=server-install-dir/lib/securityImpl.jar:$CLASSPATH
where:
client-install-diristhedirectoryinwhichyouinstalledyourclient.
openssl-install-diristhedirectoryinwhichyouinstalledOpenSSL.
server-install-diristhedirectoryinwhichyouinstalledyourserver.
ForWindows,environmentsetupmightresemblethis: >setPATH=jdk-or-jre-path\bin;client-install-dir\bin;client-install-dir\ssl_libs;openssl-install-dir\bin;%PATH%>setCLASSPATH=server-installdir\lib\securityImpl.jar;%CLASSPATH%
wherejdk-or-jre-pathisthedirectoryinwhichJavaisinstalled.
Step3.EnableSSLontheserverandontheclient1. Ontheserver,enableSSLforthe locator and server components,astheSSL-enabledclientmustbeabletocommunicatewithbothlocatorandservercomponents.FordetailsontheSSLpropertiesavailableontheserver,see“Managing>Security>SSL>ConfiguringSSL”intheGemFireUser’sGuide .
2. Ontheclient,set ssl-enabled to true .
3. Ontheclient,set ssl-keystore and ssl-truststore topointtoyourkeystorefiles.Pathstothekeystoreandtruststorearelocaltotheclient.SeeSecurity-RelatedSystemPropertiesdescriptionoftheseproperties.
StartingandstoppingtheclientandserverwithSSLinplace
Beforeyoustartandstoptheclientandserver,makesureyouconfigurethenativeclientwiththeSSLpropertiesasdescribedandwiththeserversorlocatorsspecifiedasusual.
Specifically,ensurethat:
OpenSSLandACE_SSL DLL slocationsareintherightenvironmentvariablesforyoursystem: PATH forWindows,and LD_LIBRARY_PATH forUnix.
Youhavegeneratedthekeysandkeystores.
Youhavesetthesystemproperties.
©CopyrightPivotalSoftwareInc,2013-2019 221 9.1
Page 222
FordetailsonstoppingandstartinglocatorsandcacheserverswithSSL,seeStartingUpandShuttingDownYourSystem .
Examplelocatorstartcommand
EnsurethatallrequiredSSLpropertiesareconfiguredinyourserver’s gemfire.properties file.Thenstartyourlocatorasfollows:
gfsh>startlocator--name=my_locator--port=12345--dir=.\--security-properties-file=/path/to/your/gemfire.properties
Examplelocatorstopcommand
gfsh>stoplocator--port=12345\--security-properties-file=/path/to/your/gemfire.properties
Exampleserverstartcommand
Again,ensurethatallrequiredSSLpropertiesareconfiguredin gemfire.properties .Thenstarttheserverwith:
gfsh>startserver--name=my_server--locators=hostname[12345]\--cache-xml-file=server.xml--log-level=fine\--security-properties-file=/path/to/your/gemfire.properties
Exampleserverstopcommand
gfsh>stopserver--name=my_server
©CopyrightPivotalSoftwareInc,2013-2019 222 9.1
Page 223
LATESTVERSION:9.1.1- RELEASENOTES
RemoteQueryingThissectiondocumentsremotequeryingfromtheclienttotheserver.Usingexamplesandprocedures,itdescribeshowtousetheAPIstorunqueriesagainstcacheddata,workwithquerystringsintheclient,createandmanagequeries,andcreateindexes.
RemoteQueryingBasicsUsetheclientqueryAPItoqueryyourcacheddatastoredonacacheserver.Thequeryisevaluatedandexecutedonthecacheserver,andtheresultsarereturnedtotheclient.
UsingQueryStringsintheClientTouseaquerystringinaclient,specifythestringasaparameterina QueryService::newQuery method,thenexecutethequeryusing Query::execute ,passingintherequiredparameters.
AccessingCachedDataAccessingyourcacheddatathroughthequeryingserviceissimilartoaccessingdatabasecontentsthroughSQLqueries.Howyouspecifyyourregionsandregioncontentsisparticulartotheclient.
QueryLanguageElementsThissectiondiscussesvariousaspectsandtoolsoftheclientqueryengine.
RemoteQueryAPIYouusetheclientqueryingAPItoaccessallthequeryingfunctionalitydiscussedintheprevioussections.
©CopyrightPivotalSoftwareInc,2013-2019 223 9.1
Page 224
LATESTVERSION:9.1.1- RELEASENOTES
RemoteQueryingBasicsUsetheclientqueryAPItoqueryyourcacheddatastoredonacacheserver.Thequeryisevaluatedandexecutedonthecacheserver,andtheresultsarereturnedtotheclient.
Youcanalsooptimizeyourqueriesbydefiningindexesonthecacheserver.
ThequerylanguageforthenativeclientisessentiallyasubsetofOQL(ODMG3.0ObjectDataManagementGroup,http://www.odmg.org .),whichisbasedonSQL-92.OQLisaSQL-likelanguagewithextendedfunctionalityforqueryingcomplexobjects,objectattributes,andmethods.
ThissectionassumesthatyouhavegeneralfamiliaritywithSQLqueryingandindexing,andwiththeinformationontheclientcache.
QuerylanguagefeaturesandgrammararedescribedintheGemFiremanualatQuerying .Thissectiondescribesareasthatareuniquetothenativeclient.
IfyouareusingthepoolAPI,youshouldobtaintheQueryServicefromthepool.ForinformationaboutthepoolAPI,seeClientPoolAPI.
©CopyrightPivotalSoftwareInc,2013-2019 224 9.1
Page 225
LATESTVERSION:9.1.1- RELEASENOTES
ExampleDataandClassDefinitionsThisextendedexampleisusedthroughoutthesectiontoshowC++andcorrespondingJavaclassdefinitionsandsampledatafortheexample portfolios region.Theregion’skeysaretheportfolioID.
User-defineddatatypesmustimplementthe Serializable interfaceontheclientside,whilecorrespondingJavaclassesmustimplementtheDataSerializable interface.TheC++objectsfortheclientmustcorrespondtotheJavaobjectsfortheGemFirecacheserver.Thismeansthatanobjectononesideshoulddeserializecorrectlyattheotherside.
SampleC++classdefinition
classPortfolio:publicSerializable{intID;char*type;char*status;Map<Position>positions;}classPosition:publicSerializable{char*secId;doublemktValue;doubleqty;}
CorrespondingJavaclassdefinition
classPortfolioimplementsDataSerializable{intID;Stringtype;Stringstatus;Mappositions;}classPositionimplementsDataSerializable{StringsecId;doublemktValue;doubleqty;}
Thefollowingtableliststhesampledataintheportfoliosregion.
id type Statusted Position:secID Position:mktValue Position:qty
111 xyz active xxx 27.34 1000.00
xxy 26.31 1200.00
xxz 24.30 1500.00
222 xyz active yyy 18.29 5000.00
333 abc active aaa 24.30 10.00
333 abc active aab 23.10 15.00
444 abc inactive bbb 50.41 100.00
444 abc inactive bbc 55.00 90.00
Becausetheclientcachewaitsduringtransactionexecution,andclientregionsarenotdistributed,theonlyactivitiesthatinteractwithaclienttransactionarethosethatoccurontheserver.
©CopyrightPivotalSoftwareInc,2013-2019 225 9.1
Page 226
LATESTVERSION:9.1.1- RELEASENOTES
ExecutingaQueryfromtheClientThis.NETandC++exampleusestheexample portfolios regiontoshowhowtoexecuteaqueryfromtheclient.
Note:Inallqueriesthatusetheexampledata,itisassumedthatthe portfolios regionhas javaobject.Portfolio objectsonthecacheserver.
IfyouareusingtheC++client,getapointertothe QueryService method.
Createa QueryPtr toaquery(C++)orcreateaqueryinstance(.NET)thatiscompatiblewiththeOQLspecification.
Usethe execute methodforthe Query interfacetosubmitthequerystringtothecacheserver.Theserverremotelyevaluatesthequerystringandreturnstheresultstotheclient.
Youcaniteratethroughthereturnedobjectsaspartofthequeryprocess.
C#/.NETExample
Query<Portfolio>qry=qrySvc.NewQuery("SELECTDISTINCT*FROM/portfolios");ISelectResults<Portfolio>results=qry.Execute();SelectResultsIterator<Portfolio>iter=results.GetIterator();while(iter.MoveNext()){Console.WriteLine(iter.Current.ToString());}
C++ExampleNote:TheC++examplesinthischapterallassumethatyouhavealreadyobtainedapointertothe QueryService .
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");QueryPtrqry=qrySvcPtr->newQuery("SELECTDISTINCT*FROM/PortfoliosWHEREstatus=‘active’");SelectResultsPtrresultsPtr=qry->execute(10);SelectResultsIteratoriter=resultsPtr->getIterator();while(iter.hasNext()){PortfolioPtrportfolio=dynCast<PortfolioPtr>(iter.next());}
©CopyrightPivotalSoftwareInc,2013-2019 226 9.1
Page 227
LATESTVERSION:9.1.1- RELEASENOTES
QueryingthePortfoliosRegionThe portfolios examplecontinues,showingasamplingofspecificqueries.Thequeryresultsforthedataarelistedinthetable.Forthefirstseveral,thecodingexamplesareincludedaswelltoshowhowtoexecutethequeriesusingtheAPI.
Getdistinctpositionsfromportfolioswithatleasta$25.00marketvalueThisqueryassignsiteratorvariablenamestothecollectionsintheFROMclause.Forexample,thevariable qryP istheiteratorfortheentryvaluesinthe portfolios region.ThisvariableisusedinthesecondpartoftheFROMclausetoaccessthevaluesofthepositionsmapforeachentryvalue.
Querystring:SELECTDISTINCTposnValFROM/portfolios,positions.valuesposnValTYPEPositionWHEREposnVal.mktValue>=25.00
Results:CollectionofPositioninstanceswithsecId:xxx,xxy,bbb,bbc
RetrieveallactiveportfoliosInthefollowingexample,aqueryresponsetimeoutparameterof10secondsisspecifiedfortheexecutemethodtoallowsufficienttimefortheoperationtosucceed.
Querystring:SELECTDISTINCT*FROM/portfoliosWHEREstatus=‘active’
Results:AcollectionofPortfolioobjectsforIDs111,222,and333
Code:QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");QueryPtrqry=qrySvcPtr->newQuery("SELECTDISTINCT*FROM/portfoliosWHEREstatus=‘active’");SelectResultsPtrresultsPtr=qry->execute(10);SelectResultsIteratoriter=resultsPtr->getIterator();while(iter.hasNext()){PortfolioPtrportfolio=dynCast<PortfolioPtr>(iter.next());}
RetrieveallactiveportfoliosthathavetypexyzThe type attributeispassedtothequeryengineindoublequotestodistinguishitfromthequerykeywordofthesamename.Aqueryresponsetimeoutparameterof10secondsisspecifiedfortheexecutemethodtoallowsufficienttimefortheoperationtosucceed.
Querystring:SELECTDISTINCT*FROM/portfoliosWHEREstatus='active'AND"type"='xyz'
Results:AcollectionofPortfolioobjectsforIDs111and222
Code:QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");QueryPtrqry=qrySvcPtr->newQuery("SELECTDISTINCT*FROM/portfoliosWHEREstatus='active'and\"type\"='xyz'");SelectResultsPtrresults=qry->execute(10);SelectResultsIteratoriter=results->getIterator();while(iter.hasNext()){PortfolioPtrportfolio=dynCast<PortfolioPtr>(iter.next());}
GettheIDandstatusofallportfolioswithpositionsinsecId‘yyy’
©CopyrightPivotalSoftwareInc,2013-2019 227 9.1
Page 228
Querystring:SELECTDISTINCTid,statusFROM/portfoliosWHERENOT(SELECTDISTINCT*FROMpositions.valuesposnValTYPEPositionWHEREposnVal.secId='yyy').isEmpty
Results:AcollectionofStructinstances,eachcontaininganidfieldandastatusfield.Forthisdata,thecollectionlengthis1andtheStructcontainsdatafromtheentrywithid222.
Code:QueryServicePtrqrySrvPtr=cachePtr->getQueryService("examplePool");QueryPtrqry=qrySvcPtr->newQuery("importjavaobject.Position;SELECTDISTINCTID,statusFROM""/portfoliosWHERENOT(SELECTDISTINCT*FROMpositions.values""posnValTYPEPositionWHEREposnVal.secId='DELL').isEmpty");SelectResultsPtrresults=qry->execute(10);SelectResultsIteratoriter=results->getIterator();while(iter.hasNext()){Struct*si=(Struct*)iter.next().ptr();SerializablePtrid=si->operator[]("ID");SerializablePtrstatus=si->operator[]("status");printf("\nID=%s,status=%s",id->toString()->asChar(),status->toString()->asChar());}
©CopyrightPivotalSoftwareInc,2013-2019 228 9.1
Page 229
LATESTVERSION:9.1.1- RELEASENOTES
ModifyingCacheContentsTomodifythecachebasedoninformationretrievedthroughquerying,retrievetheentrykeysandusetheminthestandardentryupdatemethods.
Thequeryserviceisadataaccesstool,soitdoesnotprovideanycacheupdatefunctionality.
Thenextexampleshowsentrykeyretrieval.
Getdistinctentrykeysandpositionsfromactiveportfolioswithatleasta$25.00marketvalueInthefollowingexample,retrievingtheentrykeysallowsyoutoaccessthecachedregionentriesforupdate.Youcannotupdatethecachethroughthequeryengine.
Querystring:SELECTDISTINCTkey,posnValFROM/portfolios.entrySet,value.positions.valuesposnValTYPEPositionWHEREposnVal.mktValue>=25.00
Results:ASelectResultsofStructinstancescontainingkey,Positionpairs.
©CopyrightPivotalSoftwareInc,2013-2019 229 9.1
Page 230
LATESTVERSION:9.1.1- RELEASENOTES
CreatingIndexesAnindexcanprovidesignificantperformancegainsforqueryexecution.Youcreateandmaintainindexesonthecacheserver.
Aqueryrunwithoutanindexiteratesthrougheveryobjectinthecollectiononthecacheserver.Ifanindexisavailablethatmatchespartorallofthequeryspecification,thequeryiteratesonlyovertheindexedset,andqueryprocessingtimecanbereduced.
Whenyoucreateyourindexesonthecacheserver,rememberthatindexesincurmaintenancecostsastheymustbeupdatedwhentheindexeddatachanges.Anindexthatrequiresmanyupdatesandisnotusedveryoftenmayrequiremoresystemresourcesthannoindexatall.Indexesalsoconsumememory.Forinformationontheamountofmemoryusedforindexes,seethesystemconfigurationinformation.
Youcancreateanindexforremotequeryingdeclarativelyonthecacheserverina cache.xml file,asshowninthisexample.
CreatinganIndexonaCacheServerUsingaServerXMLFile
<regionname="portfolios"><region-attributes...><value-constraint>cacheRunner.Portfolio</value-constraint></region-attributes><indexname="myFuncIndex"><functionalfrom-clause="/portfolios"expression="status"/></index><indexname="myPrimIndex"><primary-keyfield="id"/></index><entry>...
Fordetailedinformationaboutworkingwithindexesconfiguredonacacheserver,seeWorkingwithIndexes withintheserver’sdocumentation.
©CopyrightPivotalSoftwareInc,2013-2019 230 9.1
Page 231
LATESTVERSION:9.1.1- RELEASENOTES
RemoteQueryingRequirementsNotetheparticularrequirementsforusingregionendpoints;settingserverregiondatapolicyandscope;implementingequalsandhashcodemethods;andsettingobjecttypeconstraints.
UsingRegionEndpointsWhenyouareusingregionendpoints,atleastoneregionmustexistontheclientbeforeaquerycanbeexecutedthroughtheclient.Allobjectsintheregionbelongtothesameclasshierarchy(homogenoustypes).
SettingServerRegionDataPolicyandScopeRemotequeryingonlyaccessesthedatathatisavailableintheremotecacheserverregion,sonolocalcacheloadingoperationsareperformed.Dependingonthecacheserverregion’sscopeanddata-policyattributesettings,thiscouldmeanthatyourqueriesandindexesonlyseeapartofthedataavailablefortheserverregioninthedistributedcache.
Toensureacompletedatasetforyourqueriesandindexes,yourcacheserverregionmustuseoneoftheREPLICATEregionshortcutsettingsintheregionattributerefidoritmustexplicitlyhaveitsdatapolicysettoreplicateorpersistent-replicate.
Foracacheserverregion,settingitsdatapolicytoreplicateor persistent-replicate ensuresthatitreflectsthestateoftheentiredistributedregion.Withoutreplication,someservercacheentriesmaynotbeavailable.
Dependingonyouruseoftheservercache,thenon-globaldistributedscopes distributed-ack and distributed-no-ack mayencounterraceconditionsduringentrydistributionthatcausethedatasettobeoutofsyncwiththedistributedregion.Theglobalscopeguaranteesdataconsistencyacrossthedistributedsystem,butatthecostofreducedperformance.
Thefollowingtablesummarizestheeffectsofcacheserverregionscopeanddatapolicysettingsonthedataavailabletoyourqueryingandindexingoperations.Formoreinformation,seetheserver’sdocumentationonDistributedandReplicatedRegions .
RegionScope Notreplicated Replicated
distributed-ack or distributed-no-ack N/A FULLdataset(ifnoraceconditions).
global N/A FULLdataset.
ImplementingtheequalsandhashcodeMethodsThe Portfolio and Position queryobjectsforthecacheservermusthavethe equals and hashCode methodsimplemented,andthosemethodsmustprovidethepropertiesandbehaviorforJava Object.equals and Object.hashCode .Inconsistentqueryresultscanoccurifthesemethodsareabsent.
SettingObjectTypeConstraintsPerformingqueriesoncacheserverregionscontainingheterogeneousobjects,whichareobjectsofdifferentdatatypes,mayproduceundesirableresults.Queriesshouldbeperformedonlyonregionsthatcontainhomogeneousobjectsofthesameobjecttype,althoughsubtypesareallowed.
Soyourquerieswilladdresshomogeneousdatatypes,youneedtobeawareofthevaluesthattheclientaddstotheserver.Youcansetthekey-constraint andvalue-constraintregionattributestorestrictregionentrykeysandvaluestoaspecificobjecttype.However,becauseobjectsputfromtheclientremaininserializedformintheservercacheanddonotgetdeserializeduntilaqueryisexecuted,itisstillpossibletoputheterogeneousobjectsfromtheclient.
SeeSpecifyingtheobjecttypesofFROMclausecollectionsformoreinformationonassociatingobjecttypeswithqueries.
©CopyrightPivotalSoftwareInc,2013-2019 231 9.1
Page 232
LATESTVERSION:9.1.1- RELEASENOTES
UsingQueryStringsintheClientTouseaquerystringinaclient,specifythestringasaparameterina QueryService::newQuery method,thenexecutethequeryusing Query::execute ,passingintherequiredparameters.
Alternatively,ifanexpressionevaluatestoabooleanvalue,youcanspecifyitusingtheregionshortcutmethods Region::existsValue , Region::selectValue ,and Region::query .Theseshortcutmethodsevaluatewhethergivenexpressionsreturnanyentriesandreturnasinglevalueentry,respectively.SeeRegionShortcutQueryMethodsformoreinformationabouttheseshortcutmethods.
Ifyourqueryrequiresany IMPORT statements,youmustincludethesebeforethe SELECT statementinthequerystringthatispassedtothequeryengine.Itshouldbeafullyqualifiedpackagenamerelativetothecacheserver.TheJavaclassdefinitionmustexistandhavethesamesignatureastheclientC++class.
©CopyrightPivotalSoftwareInc,2013-2019 232 9.1
Page 233
LATESTVERSION:9.1.1- RELEASENOTES
FROMClauseThe FROM clauseestablishescollectionsofobjectsthatareiteratedoverbytheremainderofthequery.
Theattributesoftheobjectsinthesecollectionsareaddedtothenamespacescopefortheremainderofthe FROM clauseaswellasforthe WHERE clauseandthe SELECTlist.
Each FROM clauseexpressionmustevaluatetoacollection.Theexpression /portfolios.keySet isvalidbecauseitevaluatestoa Collection ,but /portfolios.name ,whichevaluatestoa,causesanexceptiontobethrown.
LiketheSQLquery,whichiteratesoverthetablesnamedinits FROM clause,the OQL queryiteratesoverthe Collections establishedinits FROM clause.
Inthefollowingquery, positions.values evaluatestoa Collection because positions isaMap,andthemethodvalueson Map returnsa Collection .
IMPORTjavaobject.Position;SELECTDISTINCT"type"FROM/portfolios,positions.valuesposnValTYPEPositionWHEREposnVal.qty>1000.00
Everyexpressioninthe FROM clausemustevaluatetoa Collection .ForaMap,thevaluesmethodreturnsa Collection .
IfpositionswereaListinsteadofaMap,thisquerycouldbeusedtoretrievethedata:
IMPORTjavaobject.Position;SELECTDISTINCT"type"FROM/portfolios,positionsposnValTYPEPositionWHEREposnVal.qty>=1000.00
AListisa Collection ,soyoucanaccessitdirectlyorthroughits toArray method.
Foreachobjecttypeaccessedinyour FROM clause,usethemethodthatreturnsa Collection forthatobject.
Eachexpressioninthe FROM clausecanbeanyexpressionthatevaluatestoa Collection .Anexpressioninthe FROM clauseistypicallyapathexpressionthatresolvestoaregioninthecachesothatthevaluesintheregionbecomethecollectionofobjectstofilter.
Forexample,thisisasimple SELECT statementthatevaluatestoasetofalltheentryvalueobjectsoftheregion /portfolios withactivestatus.Thecollectionofentryvaluesprovidedbythe FROM clauseistraversedbythe WHERE clause,whichaccesseseachelement’sstatusattributeforcomparison.
SELECTDISTINCT*FROM/portfoliosWHEREstatus='active'
Ifthe FROM clausehasonlyoneexpressioninit,theresultoftheclauseisthesinglecollectionthattheexpressionevaluatesto.Iftheclausehasmorethanoneexpressioninit,theresultisacollectionofstructsthatcontainamemberforeachofthosecollectionexpressions.Forexample,ifthe FROM clausecontainsthreeexpressionsthatevaluatetocollectionsC1 , C2, and C3 ,the FROM clausegeneratesasetof struct(x1,x2,
x3)where x1 , x2 ,and x3 representnestediterationsoverthecollectionsspecified.
Ifthecollectionsareindependentofeachother,this struct representstheircartesianproduct.
Inthisquery,the FROM clauseproducesa struct of portfolio andpositionpairstobeiterated.Eachelementinthestructcontainstheportfolioandoneofitscontainedpositions.
IMPORTjavaobject.Position;SELECTDISTINCT"type"FROM/portfolios,positionsTYPEPositionWHEREqty>1000.00
Tounderstandtheeffectsof FROM expressionsonqueryscope,seeDrillingDownforModifyingQueryScope.
©CopyrightPivotalSoftwareInc,2013-2019 233 9.1
Page 234
LATESTVERSION:9.1.1- RELEASENOTES
UsingIteratorVariablesForeachcollectionexpressedinthe FROM clause,youcanassociateanexplicitvariable.Thevariableisaddedtothecurrentscopeandbecomestheiteratorvariableboundtotheelementsofthecollectionastheyareiteratedover.Inthisexample, pflo and posnVal arebothexplicititeratorvariables.
QueryUsingExplicitIteratorVariables
IMPORTjavaobject.Position;SELECTDISTINCTpflo."type",posnVal.qtyFROM/portfoliospflo,positions.valuesposnValTYPEPositionWHEREpflo.status='active'andposnVal.mktValue>25.00
©CopyrightPivotalSoftwareInc,2013-2019 234 9.1
Page 235
LATESTVERSION:9.1.1- RELEASENOTES
ImportingandUsingObjectClassesTofacilitatethespecificationoftypeinvariabletypedeclarationsandintypecastingexpressions,aquerystringcanhave IMPORT statementsprecedingthedeclarations.ByusingIMPORT inthequerystring,theclientcantellthecacheserverabouttheclassdefinitionoftheserializedobjectthatispresentinthecacheserverregion.
Theonlyplaceyoucanhaveapackagenameinaqueryisinanimportstatement.Thesearevalid:
IMPORTcom.myFolder.Portfolio;IMPORTcom.myFolder.PortfolioASMyPortfolio;
ThefirstformoftheimportstatementallowsPortfoliotobeusedasthenameoftheclass, com.myFolder.Portfolio .Thesecondformprovidesanalternativeclassname,MyPortfolio,tobeused.Thisisusefulwhenaclassnameisnotuniqueacrosspackagesandclassesinasinglequery.
UsingImportedClassesThefollowingexampleusesimportedclasses:
IMPORTcom.commonFolder.Portfolio;IMPORTcom.myFolder.PortfolioASMyPortfolio;SELECTDISTINCTmpflo.statusFROM/portfoliospfloTYPEPortfolio,/myPortfoliosmpfloTYPEMyPortfolio,WHEREpflo.status='active'andmpflo.id=pflo.id
Thisentirequerystringmustbepassedtothequeryengine,includingthe IMPORT statements.Commontypenamesdonotrequirean IMPORT statement.ThefollowingtableliststhetypesthataredefinedbythesystemandtheJavatypestheyrepresent.
©CopyrightPivotalSoftwareInc,2013-2019 235 9.1
Page 236
LATESTVERSION:9.1.1- RELEASENOTES
PredefinedClassTypesThe FROM clauseestablishescollectionsofobjectsthatareiteratedoverbytheremainderofthequery.Theattributesoftheobjectsinthesecollectionsareaddedtothenamespacescopefortheremainderofthe FROM clauseaswellasforthe WHERE clauseandthe SELECT projectionlist.
Thetypespecificationcanbeanimportedtypeoranyofthesepredefinedtypes.
Type Java C++ .NET
short short CacheableInt16 Int16
long long CacheableInt64 Int64
int int CacheableInt32 Int32
float float CacheableFloat Single
double double CacheableDouble Double
char char CacheableWideChar Char
string java.lang.String CacheableString String
boolean boolean CacheableBoolean Boolean
byteoroctet byte CacheableByte Byte
date java.sql.Date CacheableDate DateTime
time java.sql.Time Unsupported Unsupported
timestamp java.sql.Timestamp Unsupported Unsupported
set<type> java.util.Set CacheableHashSet HashSet<type>
list<type> java.util.List CacheableVector List<type>
array<type> java.lang.Object[] CacheableArray ArrayList<type>
map<type,type>ordictionary<type,type> java.lang.Map CacheableHashMapp Dictionary<type,type>orHashTable
©CopyrightPivotalSoftwareInc,2013-2019 236 9.1
Page 237
LATESTVERSION:9.1.1- RELEASENOTES
SpecifyingtheObjectTypesofFROMClauseCollectionsToresolveimplicitattributenames,thequeryenginemustbeabletoassociateeachattributeormethodnametoasingleiteratorexpressionintheFROM clause.
Dependingonthecomplexityofthequery,theenginemaybeabletodiscovertheproperassociationsonitsown,butprovidingthespecificationsdescribedhereincreasesthechancesforsuccess.
Theserverregionbeingqueriedshouldcontainonlyhomogeneousobjectsofthesametype.SeeSettingObjectTypeConstraintsformoreinformation.
Theobjecttypeinformationmustbeavailablewhenthequeryiscreated.Toprovidetheappropriateinformationtothequeryengine,specifythetypeforeachofyour FROMcollectionobjectsbyimportingtheobject’sclassbeforerunningthequeryandtypingtheobjectinsidethequery.Fortheexampleregion,thisqueryisvalid(alloftheexamplesinthissectionassumethatthis IMPORT statementisprovided):
QueryUsingIMPORTandTYPEforObjectTyping
IMPORTjavaobject.Position;SELECTDISTINCTmktValueFROM/portfolios,positions.valuesTYPEPositionWHEREmktValue>25.00
Thisentirequerystringmustbepassedtothequeryengine,includingtheIMPORTstatement.Importtheobject’sclassbeforerunningthequeryandtypecasttheobjectinsidethequery.Fortheexampleregion,bothofthesequeriesarevalid:
QueryUsingIMPORTandTypecastingforObjectTyping
IMPORTjavaobject.Position;SELECTDISTINCTvalue.mktValueFROM/portfolios,(map<string,Position>)positionsWHEREvalue.mktValue>25.00IMPORTcacheRunner.Position;SELECTDISTINCTmktValueFROM/portfolios,(collection<Position>)positions.valuesWHEREmktValue>25.00
Thisentirequerystringmustbepassedtothequeryengine,includingthe IMPORT statement.Usenamediteratorsinthe FROM clauseandexplicitlyprefixthepathexpressionwithiteratornames.
QueryUsingNamedIteratorsforObjectTyping
SELECTDISTINCTposnVal
FROM/portfoliospflo,pflo.positions.valuesposnVal
WHEREposnVal.mktValue>=25.00
The IMPORT statementsintheseexamplesassumethatthe classes directoryoftheexamplesisinthe CLASSPATH .Thisisrequiredsothecacheservercanprocess IMPORT
statements.Theclass’spackagenamecannotbeusedinthe FROM clause.Thepackagenamemustbespecifiedinan IMPORT statement.
Thereisoneexceptiontothesetypingguidelines.Ifone FROM expressionlacksexplicittyping,thequeryengineassociatesallunresolvedattributeswiththatexpressionandcreatesthequery.Anexceptionisthrownifanyoftheseattributesarenotfoundatexecutiontime.
©CopyrightPivotalSoftwareInc,2013-2019 237 9.1
Page 238
LATESTVERSION:9.1.1- RELEASENOTES
SELECTProjectionListTheprojectionsintheSELECTprojectionlistareusedtotransformtheresultsoftheWHEREsearchoperation.
Youspecifytheprojectionlisteitheras*orasacommadelimitedlistofexpressions.For*,theinterimresultsoftheWHEREclausearereturnedfromthequery.Otherwise,thesetofobjectsintheinterimresultsareiteratedandtheprojectionsappliedtoeachoftheobjects.Duringtheapplicationoftheprojectionlist,theattributesoftheobjectsbeingtraversedareinscopefornameresolution.
Youcanalsospecifyretrievaloftheentrykeysinyourprojectionlist.Thisallowsyoutoaccesstheassociatedcachedentriesformodificationandotherpurposes.ThefollowingexampleshowshowtheRegionentrykeycanbeobtainedbyusingtheregionentriesintheFROMclauseandusingappropriateprojections.Thisqueryrunsonthe/portfoliosregion,returningasetof struct<key:string,id:string,secId:string> where key isthekeyoftheregionentry, id isanentryID,and secId isasecIdofa positionsmap fortheentry.
SELECTDISTINCTkey,entry.value.id,posnVal.secId
FROM/portfolios.entrySetentry,entry.value.positions.valuesposnVal
WHEREentry.value."type"='xyz'ANDposnVal.secId='XXX'
©CopyrightPivotalSoftwareInc,2013-2019 238 9.1
Page 239
LATESTVERSION:9.1.1- RELEASENOTES
SELECTStatementQueryResultsTheresultofa SELECT statementisacollectionthatimplementsthe SelectResults interfaceoritis UNDEFINED .
The SelectResults returnedfromthe SELECT statementiseitheracollectionofobjectsora Struct collectioncontainingtheobjects.(SeealsotheAPIdocumentationforQuery.)
Becausea SELECT statementreturnsaresult,itcanbecomposedwithotherexpressionslikethefollowingexample:
(SELECTDISTINCT*FROM/portfoliosWHEREstatus='active').iterator
Acollectionofobjectsisreturnedintwocases:
Whenonlyoneexpressionisspecifiedbytheprojectionlistandthatexpressionisnotexplicitlyspecifiedusingthe fieldname:expression syntax
Whenthe SELECT listis*andasinglecollectionisspecifiedintheFROMclause
Table1.MatrixofSelectResultsContentsBasedonSELECTandFROMClauseSpecifications
SELECT
FROM* SingleExpressions MultipleExpressions
singleexpression ObjectsObjects.( Struct iftheprojectionspecifiesafieldname.)
Struct
multipleexpressions StructObjects.( Struct iftheprojectionspecifiesafieldname.)
Struct
Whena Struct isreturned,thenameofeachfieldinthe Struct isdeterminedasfollows:
Ifafieldisspecifiedexplicitlyusingthe fieldname:expression syntax,thefieldnameisused.
Ifthe SELECT projectionlistis*andanexplicititeratorexpressionisusedinthe FROM clause,theiteratorvariablenameisusedasthefieldname.
Ifthefieldisassociatedwitharegionorattributepathexpression,thelastattributenameintheexpressionisused.
Ifnamescannotbedecidedbasedontheserules,arbitraryuniquenamesaregeneratedbythequeryprocessor.
TheseexamplesshowhowtheprojectionsandFROMclauseexpressionsareapplied.
SELECT <*> FROM <single expression>
SELECT DISTINCT *
FROM/portfolios
WHEREstatus='active'
Returnsthe Collection ofactiveportfoliosobjects.
SELECT <single expression> FROM <multipleexpression>
(without fieldName mentioned)
IMPORT javaobject.Position; SELECT DISTINCT secId
FROM/portfolios,
positions.valuesTYPEPosition
WHEREstatus=‘active’
Returnsthe Collection of secIds ( CacheableString
objects)fromthepositionsofactiveportfolios.
SELECT <single expression> FROM
<multipleexpression> (with fieldName mentioned)
IMPORT javaobject.Position;SELECT DISTINCTsecIdFieldName:secId
FROM/portfolios,positions.valuesTYPEPosition
Returns struct<secIdField: CacheableString>activeportfolios.(Comparetotheresultsforthepriorquery.)
©CopyrightPivotalSoftwareInc,2013-2019 239 9.1
Page 240
WHEREstatus='active'
SELECT <*> FROM <multiple expression>
IMPORTjavaobject.Position;SELECTDISTINCT*
FROM/portfolios,positions.valuesTYPEPosition
WHEREstatus='active'
Returnsa Collection ofstruct<portfolios:Portfolio,values:Position>
fortheactive
portfolios.
SELECT<multipleexpression>FROM<multipleexpression>
IMPORTjavaobject.Position;
SELECTDISTINCTpflo,posn
FROM/portfoliospflo,positionsposnTYPEPosition
WHEREpflo.status='active'
Returnsa Collection of struct<pflo:Portfolio,posn:Position>theactiveportfolios.
©CopyrightPivotalSoftwareInc,2013-2019 240 9.1
Page 241
LATESTVERSION:9.1.1- RELEASENOTES
WHEREClauseTheoptionalWHEREclausedefinesthesearchcriteriafortheselection,filteringthesetofelementsspecifiedbytheFROMclause.
WithoutaWHEREclause,theSELECTprojectionlistreceivestheentirecollectionorsetofcollectionsasspecifiedintheFROMclause.
ThequeryprocessorsearchesthecollectionforelementsthatmatchtheconditionsspecifiedintheWHEREclauseconditions.IfthereisanindexonanexpressionmatchedbytheWHEREclause,thenthequeryprocessormayusetheindextooptimizethesearchandavoiditeratingovertheentirecollection.
AWHEREclauseexpressionisabooleanconditionthatisevaluatedforeachelementinthecollection.Iftheexpressionevaluatestotrueforanelement,thequeryprocessorpassesthatelementontotheSELECTprojectionlist.ThisexampleusestheWHEREclausetoreturntheportfolioobjectsintheregionthathaveatypexyz.
SELECTDISTINCT*FROM/portfoliosWHERE"type"='xyz'
Thenextqueryreturnsthesetofallportfolioswithatypeofxyzandactivestatus.
SELECTDISTINCT*FROM/portfoliosWHERE"type"='xyz'ANDstatus='active'
©CopyrightPivotalSoftwareInc,2013-2019 241 9.1
Page 242
LATESTVERSION:9.1.1- RELEASENOTES
JoinsIfcollectionsinthe FROM clausearenotrelatedtoeachother,youcanusethe WHERE clausetojointhem.
Thestatementbelowreturnsallthepersonsfromthe /Persons regionwiththesamenameasaflowerinthe /Flowers region.
SELECTDISTINCTpFROM/Personsp,/FlowersfWHEREp.name=f.name
Indexesaresupportedforregionjoins.Tocreateindexesforregionjoins,youcreatesingle-regionindexesforbothsidesofthejoincondition.Theseareusedduringqueryexecutionforthejoincondition.
©CopyrightPivotalSoftwareInc,2013-2019 242 9.1
Page 243
LATESTVERSION:9.1.1- RELEASENOTES
AccessingCachedDataAccessingyourcacheddatathroughthequeryingserviceissimilartoaccessingdatabasecontentsthroughSQLqueries.Howyouspecifyyourregionsandregioncontentsisparticulartotheclient.
Thequerylanguagesupportsdrillingdownintonestedobjectstructures.RegionscancontainnesteddatacollectionsthatareunavailableuntilreferencedintheFROMclause.
Thisdiscussiondescribeshowtonavigatetoyourcacheddatathroughtheclientqueryservice.
Queryingandindexingonlyoperateonremotecacheservercontents.
©CopyrightPivotalSoftwareInc,2013-2019 243 9.1
Page 244
LATESTVERSION:9.1.1- RELEASENOTES
BasicRegionAccessInthecontextofaquery,specifythenameofaregionbyitsfullpath,startingwithaforwardslash(/).
ObjectAttributesYoucanaccesstheRegionobject’spublicfieldsandmethodsfromaregionpath,referredtoastheregion’sattributes.Usingthismethod, /portfolios.name returns“ portfolios
/portfolios.name.length returns 10 .AnattributeismappedtoaJavaclassmemberinthreepossiblewayswiththefollowingpriorityuntilamatchisfound.Iftheattributeisnamedx,then:
publicmethodgetX()publicmethodx()publicfieldx
Note:Thetermattributeinthiscontextisnotthesameasaregionattribute.
RegionDataYoucanalsoaccessentrykeysandentrydatathroughtheregion:
/portfolios.keySet returnsthe Set ofentrykeysintheregion
/portfolios.entrySet returnsthe Set of Region.Entry objects
/portfolios.values returnstheCollectionofentryvalues
/portfolios returntheCollectionofentryvalues.
TheFROMclause /portfolios.values and /portfolios returnthesamething.Notethatthesecollectionsareimmutable.Invokingmodifiermethodsonthem,suchas add andinan UnsupportedOperationException .
©CopyrightPivotalSoftwareInc,2013-2019 244 9.1
Page 245
LATESTVERSION:9.1.1- RELEASENOTES
AttributeVisibilityWithinthecurrentqueryscope,youcanaccessanyavailableobjectorobjectattribute.
Inquerying,anobject’sattributeisanyidentifierthatcanbemappedtoapublicfieldormethodintheobject.
Inthe FROM specification,anyobjectthatisinscopeisvalid,soatthebeginningofaqueryallcachedregionsandtheirattributesonthecacheserverareinscope.
ThisqueryisvalidbecausenameresolvestotheRegionmethod getName :
/portfolios.name
Thisqueryisvalidbecause toArray resolvestothe Collection methodwiththesamename:
SELECTDISTINCT*FROM/portfolios.toArray
Youcannot,however,refertotheattributeofacollectionobjectintheregionpathexpressionwherethecollectionitselfisspecified.ThefollowingstatementisinvalidbecauseneitherCollection nor Region containanattributenamed positions .Theentryvaluescollection(specifiedby /portfolios )thatdoescontainanattributenamedpositionsisnotyetpartofthequerynamespace.
/*INCORRECT:positionsisnotanattributeofRegionorofCollection*/SELECTDISTINCT*FROM/portfolios.positions
Thefollowing SELECT statementisvalid,because positions isanelementoftheentryvaluecollectionthatisspecifiedby /portfolios .TheentryvaluecollectionisinscopeassoonasthespecificationintheFROMexpressioniscomplete(before WHERE or SELECT areevaluated).
SELECTDISTINCTpositionsFROM/portfolios
YoucanalsorefertopositionsinsidetheFROMclauseafterthe /portfolios entryvaluecollectioniscreated.Inthisexample,positionsisanelementofthe /portfolios entryvaluecollectionandvaluesisanattributeofpositions:
IMPORTjavaobject.Position;SELECTDISTINCTposnValFROM/portfolios,positions.valuesposnValTYPEPositionWHEREposnVal.mktValue>=25.00
AfterthecommaintheFROMclause, /portfolios isinscope,soitsvaluecollectioncanbeiterated.Inthiscase,thisisdonewiththesecondFROMclausespecification, positions.values
©CopyrightPivotalSoftwareInc,2013-2019 245 9.1
Page 246
LATESTVERSION:9.1.1- RELEASENOTES
ModifyingQueryScopeThequeryengineresolvesnamesandpathexpressionsaccordingtothenamespacethatiscurrentlyinscopeinthequery.Thisisnottheregionscopeattribute,butthescopeofthequerystatement.
Theinitialnamespaceforanyqueryiscomposedoftheregionpathsofthecacheonthecacheserverandtheattributesofthosepaths.Newnamespacesarebroughtintoscopebasedonthe FROM clauseinthe SELECT statement.Forexample,inthisquerythe FROM expressionevaluatestothecollectionofentryvaluesin /portfolios .Thisisaddedtotheinitialscopeofthequeryandstatusisresolvedwithinthenewscope.
SELECTDISTINCT*FROM/portfoliosWHEREstatus='active'
Each FROM clauseexpressionmustresolvetoacollectionofobjectsavailableforiterationinthequeryexpressionsthatfollow.Intheexampleabove, /portfolios resolvestotheCollectionofentryvaluesintheregion.Theentryvaluecollectionisiteratedbythe WHERE clause,comparingthestatusfieldtothestringactive.Whenamatchisfound,thevalueobjectisaddedtothereturnset.
Inthefollowingquery,thecollectionspecifiedinthefirstFROMclauseexpressionisusedbythesecondFROMclauseexpressionandbytheprojectionsoftheSELECTstatement.
IMPORTcacheRunner.Position;SELECTDISTINCT"type"FROM/portfolios,positions.valuesposnValTYPEPositionWHEREposnVal.qty>1000.00
Note:YoucannotchangetheorderoftheexpressionsinthisFROMclause.Thesecondexpressiondependsonthescopecreatedbythefirstexpression.
©CopyrightPivotalSoftwareInc,2013-2019 246 9.1
Page 247
LATESTVERSION:9.1.1- RELEASENOTES
NestedQueryScopesYoucannestscopesbyusingnested SELECT statements.Namesinaninnerscopehideidenticalnamesinanouterscope.
Inthequerybelow,theinner SELECT createsanewscope,thepositionsofthecurrentportfolio,insidetheouter SELECT ’sscope, /portfolios .Thisinnerscope(thecollectionofentryvaluesfromthe /portfolios region)isfirstsearchedforthe secId element.Theouterscopeissearchedonlyifthe secId elementisnotfoundintheinnerscope.
IMPORTjavaobject.Position;SELECTDISTINCT*FROM/portfoliosWHERENOT(SELECTDISTINCT*FROMpositions.valuesTYPEPositionWHEREsecId='YYY').isEmpty
Thisstatementshowstheouterscopeinbold.TheouterscopehasalltheattributesofaPortfolioinit.
IMPORT javaobject.Position;SELECT DISTINCT * FROM /portfolios WHERE NOT (SELECT DISTINCT * FROM positions.values TYPE Position WHERE secId='YYY').isEmpty
Nowthestatementwiththeinnerscopeisshowninbold.Theinnerscopehasalltheattributesofa Portfolio init(inheritedfromtheouterscope),andalltheattributesofawell.
IMPORT javaobject.Position;SELECT DISTINCT * FROM /portfolios WHERE NOT (SELECT DISTINCT * FROM positions.values TYPE Position WHERE secId='YYY).isEmpty
©CopyrightPivotalSoftwareInc,2013-2019 247 9.1
Page 248
LATESTVERSION:9.1.1- RELEASENOTES
WhenNamesCannotBeResolvedWhenaqueryisexecutedandanameorpathexpressionresolvestomorethanoneregionnameinthescope,orifthenamecannotberesolvedatall,theclientreceivesaThe QueryException containsthemessagethatisgeneratedfortheexceptionthatoccursontheserver.
©CopyrightPivotalSoftwareInc,2013-2019 248 9.1
Page 249
LATESTVERSION:9.1.1- RELEASENOTES
QueryLanguageElementsThissectiondiscussesvariousaspectsandtoolsofthenativeclientqueryengine.
MethodInvocationThequerylanguagesupportsmethodinvocationinsidequeryexpressions.
SupportedQueryLanguageLiteralsQuerylanguageexpressionscancontainliteralsaswellasoperatorsandattributenames.Theclientsupportsmanytypesofliterals.
TypeConversionsJavaruleswithinaquerystringrequirethequeryprocessortoperformimplicitconversionsandpromotionsundercertaincasesinordertoevaluateexpressionsthatcontaindifferenttypes.
©CopyrightPivotalSoftwareInc,2013-2019 249 9.1
Page 250
LATESTVERSION:9.1.1- RELEASENOTES
MethodInvocationThequerylanguagesupportsmethodinvocationinsidequeryexpressions.
ThequeryprocessormapsattributesinquerystringsusingtheattributerulesdescribedinObjectAttributes.Methodsdeclaredtoreturn void evaluateto null wheninvokedthroughthequeryprocessor.Ifyouknowthattheattributenamemapstoapublicmethodthattakesnoparameters,youcansimplyincludethemethodnameinthequerystringasanattribute.Forexample, emps.isEmpty isequivalentto emps.isEmpty() .Inthefollowingexample,thequeryinvokes isEmpty onpositions,andreturnsthesetofallportfolioswithnopositions.
SELECTDISTINCT*FROM/portfoliosWHEREpositions.isEmpty
Theclientalsosupportstheinvocationofpublicmethodswithparameters.Toinvokemethodswithparameters,includethemethodnameasanattributeinthequerystringandprovidethemethodargumentsbetweenparentheses.Youcanonlyuseconstantsinthequerystrings.
©CopyrightPivotalSoftwareInc,2013-2019 250 9.1
Page 251
LATESTVERSION:9.1.1- RELEASENOTES
SupportedQueryLanguageLiteralsQuerylanguageexpressionscancontainliteralsaswellasoperatorsandattributenames.Theclientsupportsmanytypesofliterals.
boolean .Booleanvalue,either TRUE or FALSE .
integer and long .Type long ifitissuffixedwiththeASCIIletterL.Otherwiseitisoftype int .
floating point .TypefloatifitissuffixedwithanASCIIletterF.OtherwiseitstypeisdoubleanditcanoptionallybesuffixedwithanASCIIletterD.AdoubleorfloatingpointliteralcanoptionallyincludeanexponentsuffixofEore,followedbyasignedorunsignednumber.
string .Delimitedbysinglequotationmarks.Embeddedsinglequotationmarksaredoubled.Forexample,thecharacterstring'Hello' evaluatestothevalue Hellocharacterstring 'He said, ''Hello''' evaluatesto He said, 'Hello' .Embeddednewlinesarekeptaspartofthestringliteral.
char .Type char ifitisastringliteralprefixedbythekeyword CHAR ;otherwiseitisoftype string .TheCHARliteralforthesinglequotationmarkcharacteris CHAR ''''singlequotationmarks).
date . java.sql.Date objectthatusestheJDBCformatprefixedwiththe DATE keyword: DATE yyyy-mm-dd .IntheDate, yyyy representstheyear, mm representsthemonth,and dd representstheday.Theyearmustberepresentedbyfourdigits;atwo-digitshorthandfortheyearisnotallowed.
time .Notsupported.
timestamp .Notsupported.
NIL .Equivalentalternativeof NULL .
NULL .Sameas null inJava.
UNDEFINED .Specialliteralthatisavalidvalueforanydatatype.An UNDEFINED valueistheresultofaccessinganattributeofanull-valuedattribute.Ifyouaccessanattributethathasanexplicitvalueofnull,thenitisnotundefined.Forexample,ifaqueryaccessestheattribute address.city andaddressisnull,thentheresultisundefined.Ifthequeryaccesses address ,thentheresultisnotundefined,itisnull.
©CopyrightPivotalSoftwareInc,2013-2019 251 9.1
Page 252
LATESTVERSION:9.1.1- RELEASENOTES
TypeConversionsJavaruleswithinaquerystringrequirethequeryprocessortoperformimplicitconversionsandpromotionsundercertaincasesinordertoevaluateexpressionsthatcontaindifferenttypes.
Thequeryprocessorperformsbinarynumericpromotion,methodinvocationconversion,andtemporaltypeconversion.
BinarynumericpromotionBinarynumericpromotionwidensalloperandsinanumericexpressiontothewidestrepresentationusedbyanyoftheoperands.Ineachexpression,thequeryprocessorappliesthefollowingrulesinorder:
Ifeitheroperandisoftypedouble,theotherisconvertedtodouble.
Ifeitheroperandisoftypefloat,theotherisconvertedtofloat.
Ifeitheroperandisoftypelong,theotherisconvertedtolong.
Bothoperandsareconvertedtotypeint.
Thequeryprocessorperformsbinarynumericpromotionontheoperandsofthefollowingoperators:
comparisonoperators<,<=,>,and>=
equalityoperators=and<>
ThisisessentiallythesamebehaviorasinJava,exceptthatcharsarenotconsideredtobenumericinthenativeclientquerylanguage.
MethodinvocationconversionMethodinvocationconversioninthequerylanguagefollowsthesamerulesasJavamethodinvocationconversion,exceptthatthequerylanguageusesruntimetypesinsteadofcompiletimetypes,andhandlesnullargumentsdifferentlythaninJava.Oneaspectofusingruntimetypesisthatanargumentwithanullvaluehasnotypinginformation,andsocanbematchedwithanytypeparameter.Whenanullargumentisused,ifthequeryprocessorcannotdeterminethepropermethodtoinvokebasedonthenon-nullarguments,itthrowsanAmbiguousNameException .Formoreinformationonmethodinvocationinquerystrings,seeMethodInvocation.
TemporaltypeconversionThetemporaltypesthatthequerylanguagesupportsonthecacheserverincludetheJavatypes java.util.Date and java.sql.Date ,whicharetreatedthesameandcanbefreelycomparedandusedinindexes.Whencomparedwitheachother,thesetypesarealltreatedasnanosecondquantities.
©CopyrightPivotalSoftwareInc,2013-2019 252 9.1
Page 253
LATESTVERSION:9.1.1- RELEASENOTES
RemoteQueryAPIYouusethequeryingAPItoaccessallthequeryingfunctionalitydiscussedintheprevioussections.
ThissectiongivesageneraloverviewoftheinterfacesandclassesthatareprovidedbytheQuerypackageAPI,andtheshortcutmethodsprovidedintheRegioninterface.
CreatingandManagingQueriesYoucreatequeriesonthecacheserverbyobtaininga QueryService methodandmanagethemthroughtheresulting Query object.The Region interfacehasseveralshortcutquerymethods.
QueryResultSets
QueryCodeSamplesReturningResultSetAPIexamplesdemonstratemethodsforreturning ResultSet forbothbuilt-inanduser-fineddatatypes.
QueryCodeSamplesReturningStructSetTheseexamplesreturna StructSet forbuilt-inanduser-defineddatatypes, Struct objects,andcollections.
©CopyrightPivotalSoftwareInc,2013-2019 253 9.1
Page 254
LATESTVERSION:9.1.1- RELEASENOTES
CreatingandManagingQueriesYoucreatequeriesonthecacheserverbyobtaininga QueryService methodandmanagethemthroughtheresulting Query object.The Region interfacehasseveralshortcutquerymethods.
The newQuery methodforthe Query interfacebindsaquerystring.Byinvokingthe execute method,thequeryissubmittedtothecacheserverandreturns SelectResults ,whichiseitheraResultSet ora StructSet .
The QueryService methodistheentrypointtothequerypackage.ItisretrievedfromtheCacheinstancethrough Cache::getQueryService .IfyouareusingthePoolAPIyoumustobtaintheQueryService fromthepoolsandnotfromthecache.
QueryA Query isobtainedfroma QueryService method,whichisobtainedfromthecache.The Query interfaceprovidesmethodsformanagingthecompilationandexecutionofqueries,andforretrievinganexistingquerystring.
Youmustobtaina Query objectforeachnewquery.ThefollowingexampledemonstratesthemethodusedtoobtainanewinstanceofQuery :
QueryPtrnewQuery(constchar*querystr);
RegionShortcutQueryMethodsThe Region interfacehasseveralshortcutquerymethods.Alltakea query predicatewhichisusedinthe WHERE clauseofastandardquery.SeeWHEREClauseformoreinformation.Eachofthefollowingexamplesalsosetthequeryresponsetimeoutto10secondstoallowsufficienttimefortheoperationtosucceed.
The query methodretrievesacollectionofvaluessatisfyingthequerypredicate.Thiscallretrievesactiveportfolios,whichinthesampledataaretheportfolioswithkeysand 333 :
SelectResultsPtrresults=regionPtr->query("status'active'");
The selectValue methodretrievesonevalueobject.Inthiscall,yourequesttheportfoliowith IDABC-1 :
SerializablePtrport=region->selectValue("ID='ABC-1'");
The existsValue methodreturnsabooleanindicatingifanyentryexiststhatsatisfiesthepredicate.Thiscallreturnsfalsebecausethereisnoentrywiththeindicatedtype:
boolentryExists=region->existsValue("'type'='QQQ'");
©CopyrightPivotalSoftwareInc,2013-2019 254 9.1
Page 255
LATESTVERSION:9.1.1- RELEASENOTES
QueryResultSetsSelectResults.Executesthequeryonthecacheserverandreturnstheresultsaseithera ResultSet oraStructSet.
SelectResultsIterator.Iteratesovertheitemsavailableina ResultSet or StructSet .
ResultSet.Obtainedafterexecutinga Query ,whichisobtainedfroma QueryService thatisobtainedfromaCacheclass.
StructSet.Usedwhena SELECT statementreturnsmorethanonesetofresults.Thisisaccompaniedbya Struct ,whichprovidesthe StructSet definitionandcontainsitsfieldvalues.
©CopyrightPivotalSoftwareInc,2013-2019 255 9.1
Page 256
LATESTVERSION:9.1.1- RELEASENOTES
QueryCodeSamplesReturningResultSetAPIexamplesdemonstratemethodsforreturning ResultSet forbothbuilt-inanduser-defineddatatypes.
QueryReturnsaResultSetforaBuilt-InDataType
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");QueryPtrquery=qrySvcPtr->newQuery("selectdistinctpkidfrom/portfolios");//specify10secondsforthequerytimeoutperiodSelectResultsPtrresults=query->execute(10);if(results==NULLPTR){printf("\nNoresultsreturnedfromtheserver");}
//obtainingahandletoresultsetResultSetPtrrs(dynamic_cast<ResultSet*>(results.ptr()));if(rs==NULLPTR){printf("\nResultSetisnotobtained\n");return;}//iteratingthroughtheresultsetusingrowindex.for(int32_trow=0;row<rs->size();row++){SerializablePtrser((*rs)[row]);CacheableStringPtrstr(dynamic_cast<CacheableString*>(ser.ptr()));if(str!=NULLPTR){printf("\nstringcolumncontains-%s\n",str->asChar());}}
QueryReturnsaResultSetforaUser-DefinedDataType
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");constchar*querystring="selectdistinct*from/portfolios";QueryPtrquery=qrySvcPtr->newQuery(querystring);//specify10secondsforthequerytimeoutperiodSelectResultsPtrresults=query->execute(10);if(results==NULLPTR){printf("\nNoresultsreturnedfromtheserver");}//obtainingahandletoresultsetResultSetPtrrs(dynamic_cast<ResultSet*>(results.ptr()));if(rs==NULLPTR){printf("\nResultSetisnotobtained\n");return;}//iteratingthroughtheresultsetusingiterators.SelectResultsIteratoriter=rs->getIterator();while(iter.hasNext()){SerializablePtrser=iter.next();PortfolioPtrport(dynamic_cast<Portfolio*>(ser.ptr()));if(port!=NULLPTR){printf("\nPortfolioobjectis-%s\n",port->toString()->asChar());}}//endofrows
©CopyrightPivotalSoftwareInc,2013-2019 256 9.1
Page 257
LATESTVERSION:9.1.1- RELEASENOTES
QueryCodeSamplesReturningStructSetTheseexamplesreturna StructSet forbuilt-inanduser-defineddatatypes, Struct objects,andcollections.
QueryReturningaStructSetforaBuilt-InDataType
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");constchar*querystring="SELECTDISTINCTID,pkid,status,getTypeFROM/portfolios";QueryPtrquery=qrySvcPtr->newQuery(querystring);//specify10secondsforthequerytimeoutperiodSelectResultsPtrresults=query->execute(10);if(results==NULLPTR){printf("\nNoresultsreturnedfromtheserver");}//obtainingahandletoresultsetStructSetPtrss(dynamic_cast<StructSet*>(results.ptr()));if(ss==NULLPTR){printf("\nStructSetisnotobtained\n");return;}//iteratingthroughtheresultsetusingindexes.for(int32_trow=0;row<ss->size();row++){Struct*siptr=(Struct*)dynamic_cast<Struct*>(((*ss)[row]).ptr());if(siptr==NULL){printf("\nstructisempty\n");continue;
}//iteratethroughfieldsnowfor(int32_tfield=0;field<siptr->length();field++){SerializablePtrfieldptr((*siptr)[field]);if(fieldptr==NULLPTR){printf("\nnulldatareceived\n");}CacheableStringPtrstr(dynamic_cast<CacheableString*>(fieldptr.ptr()));if(str==NULLPTR){printf("\nfieldisofsomeothertype\n");}else{printf("\nDatafor%sis%s",siptr->getFieldName(field),str->asChar());}}//endofcolumns}//endofrows
ReturningStructObjects
©CopyrightPivotalSoftwareInc,2013-2019 257 9.1
Page 258
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");constchar*querystring="SELECTDISTINCTderivedProjAttrbts,key:p.keyFROM""/Portfolios.entriesp,(SELECTDISTINCTx.ID,myPos.secIdFROM""/Portfoliosx,x.positions.valuesASmyPos)derivedProjAttrbtsWHERE""p.value.ID=derivedProjAttrbts.IDANDderivedProjAttrbts.secId='IBM'";QueryPtrquery=qrySvcPtr->newQuery(querystring);//specify10secondsforthequerytimeoutperiodSelectResultsPtrresults=query->execute(10);if(results==NULLPTR){printf("\nNoresultsreturnedfromtheserver");}//obtainingahandletoresultsetStructSetPtrss(dynamic_cast<StructSet*>(results.ptr()));if(ss==NULLPTR){printf("\nStructSetisnotobtained\n");return;}//iteratingthroughtheresultsetusingindexes.for(int32_trow=0;row<ss->size();row++){Struct*siptr=(Struct*)dynamic_cast<Struct*>(((*ss)[row]).ptr());if(siptr==NULL){printf("\nstructisempty\n");}//iteratethroughfieldsnowfor(int32_tfield=0;field<siptr->length();field++){SerializablePtrfieldptr((*siptr)[field]);if(fieldptr==NULLPTR){printf("\nnulldatareceived\n");}CacheableStringPtrstr(dynamic_cast<CacheableString*>(fieldptr.ptr()));if(str!=NULLPTR){printf("\nDatafor%sis%s",siptr->getFieldName(field),str->asChar());}else{StructPtrsimpl(dynamic_cast<Struct*>(fieldptr.ptr()));if(simpl==NULLPTR){printf("\nfieldisofsomeothertype\n");continue;}printf("\nstructreceived%s\n",siptr->getFieldName(field));for(int32_tinner_field=0;inner_field<simpl->length();inner_field++){SerializablePtrinnerfieldptr((*simpl)[inner_field]);if(innerfieldptr==NULLPTR){printf("\nfieldofstructisNULL\n");}CacheableStringPtrstr(dynamic_cast<CacheableString*>(innerfieldptr.ptr()));if(str!=NULLPTR){printf("\nDatafor%sis%s",simpl->getFieldName(inner_field),str->asChar());}else{printf("\nsomeotherobjecttypeinsidestruct\n");}}}}//endofcolumns}//endofrows
ReturningCollections
©CopyrightPivotalSoftwareInc,2013-2019 258 9.1
Page 259
QueryServicePtrqrySvcPtr=cachePtr->getQueryService("examplePool");constchar*querystring="selectdistinctID,namesfrom/portfolios";QueryPtrquery=qrySvcPtr->newQuery(querystring);SelectResultsPtrresults=query->execute(10);if(results==NULLPTR){printf("\nNoresultsreturnedfromtheserver");}//obtainahandletoresultsetStructSetPtrss(dynamic_cast<StructSet*>(results.ptr()));if(ss==NULLPTR){printf("\nStructSetisnotobtained\n");return;}//iteratethroughtheresultsetusingindexes.for(int32_trow=0;row<ss->size();row++){Struct*siptr=dynamic_cast<Struct*>(((*ss)[row]).ptr());if(siptr==NULL){printf("\nstructisempty\n");continue;}//iteratethroughfieldsnowfor(int32_tfield=0;field<siptr->length();field++){SerializablePtrfieldptr((*siptr)[field]);if(fieldptr==NULLPTR){printf("\nnulldatareceived\n");}CacheableStringPtrstr(dynamic_cast<CacheableString*>(fieldptr.ptr()));if(str!=NULLPTR){printf("\nDatafor%sis%s",siptr->getFieldName(field),str->asChar());}else{CacheableObjectArrayPtrcoa(dynamic_cast<CacheableObjectArray*>(fieldptr.ptr()));if(coa==NULLPTR){printf("\nfieldisofsomeothertype\n");continue;}printf("\nobjectArrayreceived%s\n",siptr->getFieldName(field));for(unsignedarrlen=0;arrlen<(uint32_t)coa->length();arrlen++){printf("\nDatafor%sis%s",siptr->getFieldName(field),coa->operator[](arrlen)->toString()->asChar());}}}//endofcolumns}//endofrows
©CopyrightPivotalSoftwareInc,2013-2019 259 9.1
Page 260
LATESTVERSION:9.1.1- RELEASENOTES
ContinuousQueryingContinuousQueryingdescribeshowtoimplementcontinuousqueryinginthePivotalGemFirenativeclientsothatC++and.NETclientscanrunqueriesagainsteventsintheGemFirecacheserverregion.ItalsodescribesmainfeaturesandthenativeclientCQAPI.
HowContinuousQueryingWorksC++and.NETclientsregisterinterestineventsusingsimplequeryexpressions.Eventsaresenttoclientlistenersthatyoucanprogramtodowhateveryourapplicationrequires.
ImplementingaContinuousQueryYoucanspecifyCQsforanyclientregion.
ManagingContinuousQueriesThissectiondiscusseshowtoaccessandmanageyourCQsfromyourclient.Thecallsdiscussedhereareallexecutedspecificallyforthecallingclient.AclientcannotaccessormodifytheCQsbelongingtoanotherclient.
CQAPIandMainFeaturesThischapterdocumentstheprimarynativeclientAPIforCQmanagement.
©CopyrightPivotalSoftwareInc,2013-2019 260 9.1
Page 261
LATESTVERSION:9.1.1- RELEASENOTES
HowContinuousQueryingWorksC++and.NETclientsregisterinterestineventsusingsimplequeryexpressions.Eventsaresenttoclientlistenersthatyoucanprogramtodowhateveryourapplicationrequires.
OverviewofCQOperationsYousubscribetoserver-sideeventsusingSQL-typequeryfiltering.Thenativeclientsendsaquerytotheserversideforexecutionandreceivestheeventsthatsatisfythecriteria.
Forexample,inaregionstoringstockmarkettradeorders,youcanretrieveallordersoveracertainpricebyrunningaCQwithaquerylikethis:
SELECT*FROM/tradeOrdertWHEREt.price>100.00
WhentheCQisrunning,theserversendstheclientallneweventsthataffecttheresultsofthequery.Onthenativeclientside,listenersprogrammedbyyoureceiveandprocessincomingevents.Fortheexamplequeryon /tradeOrder ,youmightprogramalistenertopusheventstoaGUIwherehigher-pricedordersaredisplayed.CQeventdeliveryusestheclient/serversubscriptionframeworkdescribedinClienttoServerConnectionProcess.
CQsdonotupdatethenativeclientregion.Thisisincontrasttootherserver-to-clientmessaging,suchastheupdatessenttosatisfyinterestregistrationandresponsestogetrequestsfromtheclient.CQsarenotificationtoolsfortheCQlisteners,whichcanbeprogrammedinanywayyourapplicationrequires.
WhenaCQisrunningagainstaserverregion,eachentryeventisevaluatedagainsttheCQquerybythethreadthatupdatestheservercache.Ifeithertheoldorthenewentryvaluesatisfiesthequery,thethreadputsa CqEvent intheclient’squeue.The CqEvent containsinformationfromtheoriginalcacheevent,plusinformationspecifictotheCQ’sexecution.Oncereceivedbytheclient,the CqEvent ispassedtothe onEvent methodofall CqListeners definedfortheCQ.
LogicalArchitectureandDataFlowClientscanexecuteanynumberofCQs,witheachCQgivenanynumberoflisteners.Thisfigureshowsthelogicalarchitectureofcontinuousquerying.
ThenextfigureshowsthetypicalCQdataflowwhenentriesareupdatedintheservercache.Adescriptionofthedataflowfollows,alongwithadescriptionofCQstateandlifecycle.
1. Entryeventscometotheserver’scachefromanysource:theserveroritspeers,distributionfromremotesites,orupdatesfromaclient.
2. Foreachevent,theserver’sCQexecutorframeworkchecksforamatchwiththeCQsithasrunning.
3. IftheoldornewentryvaluesatisfiesaCQquery,aCQeventissenttotheCQ’slistenersontheclientside.EachlistenerfortheCQgetstheevent.Intheprecedingfigure:
©CopyrightPivotalSoftwareInc,2013-2019 261 9.1
Page 262
BothnewandoldpricesforentryXsatisfytheCQquery,sothateventissentindicatinganupdatetothequeryresults.TheoldpriceforentryYsatisfiedthequery,soitwaspartofthequeryresults.TheinvalidationofentryYmeansthatitdoesnotsatisfythequery.Becauseofthis,theeventissentindicatingthatitisdestroyedinthequeryresults.ThepriceforthenewlycreatedentryZdoesnotsatisfythequery,sonoeventissent.
Theregionoperationsdonottranslatedirectlytospecificqueryoperations,andthequeryoperationsdonotspecificallydescribetheregionevents.Instead,eachqueryoperationdescribeshowitscorrespondingregioneventaffectsthequeryresults.Formoreinformation,seeCqEventObject.
StateandLifeCycleACQhasthreepossiblestatesthatcanbeaccessedfromtheclientbycalling CqQuery.getState .
STOPPED .TheCQhasbeencreatedbutnotyetexecuted,orithasbeenexplicitlystoppedfromexecuting.ThestoppedCQusessystemresources.YoustartorrestarttheCQbycallingtheexecutemethodon CqQuery .
RUNNING .TheCQisbeingexecutedontheserverforalleventsintheregionreferencedbythequery.ResultsaresenttoallclientlistenersassociatedwiththeCqQuery
CLOSED .TheCQisclosedandisnotusingsystemresources.Invokingan execute or stop methodonclosed CqQuery throwsanexception.
TypicalCQlifecycle
1. TheclientcreatestheCQ.Thissetsupeverythingforrunningthequeryandprovidestheclientwitha CqQuery object,butdoesnotexecutetheCQ.Atthispoint,thequeryisinaSTOPPED state,readytobeclosedorrun.
2. TheclientrunstheCQwithanAPIcalltooneofthe CqQuery execute* methods.Thisputsthequeryintoa RUNNING stateontheclientandontheserver.
3. TheCQisclosedbyaclientcallto CqQuery.close .Thisde-allocatesallresourcesinusefortheCQontheclientandserver.Atthispoint,thecyclecouldbeginagainwiththecreationofanew CqQuery instance.
©CopyrightPivotalSoftwareInc,2013-2019 262 9.1
Page 263
LATESTVERSION:9.1.1- RELEASENOTES
ImplementingaContinuousQueryYoucanspecifyCQsforanyclientregion.
Herearethehigh-levelstepsforimplementingacontinuousquery,withlinkstomoredetailedinformationinthischapter.
1. MakesureyoursystemisconfiguredproperlytorunCQs.SeeConfiguringforContinuousQuerying.
2. Decidewhatdatatotrackontheserverandwriteyourqueries.UseyourcriteriafortrackingdatachangestowriteyourCQqueries.SeeWritingtheContinuousQuery
3. DeterminehowtohandletheCQeventsontheclientandwriteyourlisteners.EachCQcanhaveanynumberoflisteners.InadditiontoyourcoreCQlisteners,youmighthavelistenersthatyouuseforallCQstotrackstatisticsorothergeneralinformation.SeeWritingtheCQListener.
4. The CqEvent objectcontainsinformationabouttheCQevent.
5. WritetheclientcodetoputthequeriesandtheirlistenersintonamedCQqueriesandexecutethequeries.Makesureyouclosethequeriesifyourclientnolongerneedsthemandwhentheclientexits.SeeRunningtheContinuousQueryCode.
6. CQExecutionOptions.
7. WhenanErrorOccursinaRunningCQ.
8. Runyourcode,monitorandtuneasneeded.
©CopyrightPivotalSoftwareInc,2013-2019 263 9.1
Page 264
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringYourSystemforContinuousQueryingThecontinuousquery(CQ)functionalityrequiresstandardclient/serverdistributedsystemandcacheconfigurationsettings.
Theclientregionmustuseapoolwithsubscription-enabledsettotrue.
IfyouwantyourCQstobehighlyavailable,configureyourserversforhighavailabilityasdescribedinConfiguringHighlyAvailableServers intheserverdocumentation.Whenyourserversarehighlyavailable,CQsareregisteredonprimaryandsecondaryservers,andserverfailoverisperformedwithoutanyinterruptiontoCQmessaging.CQeventsmessagingusesthesamequeuesusedforserver-to-clientmessaging.Note:WhenCQisusedwithhighavailability,theoverheadforCQsishigherthanforthekey-basedinterestlistregistration.CQsareexecutedontheprimaryandallsecondaryservers,sotheyrequiremoreoverallserverprocessing.
ToobtainalistofalldurableCQsregisteredontheserver,usetheQueryService.getAllDurableCqsFromServer API.
IfyouwantyourCQstobedurable,configureyournativeclientsfordurablemessaging.Whenyourclientsaredurable,youcancreatedurableCQswhoseeventsaremaintainedduringclientdisconnectsandreplayedfortheclientwhenitreconnects.TheprocessanddataflowparticulartodurableCQsisdescribedinDurableClientMessaging
©CopyrightPivotalSoftwareInc,2013-2019 264 9.1
Page 265
LATESTVERSION:9.1.1- RELEASENOTES
WritingtheContinuousQueryEachCQusesaqueryandanynumberoflisteners.Thequeryfilterstheeventsontheserverandthelistenerhandlestheeventsthatmakeitthroughthequeryfilter.Withthequeryandthelistenerinhand,youcancreateandexecuteyourquerythroughtheAPI.
ThisisthebasicsyntaxfortheCQquery:
SELECT*FROM/fullRegionPath[iterator][WHEREclause]
TheCQquerymustsatisfythestandardGemFirenativeclientqueryingspecificationsdescribedinRemoteQuerying.Italsomustsatisfytheserestrictions:
The FROM clausemustcontainonlyasingleregionspecification,withoptionaliteratorvariable.
Thequerymustbea SELECT expressiononly,precededbyzeroormore IMPORT statements.Thismeansthequerycannotbeastatementlike /tradeOrder.name or(SELECT * from /tradeOrder).size .
TheCQquerycannotuse:
CrossregionjoinsDrill-downsintonestedcollectionsDISTINCT
ProjectionsBindparameters
Queriesnotmeetingtheseconstraintsgeneratean UnsupportedOperationException fromthe QueryServicenewCq method.
©CopyrightPivotalSoftwareInc,2013-2019 265 9.1
Page 266
LATESTVERSION:9.1.1- RELEASENOTES
WritingtheCQListenerorCQStatusListenerThefollowingC++andC#.NETexamplesshowhowyoumightprogramasimple CqListener or CqStatusListener toupdateadisplayscreenbasedontheCQeventsitreceives.
Thelistenerretrievesthe queryOperation andentrykeyandvaluefromthe CqEvent ,thenupdatesthescreenaccordingtotheoperationtypeprovidedin queryOperation .
CQeventsdonotchangeyourclientcache.Theyareprovidedasaneventserviceonly.ThisallowsyoutohaveanycollectionofCQswithoutstoringlargeamountsofdatainyourregions.IfyouneedtopersistinformationfromCQevents,programyourlistenertostoretheinformationwhereitmakesthemostsenseforyourapplication.
Beverycarefulifyouchoosetoupdateyourcachefromyour CqListener .IfyourlistenerupdatestheregionthatisqueriedinitsownCQ,theupdatemaybeforwardedtotheserver.IftheupdateontheserversatisfiesthesameCQ,itmaybereturnedtothesamelistenerthatdidtheupdate,whichcouldputyourapplicationintoaninfiniteloop.ThissamescenariocouldbeplayedoutwithmultipleregionsandmultipleCQsifthelistenersareprogrammedtoupdateeachother’sregions.
CqListenerImplementation(C++)
//CqListenerclassclassTradeEventListener:publicCqListener{public:voidonEvent(constCqEvent&cqEvent){//OperationassociatedwiththequeryopCqOperation::CqOperationTypequeryOperation=cqEvent.getQueryOperation();//keyandnewvaluefromtheeventCacheableKeyPtrkey=cqEvent.getKey();TradeOrderPtrtradeOrder=dynCast<TradeOrderPtr>(cqEvent.getNewValue());if(queryOperation==CqOperation::OP_TYPE_UPDATE){//updatedataonthescreenforthetradeorder...}elseif(queryOperation==CqOperation::OP_TYPE_CREATE){//addthetradeordertothescreen...}elseif(queryOperation==CqOperation::OP_TYPE_DESTROY){//removethetradeorderfromthescreen...}}voidonError(constCqEvent&cqEvent){//handletheerror}voidclose(){//closetheoutputscreenforthetrades...}}
CqListenerImplementation(C#.NET)
©CopyrightPivotalSoftwareInc,2013-2019 266 9.1
Page 267
//CqListenerclasspublicclassTradeEventListener:ICqListener{voidOnEvent(CqEvent<TKey,TResult>^ev){//OperationassociatedwiththequeryopCqOperationTypequeryOperation=ev.getQueryOperation();//keyandnewvaluefromtheeventICacheableKeykey=ev.getKey();CacheableStringkeyStr=keyasCacheableString;IGeodeSerializableval=ev.getNewValue();TradeOrdertradeOrder=valasTradeOrder;if(queryOperation==CqOperationType.OP_TYPE_UPDATE){//updatedataonthescreenforthetradeorder//...}elseif(queryOperation==CqOperationType.OP_TYPE_CREATE){//addthetradeordertothescreen//...}elseif(queryOperation==CqOperationType.OP_TYPE_DESTROY){//removethetradeorderfromthescreen//...}}publicvoidOnError(CqEvent<TKey,TResult>^ev){//handletheerror}//FromCacheCallbackpublicvoidClose(){//closetheoutputscreenforthetrades//...}}
WritingaCqStatusListenerIfyouneedyourCQstodetectwhethertheyareconnectedtoanyoftheserversthathostitssubscriptionqueues,implementaCqStatusListener insteadofa CqListener .
CqStatusListener extendsthecurrent CqListener ,allowingaclienttodetectwhenaCQisconnectedand/ordisconnectedfromtheserver(s).The onCqConnected() methodwillbeinvokedwhentheCQisconnected,andwhentheCQhasbeenreconnectedafterbeingdisconnected.The onCqDisconnected() methodwillbeinvokedwhentheCQisnolongerconnectedtoanyservers.
Takingtheexamplesfromabove,wecaninsteadimplementa CqStatusListener .
Whenyouinstallthe CqStatusListener ,yourlistenerwillbeabletodetectitsconnectionstatustotheserversthatitisquerying.
CqStatusListenerImplementation(C++)
classMyCqStatusListener:publicCqStatusListener{uint8_tm_id;uint32_tm_numInserts;uint32_tm_numUpdates;uint32_tm_numDeletes;uint32_tm_numEvents;uint32_tm_cqsConnectedCount;uint32_tm_cqsDisconnectedCount;
public:uint8_tgetId(){returnm_id;}uint32_tgetNumInserts(){returnm_numInserts;}uint32_tgetNumUpdates(){returnm_numUpdates;}uint32_tgetNumDeletes(){returnm_numDeletes;}uint32_tgetNumEvents(){
©CopyrightPivotalSoftwareInc,2013-2019 267 9.1
Page 268
{returnm_numEvents;}uint32_tgetCqsConnectedCount(){returnm_cqsConnectedCount;}uint32_tgetCqsDisConnectedCount(){returnm_cqsDisconnectedCount;}MyCqStatusListener(uint8_tid):m_id(id),m_numInserts(0),m_numUpdates(0),m_numDeletes(0),m_numEvents(0),m_cqsDisconnectedCount(0),m_cqsConnectedCount(0){}inlinevoidupdateCount(constCqEvent&cqEvent){m_numEvents++;switch(cqEvent.getQueryOperation()){caseCqOperation::OP_TYPE_CREATE:{m_numInserts++;break;}caseCqOperation::OP_TYPE_UPDATE:{m_numUpdates++;break;}caseCqOperation::OP_TYPE_DESTROY:{m_numDeletes++;break;}default:break;}}voidonEvent(constCqEvent&cqe){updateCount(cqe);}voidonError(constCqEvent&cqe){updateCount(cqe);}voidclose(){}voidonCqDisconnected(){//Thisiscalledwhenthecqlosesconnectionwithallservers.m_cqsDisconnectedCount++;}voidonCqConnected(){//Thisiscalledwhenthecqestablishesaconnectionwithaserver.m_cqsConnectedCount++;}voidclear(){m_numInserts=0;m_numUpdates=0;m_numDeletes=0;m_numEvents=0;m_cqsDisconnectedCount=0;m_cqsConnectedCount=0;}};
CQStatusListenerImplementation(C#.NET)
©CopyrightPivotalSoftwareInc,2013-2019 268 9.1
Page 269
publicclassMyCqStatusListener<TKey,TResult>:ICqStatusListener<TKey,TResult>{#regionPrivatemembersprivateboolm_failedOver=false;privateUInt32m_eventCountBefore=0;privateUInt32m_errorCountBefore=0;privateUInt32m_eventCountAfter=0;privateUInt32m_errorCountAfter=0;privateUInt32m_CqConnectedCount=0;privateUInt32m_CqDisConnectedCount=0;#endregion
#regionPublicaccessorspublicMyCqStatusListener(intid){}publicvoidfailedOver(){m_failedOver=true;}publicUInt32getEventCountBefore(){returnm_eventCountBefore;}publicUInt32getErrorCountBefore(){returnm_errorCountBefore;}publicUInt32getEventCountAfter(){returnm_eventCountAfter;}publicUInt32getErrorCountAfter(){returnm_errorCountAfter;}publicUInt32getCqConnectedCount(){returnm_CqConnectedCount;}publicUInt32getCqDisConnectedCount(){returnm_CqDisConnectedCount;}#endregion
publicvirtualvoidOnEvent(CqEvent<TKey,TResult>ev){if(m_failedOver==true)m_eventCountAfter++;elsem_eventCountBefore++;}publicvirtualvoidOnError(CqEvent<TKey,TResult>ev){if(m_failedOver==true)m_errorCountAfter++;elsem_errorCountBefore++;}publicvirtualvoidClose(){}publicvirtualvoidOnCqConnected(){m_CqConnectedCount++;}publicvirtualvoidOnCqDisconnected(){m_CqDisConnectedCount++;}publicvirtualvoidClear(){m_eventCountBefore=0;m_errorCountBefore=0;m_eventCountAfter=0;m_errorCountAfter=0;m_CqConnectedCount=0;m_CqDisConnectedCount=0;}}
©CopyrightPivotalSoftwareInc,2013-2019 269 9.1
Page 270
©CopyrightPivotalSoftwareInc,2013-2019 270 9.1
Page 271
LATESTVERSION:9.1.1- RELEASENOTES
CqEventObjectThe CqEvent objectcontainsinformationabouttheCQevent.
Entrykeyandnewvalue.
BaseoperationthattriggeredtheCQeventintheserver.
CqQuery objectassociatedwiththisCQevent.
QueryoperationassociatedwiththisCQevent.Thisoperationdescribesthechangeaffectedtothequeryresultsbythecacheevent.Possiblevaluesare:
CREATE ,whichcorrespondstothestandarddatabase INSERT operation.UPDATE
DESTROY ,whichcorrespondstothestandarddatabase DELETE operation.
Thistabledescribesthequeryoperationbasedonwhethertheoldandnewentryvaluesintheregionentryeventsatisfythequerycriteria.
Table1.QueryOperationBasedonOldandNewEntryValues
OldEntryValue NewEntryValue QueryOperation
Novalueorvaluedoesnotsatisfythequerycriteria.
Novalue(operationis invalidate or destroy )orvaluedoesnotsatisfythequery.
Valuesatisfiesthequery.
N/A-noevent
create
Valuesatisfiesthequery
Novalue(operationis invalidate or destroy )orvaluedoesnotsatisfythequery.
Valuesatisfiesthequery.
destroy
update
Table1.QueryOperationBasedonOldandNewEntryValues
Youcanusethequeryoperationtodecidewhattodowiththe CqEvent inyourlisteners.Forexample,a CqListener thatdisplaysqueryresultsonscreenmightstopdisplayingtheentry,startdisplayingtheentry,orupdatetheentrydisplaydependingonthequeryoperation.
©CopyrightPivotalSoftwareInc,2013-2019 271 9.1
Page 272
LATESTVERSION:9.1.1- RELEASENOTES
RunningtheContinuousQueryCodeCreateyourCQfromaninstanceoftheQueryService.Oncecreated,theCQismaintainedprimarilythroughtheCqQueryinterface.ThefollowingtwoC++andC#examplesshowthebasiccallsintheCQlifecycle.
CQCreation,Execution,andClose(C++)
//GetcacheandqrySvcPtr-refstolocalcacheandQueryService//Createclient/tradeOrderregionconfiguredtotalktotheserver//CreateCqAttributeusingCqAttributeFactoryCqAttributesFactorycqf;//CreatealistenerandaddittotheCQattributes//callbackdefinedbelowCqListenerPtrtradeEventListener(newTradeEventListener());QueryServicePtrqrySvcPtr=cachePtr->getQueryService();"cqf.addCqListener(tradeEventListener);CqAttributesPtrcqa=cqf.create();//NameoftheCQanditsquerychar*cqName="priceTracker";char*queryStr="SELECT*FROM/tradeOrdertwheret.price>100.00";//CreatetheCqQueryCqQueryPtrpriceTracker=qrySvcPtr->newCq(cqName,queryStr,cqa);try{//ExecuteCQpriceTracker->execute();}catch(Exception&ex){ex.printStackTrace();}//NowtheCQisrunningontheserver,sendingCqEventstothelistener...}//EndoflifefortheCQ-clearupresourcesbyclosingpriceTracker->close()
CQCreation,Execution,andClose(C#.NET)
//GetcacheandqueryService-refstolocalcacheandQueryService//Createclient/tradeOrderregionconfiguredtotalktotheserver//CreateCqAttributeusingCqAttributeFactoryCqAttributesFactorycqf=newCqAttributesFactory();//CreatealistenerandaddittotheCQattributes//callbackdefinedbelowICqListenertradeEventListener=newTradeEventListener();cqf.addCqListener(tradeEventListener);CqAttributescqa=cqf.create();//NameoftheCQanditsqueryStringcqName="priceTracker";StringqueryStr="SELECT*FROM/tradeOrdertwheret.price>100.00";QueryServicequeryService=cache.GetQueryService();//CreatetheCqQueryCqQuerypriceTracker=queryService.newCq(cqName,queryStr,cqa,true);try{//ExecuteCQpriceTracker.execute();}catch(Exceptionex){//handleexception}//NowtheCQisrunningontheserver,sendingCqEventstothelistener//...}//EndoflifefortheCQ-clearupresourcesbyclosingpriceTracker.close();
©CopyrightPivotalSoftwareInc,2013-2019 272 9.1
Page 273
LATESTVERSION:9.1.1- RELEASENOTES
CQExecutionOptionsCQexecutioncanbedonewithorwithoutaninitialresultsetbycalling CqQuery.Execute or CqQuery.ExecuteWithInitialResults .Theinitial SelectResults returnedfrom ExecuteWithInitialResults
thesameastheoneyouwouldgetifyouranthequeryadhocbycalling QueryService.NewQuery.Execute ontheservercache,butwiththekeyadded.
IndividualCQsareexecutedusing CqQueryexecute* methods.YoucanalsoexecuteallCQsfortheclientorforaregionthroughtheclient QueryService .CQsthatarerunningcanbestoppedorclosed.
IfyouaremanagingadatasetfromtheCQresults,youcaninitializethesetbyiteratingovertheresultsetandthenupdatingitfromyourlistenersaseventsarrive.Forexample,youmightpopulateanewscreenwithinitialresultsandthenupdatethescreenfromalistener.
Justaswiththestandalonequery,theinitialresultsrepresentsapossiblymovingsnapshotofthecache.Ifthereareupdatestotheserverregionwhiletheresultsetisbeingcreated,theresultsetandthesubsequentevent-by-eventCQqueryexecutionmightmisssomeevents.
©CopyrightPivotalSoftwareInc,2013-2019 273 9.1
Page 274
LATESTVERSION:9.1.1- RELEASENOTES
WhenanErrorOccursinaRunningCQWhenanerroroccursinCQexecutionontheserver,specificinformationontheerroritselfisstoredintheserver’slogfile.Anexceptionispassedtotheclient,andtheclientthrowsanexception.
TheserverlogwillcontainanerrormessageindicatinganerrorwhileprocessingCQ,likethis:
[error2007/12/1812:03:18.903PST<RMITCPConnection(2)-192.0.2.0>tid=0x18]ErrorwhileprocessingCQontheevent,key:key-1,CqName:testCQEvents_0,ClientId:identity(carlos(3249):52623/35391,connection=1,durableAttributes=null)Error:Nopublicattributenamed'ID'wasfoundinclassjava.lang.Object
ErrorsinCQexecutionareusuallycausedbydataerrors,suchasinvalidobjecttypesthatarestoredintheserverregion.Inthiscase,thequeryistryingtoreadintoanobjectoftypePortfolioforanentrywhereanemptyobjecthasbeenstored.Youcanavoidthesetypesoferrorsbyplacingconstraintsontheregionentries,orbyotherwisecontrollingthetypesofobjectsstoredinyourserverregions.
©CopyrightPivotalSoftwareInc,2013-2019 274 9.1
Page 275
LATESTVERSION:9.1.1- RELEASENOTES
ManagingContinuousQueriesThissectiondiscusseshowtoaccessandmanageyourCQsfromyourclient.Thecallsdiscussedhereareallexecutedspecificallyforthecallingclient.AclientcannotaccessormodifytheCQsbelongingtoanotherclient.
ThissectiondiscusseshowtoaccessandmanageyourCQsfromyourclient.Thecallsdiscussedhereareallexecutedspecificallyforthecallingclient.AclientcannotaccessormodifytheCQsbelongingtoanotherclient.
Fordetailedmethodusage,seetheAPIdocumentationfortheC++API orthe.NETAPI .
AccessingCQsandCQStatisticsYoucanusethe QueryServicegetCq* methodstoaccessasinglenamedCQ,anarrayofallCQsregistered,andanarrayofallCQsregisteredintheclient.YoucanusetheCqEvent.getCqmethodtoaccesstheCQusedtoproducea CqEvent .
CQruntimestatisticsareavailablefortheclientthroughthe CqServiceStatistics and CqStatistics interfacesdescribedunderCQAPIandMainFeatures.YoucangetinformationontheeventsgeneratedbyaspecificCQfromthe CqStatistics objectreturnedby CqQuery.GetStatistics .Youcangethigher-levelinformationabouttheCQstheclienthasregistered,running,andsoon,fromthe CqServiceStatistics objectreturnedby QueryService.GetCqStatistics .
Clientstatisticsareforthesingleclientonly.Theserver’spertaintoallclientswithCQsonthisserver.
ModifyingCQAttributesYoucanmodifytheattributesforanexistingCQusingthemethodsprovidedby CqQuery.GetCqAttributesMutator .Theattributesconsistofalistoflisteners.
StoppingandClosingCQsYoustopindividualCQswiththe CqQuerystop method.YoucanstopallCQsfortheclientthroughthe QueryService .StoppedCQsareinthesamestateasnewCQsthathavenotyetbeenexecuted.YoucancloseorexecuteastoppedCQ.
YoucloseindividualCQswiththe CqQueryclose method.YoucanalsocloseallCQsfortheclientthroughthe QueryService .ClosedCQscannotbeexecuted.CQsarealsoclosedinthefollowingcases:
TheclientclosesitscacheafterclosingallofitsCQs–Closingtheclientcacheclosesthe QueryService andallassociatedCQsontheclientandserver.
Theclientdisconnectsfromitsserver–Thismightbebecauseofanetworkoutageorsomeotherfailure.Whenaclientdisconnects,allCQscreatedbytheclientareremovedfromtheserverandputintoa CLOSED stateontheclient.
Theserverregionisdestroyed–Whenaserverregionisdestroyed,allassociatedCQsarealsocleanedupontheserverandtheregiondestroyeventissenttotheclient.Ontheclient,the CqListener.Close methodiscalledforallCQsontheregion.
GettingAllDurableCQsRegisteredwiththeServerToobtainalistofalldurableCQsregisteredontheserver,usetheQueryService.getAllDurableCqsFromServer API.
©CopyrightPivotalSoftwareInc,2013-2019 275 9.1
Page 276
LATESTVERSION:9.1.1- RELEASENOTES
CQAPIandMainFeaturesThischapterdocumentstheprimarynativeclientAPIforCQmanagement.
ThePivotalGemFirenativeclientAPIallowsyourclientstocreateandmanageCQs.(TheserversidedoesnothaveanAPI.)Continuousqueryingprovidesnativeclientquerysyntax,events-basedmanagement,integrationwithclient/serverarchitecture,activequeryexecution,andinterestcriteriabasedondatavalues.Forcompleteinformationontheclassesandinterfacesdescribedhere,seethedocumentationfortheC++API orthe.NETAPI .
Apache.Geode.Client.Cache
OnlyC#versionsofCQAPIinterfaces,classes,andmethodsareshownhere(example: CqQuery.execute ).ThecodeexamplesdemonstratebothC++andC#versions.
QueryService interface.Providesmethodsthatenableyouto:
CreateanewCQandspecifywhetheritisdurable(availablefordurableclients)ExecuteaCQwithorwithoutaninitialresultListalltheCQsregisteredbytheclientCloseandstopCQsGetahandleon CqStatistics fortheclient
Yourun QueryService CQmethodsagainsttheservercache.TheQueryServicecanbeobtainedfromthecacheorfromapool.
CqQuery interface.Providesmethodsformanagingacontinuousqueryafteritiscreatedthroughthe QueryService .ThisinterfaceisusedtypicallytobeginandendCQexecutionandtoretrieveotherCQ-relatedobjectssuchasCQattributes,CQstatistics,andCQstate.
CqListener applicationplug-ininterface.Handlescontinuousqueryeventsaftertheyoccur.Youprogramthisinterface.
CqEvent interface.ProvidesallinformationsentfromtheserverabouttheCQevent,whichispassedtotheCQ’s CqListener methods.
CqState interface.Providesinformationonthestateofa CqQuery ,throughthegetStatemethodofthe CqQuery instance.
CqAttributes,CqAttributesFactory,CqAttributesMutator interfaces.AllowyoutomanageCQattributes.Theattributesconsistof CqListener plug-inspecifications.
CqStatistics,CqServiceStatistics interfaces.AllowyoutoaccessstatisticsinformationforasingleCQandforthequeryservice’smanagementofCQsasawhole.Fordetailsonstatistics,seeStatisticsAPI.
MainFeaturesofContinuousQueryingContinuousqueryinginthenativeclienthasthefollowingfeatures:
StandardGemFirenativeclientquerysyntaxandsemantics.CQqueriesareexpressedinthesamelanguageusedforothernativeclientqueries.SeeRemoteQuerying
StandardGemFireevents-basedmanagementofCQevents.TheeventhandlingusedtoprocessCQeventsisbasedonthestandardGemFireeventhandlingframework.TheCQListenerinterfaceissimilartoApplicationPlug-InsandApplicationCallbacks.
Completeintegrationwiththeclient/serverarchitecture.CQfunctionalityusesexistingserver-to-clientmessagingmechanismstosendevents.Alltuningofyourserver-to-clientmessagingalsotunesthemessagingofyourCQevents.IfyoursystemisconfiguredforhighavailabilitythenyourCQsarehighlyavailable,withseamlessfailoverprovidedincaseofserverfailure(seeHighAvailabilityforClient-to-ServerCommunication).Ifyourclientsaredurable,youcanalsodefineanyofyourCQsasdurable(seeDurableClientMessaging
Interestcriteriabasedondatavalues.CQqueriesarerunagainsttheregion’sentryvalues.ComparethistoregisterinterestbyreviewingRegisteringInterestforEntries
Activequeryexecution.Onceinitialized,thequeriesonlyoperateonneweventsinsteadofontheentireregiondataset.Eventsthatchangethequeryresultaresenttotheclientimmediately.
©CopyrightPivotalSoftwareInc,2013-2019 276 9.1
Page 277
LATESTVERSION:9.1.1- RELEASENOTES
UsingConnectionPoolsUsingConnectionPoolsdescribeshowconnectionpoolsachieveloadbalancingfortheclientanddescribeshowtoconfigureconnectionpoolsasserverlocatorsorasalistofservers.
HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.
ConfiguringPoolsApoolcanbeconfiguredaslocatorsorasalistofservers.
©CopyrightPivotalSoftwareInc,2013-2019 277 9.1
Page 278
LATESTVERSION:9.1.1- RELEASENOTES
HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.
TheconnectionpoolAPIsupportsconnectingtoserversthroughserverlocatorsordirectlyconnectingtoservers.
ServerLocatorsServerlocatorscontinuouslymonitorserveravailabilityandserverloadinformation.Theclientisconfiguredwithalistofserverlocatorsandconsultsaserverlocatortorequestaconnectiontoaserverinthedistributedsystem.
ConnectionPoolsClientscontainconnectionpools.Eachregionisassociatedwithaconnectionpoolusingaregionattribute,andoperationsontheregionuseconnectionsfromtherespectivepools.
DiscoveringLocatorsDynamicallyAbackgroundthreadperiodicallyqueriesthelocatorforanyotherlocatorsjoiningthedistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 278 9.1
Page 279
LATESTVERSION:9.1.1- RELEASENOTES
ServerLocatorsServerlocatorscontinuouslymonitorserveravailabilityandserverloadinformation.Theclientisconfiguredwithalistofserverlocatorsandconsultsaserverlocatortorequestaconnectiontoaserverinthedistributedsystem.
Locatorsprovideclientswithdynamicserverdiscoveryandserverloadbalancing.Theygiveclientsconnectioninformationfortheserverwiththeleastloadatanygiventime.
Serverlocatorsprovidethesemainfeatures:
Automateddiscoveryofserversandlocators.Addingandremovingserversorlocatorsismadeeasyaseachclientdoesnotrequirealistofserverstobeconfiguredatthetimeofpoolcreation.
Clientloadrebalancing.Serverlocatorsgiveclientsdynamicserverinformationandprovideserverloadrebalancingafterserversdepartorjointhesystem.
Highavailability.Whenaclient/serverconnectionreceivesanexception,theconnectionisautomaticallyfailedovertoanotheravailableconnectioninthepool.Redundancyisalsoprovidedforclientsubscriptions.
Alternatively,youcanconfigureapoolstaticallywithalistofendpoints.Whenthepoolsarestaticallyconfigured,around-robinloadbalancingpolicyisusedtodistributeconnectionsacrosstheservers.
©CopyrightPivotalSoftwareInc,2013-2019 279 9.1
Page 280
LATESTVERSION:9.1.1- RELEASENOTES
ConnectionPoolsClientscontainconnectionpools.Eachregionisassociatedwithaconnectionpoolusingaregionattribute,andoperationsontheregionuseconnectionsfromtherespectivepools.
Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.Eachpoolhasaminimumandmaximumnumberofconnections.
Eachcacheoperationthatrequiresserverconnectivityobtainsaconnectionfromthepoolfortheservergroupthattheoperationaffects,performstheoperationusingtheconnection,andreturnstheconnectiontothepool.Ifthepoolsizeislessthanthemaximumnumberofconnectionsandallconnectionsareinuse,theconnectionpoolcreatesanewconnectionandreturnsit.Ifthepoolisatthemaximumnumberofconnections,thatthreadblocksuntilaconnectionbecomesavailableora free-connection-timeout occurs.Ifa free-connection-timeoutoccurs,an AllConnectionsInUse exceptionisthrown.
Theconnectionpoolhasaconfigurabletimeoutperiodthatisusedtoexpireidleconnections.Theidleconnectionsareexpireduntilthepoolhastheminimumnumberofconnections.Amonitoringthreadexpiresidleconnections,addssufficientconnectionstobringupthecounttominimum,andclosesconnectionswhoselifetimehasbeenexceeded.Seetheload-conditioning-interval and idle-timeout attributesofthe<pool> element.Aseparatethread(ping)testseachconnectedendpointforitsstatusandiftheendpointisnotreachable,thethreadclosesallconnectionsthathavebeenmadetotheendpoint.Seethe ping-interval attributeofthe<pool>element>.
Figure:LogicalArchitectureofClient/ServerConnections
Whenaconnectionreceivesanexception,theoperationisfailedovertoanotherconnectionfromthepool.Thefailovermechanismobtainstheendpointtofailovertofromthelocatororfromthespecifiedendpointlistinthepool.
©CopyrightPivotalSoftwareInc,2013-2019 280 9.1
Page 281
LATESTVERSION:9.1.1- RELEASENOTES
DiscoveringLocatorsDynamicallyAbackgroundthreadperiodicallyqueriesthelocatorforanyotherlocatorsjoiningthedistributedsystem.
However,iflocatorA(towhichtheclientisconnected)goesdownbeforeitdiscoverslocatorB,locatorBisneverdiscoveredeventhoughitisaliveandtheclientreceivesaNoLocatorsAvailable exception.
Oneconnectionisattachedtoeveryapplicationthreadthatis local totherespectivethread.Thisisknownasathreadlocalconnection.
Inthiscase,toperformanycacheoperationtheclientisnotrequiredtoobtainaconnectionfrompool.Insteadthethreadlocalconnectionoftheclientisused.
Athreadlocalconnectioncanbereleasedbyinvokingthe Pool::releaseThreadLocalConnection() method.Thereleasedconnectionisreturnedtothepool.Ifthenumberofthreadsislargerthanthenumberof max-connections ,theclientthrowsan AllConnectionsInUseException afterthe free-connection-timeout lapses,unlessthe Pool::releaseThreadLocalConnection() methodisusedjudiciously.
Ifaconnectionexpiresortheservergoesdownonwhichtheconnectionwasestablished,athreadlocalconnectionisimmediatelyreplacedwithagoodconnectionobtainedfromthepool.
©CopyrightPivotalSoftwareInc,2013-2019 281 9.1
Page 282
LATESTVERSION:9.1.1- RELEASENOTES
ConfiguringPoolsApoolcanbeconfiguredaslocatorsorasalistofservers.
Youconfigurelocator,server,andpoolsettingsdeclarativelyintheclient’s cache.xml fileorprogrammaticallythroughthe PoolFactory method.Youcreateaninstanceofthrough PoolManager .
NativeClientPoolAPIThenativeclientAPIallowsyourclientstocreateandmanageconnectionpools.TheserversidedoesnothaveanAPI.
PoolConfigurationExampleandSettingsConnectionpoolsrequirestandardclient/serverdistributedsystemandcacheconfigurationsettings.Youmustalsoconfiguresettingsforthelocator,server,andpoolelements.
SubscriptionPropertiesEachconnectionpoolhasasinglesubscriptionconnectionthatcanbetoanyserverthatmatchestherequirementsoftheconnectionpool.
RunningtheConnectionPoolCodeExamplesdemonstrateasimpleproceduretocreateapoolfactoryandthencreateapoolinstanceinC++andC#.Theyalsohelpyoutoexecuteaquery.
©CopyrightPivotalSoftwareInc,2013-2019 282 9.1
Page 283
LATESTVERSION:9.1.1- RELEASENOTES
NativeClientPoolAPIThenativeclientAPIallowsyourclientstocreateandmanageconnectionpools.TheserversidedoesnothaveanAPI.
ThissectionliststheprimarynativeclientAPIforpoolmanagement.Forcompleteinformationontheclassesandinterfacesdescribedhere,seetheAPIdocumentation.
Note:OnlyC#versionsofPoolAPIinterfaces,classes,andmethodsareshownthroughoutthetextinthissection(example: Pool.GetQueryService() ).ThecodeexamplesdemonstratebothC++andC#versions.
Apache.Geode.Client.Cache
Pool interface.APItoretrievepoolattributes.
PoolFactory interface.APItoconfigurepoolattributes.
PoolManager interface.APItocreatea PoolFactory objectandtofindthepoolobjects.
AttributesFactory class.Hasanewmethod setPoolname whichassignsapooltoaregion.Operationsperformedontheconfiguredregionuseconnectionsfromthepool.
Note:Aregioncanhaveapoolattachedtoit.Apoolmayhavemultipleregionsattachedtoit.
©CopyrightPivotalSoftwareInc,2013-2019 283 9.1
Page 284
LATESTVERSION:9.1.1- RELEASENOTES
PoolConfigurationExampleandSettingsConnectionpoolsrequirestandardclient/serverdistributedsystemandcacheconfigurationsettings.Youmustalsoconfiguresettingsforthelocator,server,andpoolelements.
Locator.Hostandportwhereaserverlocatorislistening.
Server.Hostandportwhereaserverislistening.
Pool.Client/serverconnectionpool.
Theexampleshowsadeclarativepoolconfiguration.Followingtheexampleisatablethatdescribestheattributesthatcanbeconfigured.
Example—DeclarativePoolConfigurationThisexampleshowsadeclarativepoolconfiguration.
Note:Youcreateaninstanceof PoolFactory through PoolManager .
<poolfree-connection-timeout="12345"idle-timeout="5555"load-conditioning-interval="23456"max-connections="7"min-connections="3"name="test_pool_1"ping-interval="12345"read-timeout="23456"retry-attempts="3"server-group="ServerGroup1"socket-buffer-size="32768"statistic-interval="10123"subscription-ack-interval="567"subscription-enabled="true"subscription-message-tracking-timeout="900123"subscription-redundancy="0"thread-local-connections="true"><locatorhost="localhost"port="34756"/></pool>
PoolAttributes
free-connection-timeoutNumberofmilliseconds(ms)thattheclientwaitsforafreeconnectionif max-connectionslimitisconfiguredandallconnectionsareinuse.
10000ms
idle-timeoutNumberofmillisecondstowaitforaconnectiontobecomeidleforloadbalancing 5000ms
load-conditioning-intervalIntervalinwhichthepoolcheckstoseeifaconnectiontoaspecificservershouldbemovedtoadifferentservertoimprovetheloadbalance.
300000ms(5minutes)
max-connections
Maximumnumberofconnectionsthatthepoolcancreate.Ifallconnectionsareinuse,anoperationrequiringaclient-toserver-connectionisblockeduntilaconnectionisavailableorthe free-connection-timeout isreached.Ifsetto-1,thereisnomaximum.Thesettingmustindicateacapgreaterthan min-connections .
-1
min-connections Numberofconnectionsthatmustbecreatedinitially. 5
name Poolname.
Intervalbetweenpingingtheservertoshowtheclientisalive,setinmilliseconds.Pings
Note:
Ifyouusethissettingtocapyourpoolconnections,disablethepoolattributepr-single-hop-enabled .Leavingsinglehopenabledcanincreasethrashingandlowerperformance.
©CopyrightPivotalSoftwareInc,2013-2019 284 9.1
Page 285
ping-interval
Intervalbetweenpingingtheservertoshowtheclientisalive,setinmilliseconds.Pingsareonlysentwhenthe ping-interval elapsesbetweennormalclientmessages.Thismustbesetlowerthantheserver’s maximum-time-between-pings .
10000ms
pr-single-hop-enabledSettingusedforsingle-hopaccesstopartitionedregiondataintheserversforsomedataoperations.SeePartitionResolver.Seenotein thread-local-connections below.
True
read-timeoutNumberofmillisecondstowaitforaresponsefromaserverbeforetheconnectiontimesout.
10000
retry-attempts Numberoftimestoretryanoperationafteratime-outorexceptionforhighavailability.Ifsetto-1,thepooltrieseveryavailableserveronceuntilitsucceedsorhastriedallservers.
-1
server-group Servergroupfromwhichtoselectconnections.Ifnotspecified,theglobalgroupofallconnectedserversisused.
empty
socket-buffer-size Sizeofthesocketbuffer,inbytes,oneachconnectionestablished. 32768
statistic-intervalDefaultfrequency,inmilliseconds,withwhichtheclientstatisticsaresenttotheserver.Avalueof -1 indicatesthatthestatisticsarenotsenttotheserver.
-1
subscription-ack-intervalNumberofmillisecondstowaitbeforesendinganacknowledgmenttotheserverabouteventsreceivedfromthesubscriptions.
100
subscription-enabled Whethertoestablishaservertoclientsubscription. False
subscription-message-tracking-timeoutNumberofmillisecondsforwhichmessagessentfromaservertoaclientaretracked.Thetrackingisdonetominimizeduplicateevents.
90000
subscription-redundancyRedundancyforserversthatcontainsubscriptionsestablishedbytheclient.Avalueof-1 causesallavailableserversinthespecifiedgrouptobemaderedundant.
0
thread-local-connections
Whethertheconnectionsmusthaveaffinitytothethreadthatlastusedthem.
False
update-locator-list-intervalAnintegernumberofmillisecondsdefiningtheintervalbetweenlocatorlistupdates.Ifthevalueislessthanorequalto0,theupdatewillbedisabled.
5000
Note:
Tosetthisto true ,alsoset pr-single-hop-enabled to false .A true valueinpr-single-hop-enabled automaticallyassignsa false valueto thread-local-connections …
©CopyrightPivotalSoftwareInc,2013-2019 285 9.1
Page 286
LATESTVERSION:9.1.1- RELEASENOTES
SubscriptionPropertiesEachconnectionpoolhasasinglesubscriptionconnectionthatcanbetoanyserverthatmatchestherequirementsoftheconnectionpool.
Whenaclientregistersinterestforaregion,iftheconnectionpooldoesnotalreadyhaveasubscriptionchannel,theconnectionpoolsendsamessagetotheserverlocator,andtheserverlocatorchoosesserverstohostthequeueandreturnthoseservernamestotheclient.Theclientthencontactsthechosenserversandasksthemtocreatethequeue.
Theclientmaintainsatleastoneconnectionwitheachserverhostingaqueue.Iftheserverdoesnotdetectanyconnectionsfromanon-durableclient,itdropstheclientqueueandclosesallartifactsfortheclient.Forinformationaboutdurableclientsubscriptions,seeDurableClientMessaging.
RequestingaSubscriptionRegionQueueTheclient-to-serverlocatorrequestisashortlivedTCPrequest.Theclientsendsamessagewith:
TheclientID.
(Optional)targetservergroup.
Numberofredundantcopies.
Serverstoexcludefromtheresults.Thislistisusediftheclientcannotconnecttoaserverandneedstorequestanewone.
Theserverlocatorrespondswithalistofservers.Theclientisresponsibleforcontactingtheprimaryandsecondariesandaskingthemtohostthequeue.
Fordurablesubscriptions,theserverlocatormustbeabletolocatetheserversthathostthequeuesforthedurableclient.Whenadurableclientsendsarequest,theserverlocatorqueriesalltheavailableserverstoseeiftheyarehostingthesubscriptionregionqueueforthedurableclient.Iftheserverislocated,theclientisconnectedtotheserverhostingthesubscriptionregionqueue.
©CopyrightPivotalSoftwareInc,2013-2019 286 9.1
Page 287
LATESTVERSION:9.1.1- RELEASENOTES
RunningtheConnectionPoolCodeExamplesdemonstrateasimpleproceduretocreateapoolfactoryandthencreateapoolinstanceinC++andC#.Theyalsohelpyoutoexecuteaquery.
Theexamplescreateapoolwithlocators.Ensurethatyoucreateapoolwithlocatorsorendpoints,butnotboth.Thefirstexampledemonstratescreatingapoolbyaddinglocators.Thesecondexampledemonstratescreatingapoolbyaddingservers.Formoreinformation,seetheexampleintheQuickStartGuide.
ConnectionPoolCreationandExecutionUsingC++
PropertiesPtrprptr=Properties::create();systemPtr=CacheFactory::createCacheFactory(prptr);
cachePtr=systemPtr->create();PoolFactoryPtrpoolFacPtr=PoolManager::createFactory();//tocreatepooladdeitherendpointsoraddlocatorsorservers//poolwithendpoint,addingtopoolfactory//poolFacPtr->addServer("localhost",12345/*portnumber*/);//poolwithlocator,addingtopoolfactorypoolFacPtr->addLocator("localhost",34756/*portnumber*/);PoolPtrpptr=NULLPTR;if((PoolManager::find("examplePool"))==NULLPTR){//Poolwiththisnamedoesnotexistpptr=poolFacPtr->create("examplePool");}RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);regionPtr=regionFactory->setPoolName("examplePool")->create("regionName");QueryServicePtrqs=cachePtr->getQueryService("examplePool");
ConnectionPoolCreationandExecutionUsingC#.NET
Propertiesprop=Properties.Create();CacheFactorycacheFactory=CacheFactory.CreateCacheFactory(prop);Cachecache=cacheFactory.Create();
PoolFactorypoolFact=PoolManager.CreateFactory();//tocreatepooladdeitherendpointsoraddlocators//poolwithendpoint,addingtopoolfactory.poolFact.AddServer("localhost",40404/*portnumber*/);//poolwithlocator,addingtopoolfactory//poolFact.AddLocator("hostname",15000/*portnumber*/);Poolpool=null;if(PoolManager.Find("poolName")==null){pool=poolFact.Create("poolName");}intloadConditInterval=pool.LoadConditioningInterval;RegionFactoryregionFactory=cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY);IRegion<string,string>region=regionFactory.SetPoolName(poolName).Create<string,string>(regionName);
©CopyrightPivotalSoftwareInc,2013-2019 287 9.1
Page 288
LATESTVERSION:9.1.1- RELEASENOTES
TransactionsThissectiondescribeshowtransactionsworkontheclientside.Itprovidesexamplesforrunning,suspending,andresumingtransactions.
Clienttransactionsrunontheservertier.Theclientusesaserverdelegatethatrunsthetransactionasitwouldalocaltransaction.Thus,thekeytorunningclienttransactionsliesinmakingsuretheserverisproperlyconfiguredandprogrammed.ForcompleteinformationabouttransactionsintheJavaserver,seetheserverdocumentationatTransactionsprovidesdetailedinformationincludingserverdatarequirements,interactionsoftransactionswithotheroperationsrunningontheservertier,server-sideapplicationplug-inswithtransactions,andqueryingwithtransactions.
HowClientTransactionsWorkThesyntaxforwritingclienttransactionsisthesameaswithserverorpeertransactions,butwhenaclientperformsatransaction,thetransactionisdelegatedtoaserverthatbrokersthetransaction.
RunningaClientTransactionBeforeyoucanrunaclienttransaction,youmustconfigureyourclientsandservers;defineyourserverregionsforyourtransactions;anddefineyourclientregions.
SuspendingandResumingTransactionsTheabilitytosuspendandresumetransactionsisusefulwhenathreadmustperformoperationsthatshouldnotbepartofthetransactionbeforethetransactioncancomplete.
©CopyrightPivotalSoftwareInc,2013-2019 288 9.1
Page 289
LATESTVERSION:9.1.1- RELEASENOTES
HowClientTransactionsWorkThesyntaxforwritingclienttransactionsisthesameaswithserverorpeertransactions,butwhenaclientperformsatransaction,thetransactionisdelegatedtoaserverthatbrokersthetransaction.
RoleofServerDelegatesinTransactionsTheclientcanruntransactionsontheJavacacheserver,usingaserverdelegatetoactuallyrunthetransactioncode.
Forinformationontransactionrequirementsandactivitiesontheserverside,seetheserverdocumentationatTransactions .
Note:Theclientcacheblocksuntilthetransactionissuccessfullycommitted.However,theblockisremovedifthetransactionissuspended.
Dependingonwherethedataresides,theservertransactiondelegatemayornotbethesamememberthathoststhetransaction.Thisisthesameasfortransactionsrunbytheservers,butforserver-runtransactions,thereisnodelegate.Thereisjustthememberthatisdirectlyrunningitsowntransactioncode.
Inthisfigure,theapplicationcodeontheclientmakeschangestodataentriesYandZwithinatransaction.Theserverdelegatethatperformsthetransaction,M1,doesnothosttheprimarycopyofthedatabeingmodified.ThetransactiontakesplaceonserverM2,wherethedataresides.
Figure:TransactionRunFromaClient
Tomaintaincacheconsistency,thelocalclientcacheisnotaccessibleduringatransactionasitmayreflectinformationinconsistentwiththetransactioninprogress.Whenthetransactioncompletes,thelocalcacheisaccessibleagain.
Inadditiontothefailureconditionscommontoalltransactions,clienttransactionscanalsofailifthetransactiondelegatefails.Ifthedelegateperformingthetransactionfails,thetransactioncodethrowsa TransactionException .
ClientTransactionAPIsTheAPIfordistributedtransactionshasthefamiliarrelationaldatabasemethods, begin , commit ,and rollback .TherearealsoAPIsavailabletosuspendandresumetransactions.
The.NETclassesforexecutingtransactionsare:
Apache.Geode.Client.CacheTransactionManager
Apache.Geode.Client.TransactionId
©CopyrightPivotalSoftwareInc,2013-2019 289 9.1
Page 290
LATESTVERSION:9.1.1- RELEASENOTES
RunningaTransactionBeforeyoucanrunatransaction,youmustconfigureyourclientsandservers,defineyourserverregionsforyourtransactions,anddefineyourclientregions.
1. Retrievethetransactionmanager.C++example
CacheTransactionManagerPtrtxManager=cache->getCacheTransactionManager();
C#.NETexample
CacheTransactionManagertxManager=cache.CacheTransactionManager;
2. Runthetransaction.(Detailedstepsfollowtheexamples.)C++example
TransactionIdPtrtid;txManager->begin();//..doworktid=txManager->suspend();//followingcodecanberunfromanother//threadthathasaccesstotidtry{txManager->resume(tid);//..doworktid=txManager->commit();}catch(constCommitConflictException&e){//..onexception}
C#.NETexample
TransactionIdtid;txManager.Begin();//..doworktid=txManager.Suspend();//followingcodecanberunfromanother//threadthathasaccesstotidtry{txManager.Resume(tid);//..doworktxManager.Commit();}catch(CommitConflictExceptione)
Starteachtransactionwitha begin operation.Ifthetransactionrunsonserverregionsthatareamixofpartitionedandreplicatedregions,performthefirsttransactionoperationonapartitionedregion.Thissetstheserverdatahostfortheentiretransaction.IfyouareusingPRsingle-hop,single-hopwillbeappliedasusualtothisfirstoperation.Runtheoperationsthatyouwantincludedinthetransaction.Endthetransactionwitha commit ora rollback .Note:Donotleaveanytransactioninanuncommittedandunrolledbackstateunlessyouhavesuspendedthetransaction.Transactionsthathavenotbeenexplicitlysuspendeddonottimeout,sowillremaininthesystemforthelifeofyourapplication.
3. Reviewallofyourclientcodeforcompatibilitywithtransactions.
Whenyoucommitatransaction,whilethecommitistakingplace,thechangesarevisibleinthecache.Thisisalsoknownastransitioncommits.Thisprovidesbetterperformancethanlockingeverythingtodothetransactionupdates,butitmeansthatanotherprocessaccessingdatausedinthetransactionmightgetsomedatainthepre-transactionstateandsomeinthepost-transactionstate.
Forexample,keys1and2arewrittentoinatransactionsobothoftheirvalueschangefromAtoB.Inanotherthread,itispossibletoreadkey1withvalueBandkey2withvalueA,whilethetransactionisbeingcommitted.ThiscanhappenbecauseofhowGemFireperformsreads.Thischoicesacrificesatomicvisibilityinfavorofperformance.Readsdonotblockwrites.Writesdonotblockreads.
Becausetheclientcachewaitsduringtransactionexecution,andclientregionsarenotdistributed,theonlyactivitiesthatinteractwithaclienttransactionarethosethatoccurontheserver.
©CopyrightPivotalSoftwareInc,2013-2019 290 9.1
Page 291
LATESTVERSION:9.1.1- RELEASENOTES
SuspendingandResumingTransactionsTheabilitytosuspendandresumetransactionsisusefulwhenathreadmustperformoperationsthatshouldnotbepartofthetransactionbeforethetransactioncancomplete.
Whenatransactionissuspended,itlosesthetransactionalviewofthecache.Noneofthepreviousoperations(beforecallingsuspend)arevisibletothethread.Subsequentlyanyoperationsthatareperformedbythethreaddonotparticipateinthesuspendedtransaction.
Whenatransactionisresumed,theresumingthreadassumesthetransactionalview.Atransactionthatissuspendingonamembermustberesumedonthesamemember.Beforeresumingatransaction,youmaywanttocheckifthetransactionexistsonthememberandwhetheritissuspended.Youmayoptionallyusethe tryResume method.
Ifthememberwiththeprimarycopyofthedatacrashes,thetransactionalviewthatappliedtothatdataislost.Thesecondarymemberforthedatacannotresumetransactionssuspendedonthecrashedmember.Youneedtotakeremedialstepstoretrythetransactiononanewprimarycopyofthedata.
Ifasuspendedtransactionisnottouchedforaperiodoftime,GemFirecleansitupautomatically.Bydefault,thetimeoutforasuspendedtransactionis30minutesandcanbeconfiguredbyusingthe suspended-tx-timeout propertyofthe geode.properties file.Thesuspendedtransactiontimeoutvalueisspecifiedinmilliseconds.
SeeRunningaClientTransactionforcodeexamplesthatshowahowtosuspendandresumeatransaction.
©CopyrightPivotalSoftwareInc,2013-2019 291 9.1
Page 292
LATESTVERSION:9.1.1- RELEASENOTES
FunctionExecutionThissectiondescribeshowtoexecuteapplicationfunctionstoachievelinearscalability.Itexplainshowfunctionexecutionworksandlistsspecificusecases.
Functionexecutioncanbeusedonlyalongwiththepoolfunctionality.FormoreinformationaboutthepoolAPI,seeUsingConnectionPools.OnlyC++versionsofFunctionExecutionAPIinterfaces,classes,andmethods(like FunctionService::onRegion )areshownintext.ThecodeexamplesshowC++andC#.
UnderstandingData-AwareFunctionRoutingAchievinglinearscalabilityispredicateduponbeingabletohorizontallypartitiontheapplicationdatasuchthatconcurrentoperationsbydistributedapplicationscanbedoneindependentlyacrosspartitions.
HowFunctionsExecuteThissectiondiscussesthebasicfunctionexecutionprocess,howhighlyavailablefunctionsexecuteafterafailure,andtheexecutionscenariosfordata-dependentanddata-independentfunctions.
ExecutingFunctionsUsingthefunctionexecutionservice,youcanexecuteapplicationfunctionsonasingleservermember,inparallelonasubsetofservermembers,orinparallelonallservermembersofadistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 292 9.1
Page 293
LATESTVERSION:9.1.1- RELEASENOTES
UnderstandingData-AwareFunctionRoutingAchievinglinearscalabilityispredicateduponbeingabletohorizontallypartitiontheapplicationdatasuchthatconcurrentoperationsbydistributedapplicationscanbedoneindependentlyacrosspartitions.
Inotherwords,iftheapplicationrequirementsfortransactionscanberestrictedtoasinglepartition,andalldatarequiredforthetransactioncanbecolocatedtoasingleservermemberorasmallsubsetofservermembers,thentrueparallelismcanbeachievedbyvectoringtheconcurrentaccessorstotheever-growingnumberofpartitions.
Mostscalableenterpriseapplicationsgrowindatavolume,wherethenumberofdataitemsmanagedratherthanthesizeofindividualitemsgrowsovertime.Iftheabovelogicholds(especiallytrueforOLTPclassapplications),thenwecanderivesizablebenefitsbyroutingthedata-dependentapplicationcodetothefabricmemberhostingthedata.Thisroutingofapplicationcodetothedataofinterestiscalleddata-awarefunctionrouting,orbehaviorrouting.
©CopyrightPivotalSoftwareInc,2013-2019 293 9.1
Page 294
LATESTVERSION:9.1.1- RELEASENOTES
HowFunctionsExecuteThissectiondiscussesthebasicfunctionexecutionprocess,howhighlyavailablefunctionsexecuteafterafailure,andtheexecutionscenariosfordata-dependentanddata-independentfunctions.
HowFunctionsExecute1. Thecallingclientapplicationrunsthe execute methodonthe Execution object.Theobjectmustalreadyberegisteredontheservers.
2. Thefunctionisinvokedonallserverswhereitneedstorun.Thelocationsaredeterminedbythe FunctionService on* methodcalls,regionconfiguration,andanyfilters.
3. Ifthefunctionhasresults,theresultisreturnedtothe AddResult methodcallina ResultCollector object.
4. Theclientcollectsresultsusingtheresultcollector getResult .
HowHighlyAvailableFunctionsExecuteafteraFailureIfafailureoccursinfunctionexecution,theerrorisreturnedtothecallingapplication.Youcancodeforhighavailabilityfor onRegion functionsthatreturnaresult,sothefunctionisautomaticallyretried.Forinformationonsettingthisupontheserverside,seeExecutingaFunctioninPivotalGemFire .Touseahighlyavailablefunction,theclientmustcalltheresultscollector getResult method.Whenanexecutionerroroccursoramembercrasheswhileexecuting,thesystemdoesthefollowing:
1. Waitsforallcallstoreturn.
2. Setsabooleanindicatingareexecutionisbeingdone.
3. Callstheresultcollector’s clearResults method.
4. Executesthefunction.
Thesystemretriestheexecutionuptothenumberspecifiedintheserverpool’s retryAttempts setting.Ifthefunctioncontinuestofail,thefinalexceptionisreturnedtothemethod.
Data-IndependentFunctionExecutionThefigureshowsthesequenceofeventsforadata-independentfunctionexecutedagainstallavailableservers.
Figure:Data-IndependentFunctionInvokedfromaClient
Data-DependentFunctionExecutionThefigureshowsadata-dependentfunctionrunbyaclient.Thespecifiedregionisconnectedtotheserversystem,sothefunctionautomaticallygoestheretorunagainstallserversholdingdatafortheregion.
©CopyrightPivotalSoftwareInc,2013-2019 294 9.1
Page 295
Figure:Data-DependentFunctionInvokedFromaClient
Thisshowsthesamedata-dependentfunctionwiththeaddedspecificationofasetofkeysonwhichtorun.Serversthatdon’tholdanyofthekeysareleftoutofthefunctionexecution.
Figure:Data-DependentFunctionwithFilterInvokedfromaClient
Thisscenariodemonstratesthestepsinacalltoahighlyavailablefunction.Thecallfailsthefirsttimeononeoftheparticipatingserversandissuccessfullyrunasecondtimeonallservers.
Figure:HighlyAvailableData-DependentFunctionwithFailureonFirstExecutions
©CopyrightPivotalSoftwareInc,2013-2019 295 9.1
Page 296
©CopyrightPivotalSoftwareInc,2013-2019 296 9.1
Page 297
LATESTVERSION:9.1.1- RELEASENOTES
ExecutingFunctionsUsingthefunctionexecutionservice,youcanexecuteapplicationfunctionsonasingleservermember,inparallelonasubsetofservermembers,orinparallelonallservermembersofadistributedsystem.
Intheseprocedures,itisassumedthatyouhavedefinedyourclientandserverregions,andthatyouhavecodedandconfiguredyourserverstorunyourfunctions.Seetheserver-sidefunctionexecutioninformationatFunctionExecution .
RunningtheFunctionInthissectionyoucreatean Execution objectanduseitsmethodstodefineandrunthefunction.Torunafunctionwithhighavailability,youcall getResult fromtheresultscollectorreturnedfromthe execute method.
ProgrammingtoGetFunctionResultsGemFireprovidesadefaultresultcollector.Ifyouneedspecialresultshandling,codeacustom ResultsCollector implementationtoreplacetheprovideddefault.UsetheExecution::withCollector methodtodefineyourcustomcollector.
SolutionsandUseCasesThefunctionexecutionserviceprovidessolutionsforvariousapplicationusecases.
©CopyrightPivotalSoftwareInc,2013-2019 297 9.1
Page 298
LATESTVERSION:9.1.1- RELEASENOTES
RunningtheFunctionInthissectionyoucreatean Execution objectanduseitsmethodstodefineandrunthefunction.Torunafunctionwithhighavailability,youcall getResult fromtheresultscollectorreturnedfromthe execute method.
ConfiguringandRunningaFunctionYouspecifythemembersthatrunthefunctionand,optionally,thedatasetoverwhichthefunctionsrun.
Servers.Executethefunctioninasingleserverorasetofservers,specifiedbytheserverpool.Tospecifydatasetsforthistypeoffunction,passargumentsintothefunction.
Dataset.Specifyaregionandpossiblyasetofkeysonwhichtorun.
Ineveryclientwhereyouwanttoexecutethefunctionandprocesstheresults:
1. Useoneofthe FunctionServiceon* methodstocreatean Execution object.The on* methods, onRegion , onServer and onServers ,definethehighestlevelwherethefunctionisrun.Ifyouuse onRegion youcanfurthernarrowyourrunscopebysettingkeyfilters.Thefunctionrunusing onRegion isadatadependentfunction–theothersaredata-independentfunctions.Youcanrunadatadependentfunctionagainstcustompartitionedandcolocatedpartitionedregions.Fromtheclient,providetheappropriatekeysetstothefunctioncall.
2. Usethe Execution objectasneededforadditionalfunctionconfiguration.Youcan:
Provideasetofdatakeysto withFilter tonarrowtheexecutionscope.Thisworksonlyfor onRegion Execution objects.Providefunctionargumentsto withArgs .Defineacustom ResultCollector to withCollector .SeeProgrammingtoGetFunctionResults.
3. Callthe Execution objectexecutemethodtorunthefunction.
4. Torunafunctionwithhighavailability,call getResult fromtheresultscollectorreturnedfrom execute .Callingahighlyavailablefunctionwithoutusing getResult disablesthehighavailabilityfunctionality.
RunningaFunctiononaRegion(C++)
regPtr0=initRegion();ExecutionPtrexc=FunctionService::onRegion(regPtr0);CacheableVectorPtrroutingObj=CacheableVector::create();charbuf[128];boolgetResult=true;
sprintf(buf,"VALUE--%d",10);CacheablePtrvalue(CacheableString::create(buf));
sprintf(buf,"KEY--%d",100);CacheableKeyPtrkey=CacheableKey::create(buf);regPtr0->put(key,value);
sprintf(buf,"KEY--%d",100);CacheableKeyPtrkey1=CacheableKey::create(buf);routingObj->push_back(key1);
CacheablePtrargs=routingObj;CacheableVectorPtrexecuteFunctionResult=exc->withFilter(routingObj)->withArgs(args)->execute(func)->getResult();
RunningaFunctiononaServerPool(C++)
©CopyrightPivotalSoftwareInc,2013-2019 298 9.1
Page 299
pptr=PoolManager::find(poolName);ExecutionPtrexc=FunctionService::onServer(cache);CacheableVectorPtrroutingObj=CacheableVector::create();charbuf[128];boolgetResult=true;sprintf(buf,"VALUE--%d",10);CacheablePtrvalue(CacheableString::create(buf));
sprintf(buf,"KEY--%d",100);CacheableKeyPtrkey=CacheableKey::create(buf);regPtr0->put(key,value);
sprintf(buf,"KEY--%d",100);CacheableKeyPtrkey1=CacheableKey::create(buf);routingObj->push_back(key1);
CacheablePtrargs=routingObj;CacheableVectorPtrexecuteFunctionResult=exc->withArgs(args)->execute(func)->getResult();
RunningaFunctiononaRegion(C#.NET)
IRegion<string,string>fregion=regionFactory.Create<string,string>("exampleRegion");for(inti=0;i<34;i++){fregion.Put("KEY--"+i,"VALUE--"+i,null);}
object[]routingObj=newobject[17];intj=0;for(inti=0;i<34;i++){if(i%2==0)continue;routingObj[j]="KEY--"+i;j++;}objectargs0=true;BooleangetResult=true;//datadependentfunctionexecution--getfunctionwithresultExecution<object>exc=Generic.FunctionService.OnRegion<string,string,object>(fregion);Generic.IResultCollectorrc=exc.WithArgs((IGeodeSerializable)args0).WithFilter((IGeodeSerializable[])routingObj).Execute(getFuncName);object[]executeFunctionResult=rc.GetResult();
RunningaFunctiononaServerPool(C#.NET)
exc=Generic.FunctionService.OnServer<object>(cache);List<object>args1=newList<object>();for(inti=0;i<routingObj.Length;i++){Console.WriteLine("routingObj[{0}]={1}.",i,(routingObj[i]asstring));args1.Add(routingObj[i]);}rc=exc.WithArgs((IGeodeSerializable)args1).Execute(getFuncIName);executeFunctionResult=rc.GetResult();Console.WriteLine("ononeserver:resultcount={0}.",executeFunctionResult.Length);
©CopyrightPivotalSoftwareInc,2013-2019 299 9.1
Page 300
LATESTVERSION:9.1.1- RELEASENOTES
ProgrammingtoGetFunctionResultsTheclientmayusethedefaultresultcollector.Iftheclientneedsspecialresultshandling,codeacustom ResultsCollector implementationtoreplacethedefault.UsetheExecution::withCollector methodtodefinethecustomcollector.
Note:Thissectionappliesonlytofunctionsthatreturnresults.
Toprogramyourclienttogettheresultsfromafunction,usetheresultcollectorreturnedfromthefunctionexecution,likethis:
ResultCollectorPtrrc=FunctionService::onRegion(region)->withArgs(args)->withFilter(keySet)->withCollector(newMyCustomResultCollector()).execute(Function);CacheableVectorPtrfunctionResult=rc.getResult();
The getResult methodsofthedefaultresultcollectorblockuntilallresultsarereceived,thenreturnthefullresultset.
Tohandletheresultsinacustommanner:
1. Writeaclassthatimplementsthe ResultCollector interfacetohandletheresultsinacustommanner.Themethodsareoftwotypes:onehandlesdataandinformationfromGemFireandpopulatestheresultsset,whiletheotherreturnsthecompiledresultstothecallingapplication:
addResult iscalledwhenresultsarrivefromthe Function methods.Use addResult toaddasingleresulttotheResultCollector.endResults iscalledtosignaltheendofallresultsfromthefunctionexecution.getResult isavailabletoyourexecutingapplication(theonethatcalls Execution.execute )toretrievetheresults.Thismayblockuntilallresultsareavailable.clearResults iscalledtoclearpartialresultsfromtheresultscollector.Thisisusedonlyforhighlyavailable onRegion functionswherethecallingapplicationwaitsfortheresults.Ifthecallfails,beforeGemFireretriestheexecution,itcalls clearResults toreadytheinstanceforacleansetofresults.
2. Usethe Execution objectinyourexecutingmembertocall withCollector ,passingyourcustomcollector,asshownintheexampleabove.
©CopyrightPivotalSoftwareInc,2013-2019 300 9.1
Page 301
LATESTVERSION:9.1.1- RELEASENOTES
SolutionsandUseCasesThefunctionexecutionserviceprovidessolutionsfortheseapplicationusecases:
Anapplicationthatexecutesaserver-sidetransactionormakesdataupdatesusingtheGemFiredistributedlockingservice.
Anapplicationthatinitializessomeofitscomponentsonceoneachserver,whichmightbeusedlaterbyexecutedfunctions.
Initializationandstartupofathird-partyservice,suchasamessagingservice.
Anyarbitraryaggregationoperationthatrequiresiterationoverlocaldatasetsthatcanbedonemoreefficientlythroughasinglecalltothecacheserver.
Anykindofexternalresourceprovisioningthatcanbedonebyexecutingafunctiononaserver.
©CopyrightPivotalSoftwareInc,2013-2019 301 9.1
Page 302
LATESTVERSION:9.1.1- RELEASENOTES
DeltaPropagationDeltaPropagationdescribeshowdeltas(updatestodata)arepropagatedandhowtoimplementdeltapropagation.Italsoanalyzesperformancelimitations.
Inmostdistributeddatamanagementsystems,storeddataiscreatedonceandupdatedfrequently.Updatesaresenttoothermembersforeventpropagation,redundancymanagement,andcacheconsistencyingeneral.Trackingonlythechangesinanupdatedobjectandsendingonlytheupdates,ordeltas,meanlowernetworktransmissioncostsandlowerobjectserialization/deserializationcosts.Generally,thelargeryourobjectsandthesmallerthedeltas,thegreatertheperformancebenefitsofdeltapropagation.Partitionedregionsgenerallybenefitmorewithhigherredundancylevels.
HowDeltaPropagationWorks
GemFirepropagatesobjectdeltasusingmethodsthatyouprogramontheclientside.Themethodsareinthedeltainterface,whichyouimplementinyourcachedobjects’classes.
DeltaPropagationAPI
DeltapropagationusesconfigurationpropertiesandasimpleAPItosendandreceivedeltas.
Cloning
Withcloningenabled,GemFiredoesadeepcopyoftheobject,usingserialization.Youcanimproveperformancebyimplementingtheappropriate clone methodforyourAPI,makingadeepcopyofanythingtowhichadeltamaybeapplied.
ImplementingDeltaPropagationBydefault,deltapropagationisenabledinyourdistributedsystemandisusedforobjectsthatimplementthedeltainterface.Youprogramtheclient-sidemethodstoextractdeltainformationforyourentriesandtoapplyreceiveddeltainformation.
ExceptionsandLimitations
©CopyrightPivotalSoftwareInc,2013-2019 302 9.1
Page 303
LATESTVERSION:9.1.1- RELEASENOTES
HowDeltaPropagationWorksGemFirepropagatesobjectdeltasusingmethodsthatyouprogramontheclientside.Themethodsareinthedeltainterface,whichyouimplementinyourcachedobjects’classes.
Thisfigureshowsdeltapropagationforachangetoanentrywithkey, k ,andvalueobject, v .
1. getoperation.The get worksasusual;thecachereturnsthefullentryobjectfromthelocalcacheor,ifitisunavailablethere,fromaservercacheorfromaloader.
2. updatemethods.Youneedtoaddcodetotheobject’supdatemethodssothattheysavedeltainformationforobjectupdates,inadditiontotheworktheywerealreadydoing.
3. putoperation.The put worksasusualinthelocalcache,usingthefullvalue,thencalls hasDelta tocheckfordeltasand toDelta toserializetheinformation.
4. receiptofdelta. fromDelta extractsthedeltainformationthatwasserializedby toDelta andappliesittotheobjectinthelocalcache.Thedeltaisapplieddirectlytotheexistingvalueortoaclone,dependingonhowyouconfigureitfortheregion.
5. additionaldistributions.Aswithfulldistributions,receivingmembersforwardthedeltaaccordingtotheirconfigurationsandconnectionstoothermembers.Intheexample,theserverwouldforwardthedeltatoitspeersanditsotherclientsasneeded.Receivingmembersdonotrecreatethedelta; toDelta isonlycalledintheoriginatingmember.
©CopyrightPivotalSoftwareInc,2013-2019 303 9.1
Page 304
LATESTVERSION:9.1.1- RELEASENOTES
DeltaPropagationAPIDeltapropagationusesconfigurationpropertiesandasimpleAPItosendandreceivedeltas.
.NET-forC#Yourapplicationclassmustimplement:
Apache.Geode.Client.IGFDelta
Apache.Geode.Client.IGeodeSerializable
IGFDelta providesthemethods, HasDelta , ToDelta ,and FromDelta ,whichyouprogramtoreporton,send,andreceivedeltasforyourclass.
Additionally,forcloning,yourclassmustimplementthestandard.NET IClonable interfaceandits Clone method.SeeCloning.
C++Yourapplicationmustpubliclyderivefrom:
apache::geode::client::Delta
Delta providesthemethods, hasDelta , toDelta , fromDelta ,whichyouprogramtoreporton,send,andreceivedeltasforyourclass.
Forcloning,usethe clone methodprovidedintheDeltainterface.SeeCloning.
©CopyrightPivotalSoftwareInc,2013-2019 304 9.1
Page 305
LATESTVERSION:9.1.1- RELEASENOTES
CloningWithcloningenabled,GemFiredoesadeepcopyoftheobject,usingserialization.Youcanimproveperformancebyimplementingtheappropriate clone methodforyourAPI,makingadeepcopyofanythingtowhichadeltamaybeapplied.
Thegoalistosignificantlyreducetheoverheadofcopyingtheobjectwhilestillretainingtheisolationneededforyourdeltas.
Youconfiguredeltapropagationontheserversideaswellasclient.Forinformationontheserveranddeltapropagation,seeDeltaPropagation .
cloning-enabledThe cloning-enabled propertyisaregionattributesboolean,configuredinthe cache.xml ,thataffectshow fromDelta appliesdeltastothelocalclientcache.When true ,theupdatesareappliedtoacloneofthevalueandthenthecloneissavedtothecache.When false ,thevalueismodifiedinplaceinthecache.Thedefaultvalueis false .
Cloningcanbeexpensive,butitensuresthatthenewobjectisfullyinitializedwiththedeltabeforeanyapplicationcodeseesit.
Withoutcloning:
Itispossibleforapplicationcodetoreadtheentryvalueasitisbeingmodified,possiblyseeingthevalueinanintermediate,inconsistentstate,withjustpartofthedeltaapplied.Youmaychoosetoresolvethisissuebyhavingyourapplicationcodesynchronizeonreadsandwrites.
GemFirelosesanyreferencetotheoldvaluebecausetheoldvalueistransformedinplaceintothenewvalue.Becauseofthis,your CacheListener seesthesamenewvaluereturnedfor EntryEvent.getOldValue and EntryEvent.getNewValue .
Exceptionsthrownfrom fromDelta mayleaveyourcacheinaninconsistentstate.Withoutcloning,anyinterruptionofthedeltaapplicationcouldleaveyouwithsomefieldsinyourcachedobjectchangedandothersunchanged.Ifyoudonotusecloning,keepthisinmindwhenyouprogramyourerrorhandlinginyour fromDelta implementation.
EnablingCloningincache.xml
<regionname="exampleRegion"><region-attributesrefid="CACHING_PROXY"cloning-enabled="true"pool-name="examplePool"/></region>
EnablingCloning(C++)
RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);RegionPtrregionPtr=regionFactory->setCloningEnabled(true)->create("myRegion");
©CopyrightPivotalSoftwareInc,2013-2019 305 9.1
Page 306
LATESTVERSION:9.1.1- RELEASENOTES
ImplementingDeltaPropagationBydefault,deltapropagationisenabledinyourdistributedsystemandisusedforobjectsthatimplementthedeltainterface.Youprogramtheclient-sidemethodstoextractdeltainformationforyourentriesandtoapplyreceiveddeltainformation.
Foracompletedeltapropagationexample,seeQuickStartExamples.
Prerequisites
Studyyourobjecttypesandexpectedapplicationbehaviortodeterminewhichobjectsshouldusedeltapropagation.Deltapropagationisnotbeneficialforalldataanddatamodificationscenarios.SeeExceptionsandLimitations .
Decidewhethertoenablecloning.Cloningisdisabledbydefault.Seecloning-enabled .
Ifyouenablecloning,considerprovidingyourownimplementation,tooptimizeperformance.
Ifyoudonotenablecloning,besuretosynchronizeyourdeltacode.
Ifyoudonotenablecloning,reviewallassociatedlistenercodefordependenciesontheentryeventoldvalue.Withoutcloning,GemFiremodifiestheentryinplaceandsolosesitsreferencetotheoldvalue.Fordeltaevents,the EntryEvent methodstoretrievetheoldandnewvaluesbothreturnthenewvalue.
Procedure
Foreveryclassinwhichyouwantdeltapropagation,implementthedeltainterfaceandupdateyourmethodstosupportdeltapropagation.Exactlyhowyoudothisdependsonyourapplicationandobjectneeds,butthesestepsdescribethebasicapproach.
1. Studytheobjectcontentstodecidehowtohandledeltachanges.Deltapropagationhasthesameissuesofdistributedconcurrencycontrolasthedistributionoffullobjects,butonamoredetailedlevel.Somepartsofyourobjectsmaybeabletochangeindependentofoneanotherwhileothersmayalwaysneedtochangetogether.Senddeltaslargeenoughtokeepyourdatalogicallyconsistent.If,forexample,fieldAandfieldBdependoneachother,thenyourdeltadistributionsshouldeitherupdatebothfieldsorneither.Aswithregularupdates,thefewerproducersyouhaveonadataregion,theloweryourlikelihoodofconcurrencyissues.
2. Intheapplicationcodethatputsentries,putthefullypopulatedobjectintothelocalcache.Thisusuallymeansdoinga get ontheentry,unlessyouaresureitdoesnotalreadyexistanywhereinthedistributedregion.Eventhoughyouareplanningtosendonlydeltas,errorsonthereceivingendcouldcausearequestofthefullobject,soyoumustprovidethefullobjecttotheoriginatingputmethod.Dothiseveninemptyproducers,withregionsconfiguredfornolocaldatastorage.
3. Changeeachfield’supdatemethodtorecordinformationabouttheupdate.Theinformationmustbesufficientfor toDelta toencodethedeltaandanyadditionalrequireddeltainformationwhenitisinvoked.
4. Write hasDelta toreportonwhetheradeltaisavailable.
5. Whenwritingyourserializationmethods, toDelta , fromDelta , toData , fromData ,besuretoexcludeanyfieldsusedtomanagedeltastate,whichdonotneedtobesent.
6. Write toDelta tocreateabytestreamwiththechangestotheobjectandanyotherinformationthat fromDelta willneedtoapplythechanges.Beforereturningfromyourdeltastatetoindicatethattherearenodeltachangeswaitingtobesent.
7. Write fromDelta todecodethebytestreamthat toDelta createsandupdatetheobject.
8. Makesureyouprovideadequatesynchronizationtoyourobjecttomaintainaconsistentobjectstate.Ifyoudonotusecloning,youwillprobablyneedtosynchronizeonreadsandwritestoavoidreadingpartiallywrittenupdatesfromthecache.Thismightinvolve toDeltafromDelta ,andotherobjectaccessandupdatemethods.Additionally,yourimplementationshouldtakeintoaccountthepossibilityofconcurrentinvocationsof fromDelta
ormoreoftheobject’supdatemethods.
©CopyrightPivotalSoftwareInc,2013-2019 306 9.1
Page 307
LATESTVERSION:9.1.1- RELEASENOTES
ExceptionsandLimitationsInsomeapplicationscenarios,deltapropagationdoesnotshowanysignificantperformancebenefits.Onoccasionitresultsindegradation.Thereareotherlimitationsandexceptionsrelatedtodeltapropagation.
ErrorsinDeltaPropagationErrorsindeltapropagationfallintotwocategoriesbasedonhowtheyarehandled:
Problemsapplyingthedeltathatcanberemediediftheoriginatingmembersendsthefullvalueinplaceofthedelta.Yourputoperationdoesnotseeerrorsorexceptionsrelatedtothefaileddeltapropagation.Thesystemautomaticallydoesafullvaluedistributiontothereceiverwheretheproblemoccurs.Thistypeoferrorincludes:
Unavailableentryvalueinthereceivingcache,eitherbecausetheentryismissingoritsvalueisnull.Inbothcases,thereisnothingtoapplythedeltatoandthefullvaluemustbesent.Thisismostlikelytooccurifyoudestroyorinvalidateyourentrieslocally,eitherthroughapplicationcallsorthroughconfiguredactionslikeevictionorentryexpiration.InvalidDeltaException thrownby fromDelta method,programmedbyyou.Thisexceptionenablesyoutoavoidapplyingdeltasthatwouldviolatedataconsistencychecksorotherapplicationrequirements.Throwingthisexceptioncausesasendofthefullvalue.Anyerrorapplyingthedeltainaclientinserver-to-clientpropagation.Theclientretrievesthefullvaluefromtheserver.
Problemscreatingordistributingthedeltathatcannotbefixedbydistributingthefullvalue.Theseproblemsarecausedbyerrorsorexceptionsin hasDelta or toDelta
cases,your put operationfailswithanexception.
PerformanceLimitationsConsiderthefollowingsituationsinwhichdeltapropagationadverselyaffectsperformance:
Addedcostsofdeserializingyourobjectstoapplydeltas.Applyingadeltarequirestheentryvaluetobedeserialized.Oncethisisdone,theobjectisstoredbackinthecacheindeserializedform.Thisaspectofdeltapropagationonlynegativelyimpactsyoursystemifyourobjectsarenotalreadybeingdeserializedforotherreasons,suchasforindexingandqueryingorforlisteneroperations.Oncestoredindeserializedform,therearereserializationcostsforoperationsthatsendtheobjectoutsideofthemember,likevaluessentinresponsetonetSearchorclientrequests,andstoragetodisk.Themoreoperationsthatrequirereserialization,thehighertheoverheadofdeserializingtheobject.
Cloning.Cloningcanaffectperformance.Notusingcloningisrisky,however,asyouaremodifyingcachedvaluesinplace.Makesureyousynchronizeyourentryaccesstokeepyourcachefrombecominginconsistent.
Problemsapplyingthedeltathatcausethesystemtogobacktotheoriginatorforthefullentryvalue.Inthisscenario,theoveralloperationcostsmorethansendingthefullentryvalueinthefirstplace.Theproblemcanbeexacerbatedifyourdeltaissenttoanumberofrecipients,allormostofthemrequestafullvalue,andthefullvaluesendrequirestheobjecttobeserialized.
DiskI/Ocostsassociatedwithoverflowregions.Ifyouuseevictionwithoverflowtodisk,on-diskvaluesmustbebroughtintomemoryinordertoapplythedelta.Thisismuchmorecostlythanremovingthereferencetothediskcopy,asyouwoulddowithafullvaluedistributionintothecache.
ConfigurationsThatRequireFullValuesClientscanalwayssenddeltastotheservers,andserverscanusuallysentdeltastoclients.Thefollowingconfigurationsrequiretheserverstosendfullvaluestotheclients,insteadofdeltas:
Whentheclient’s gemfire.properties setting conflate-events issetto true ,theserverssendfullvaluesforallregions.
Whentheserverregionattribute enable-subscription-conflation issetto true andtheclient gemfire.properties setting conflate-events issetto serversendfullvaluesfortheregion.
Serverssendfullvaluestoclientregionsthatareconfiguredtonotcachedata—withthe PROXY RegionShortcut intheirregionattributes refid .
Tousethedeltapropagationfeature,allupdatesonakeyinaregionmusthavevaluetypesthatimplementtheDelta interface.Youcannotmixobjecttypesforanentrykeywheresomeofthetypesimplementdeltaandsomedonot.Thisisbecause,whenatypeimplementingthedeltainterfaceisreceivedforanupdate,theexistingvalueforthekeyiscasttoatypetoapplythereceiveddelta.
GeneralLimitationsSometimes fromDelta cannotbeinvokedbecausethereisnoobjecttoapplythedeltatointhereceivingcache.Whenthishappens,thesystemsendsthefullvalue.Therearetwopossiblescenarios:
Ifthesystemcandeterminebeforehandthatthereceiverdoesnothavealocalcopy,itsendstheinitialmessagewiththefullvalue.Thisispossiblewhenregionsareconfiguredwith
©CopyrightPivotalSoftwareInc,2013-2019 307 9.1
Page 308
nolocaldatastorage,aswhenyouareusingthemtoprovidedataupdateinformationtolisteners.
Inlessobviouscases,aswhenanentryhasbeenlocallydeleted,firstthedeltaissent,thenthereceiverrequestsafullvalueandthatissent.Wheneverthefullvalueisreceived,anyfurtherdistributionstothereceiver’speersorclientsusesthefullvalue.
Nodeltasarepropagatedfor:
Transactionalcommitontheserver
The putAll operation
©CopyrightPivotalSoftwareInc,2013-2019 308 9.1
Page 309
LATESTVERSION:9.1.1- RELEASENOTES
ProgrammingExamplesThischapterprovidesasetofprogrammingexamplestohelpyouunderstandtheclientAPI.
DeclaringaClientRegion
Thefollowingexampleshowshowtodeclareaclientregionina cache.xml file.
APIProgrammingExample–C#ThisC#programmingcodeinthenextexampledemonstrateshowtousetwoormoreclientssharingadistributedregioninaGeodecache.
APIProgrammingExample–C++
DataSerializationExamples
©CopyrightPivotalSoftwareInc,2013-2019 309 9.1
Page 310
LATESTVERSION:9.1.1- RELEASENOTES
DeclaringaClientRegionThisexampleshowshowtodeclareaclientregionina cache.xml file.
<cache><regionname="root1"><region-attributesrefid="CACHING_PROXY"pool-name="poolName1"/></region><regionname="root2"><region-attributesrefid="PROXY"pool-name="poolName2"/></region><poolname="poolName1"subscription-enabled="true"><serverhost="localhost"port="40404"/></pool><poolname="poolName2"subscription-enabled="true"><serverhost="localhost"port="40404"/></pool></cache>
Thepooldefinesalistofcacheserversthattheclientregioncancommunicatewith.
TheCACHING_PROXYsettingcausestheclientregiontocachedataandtocommunicatewiththeservers.ThePROXYsettingcausestheclientregiontocommunicatewiththeservers,butcachenodata.
Theregionsubscription-enabledproperty,if true ,indicatesthattheclientshouldreceivedataupdateswhenserverdatachanges.
Clientsdonotspecifycacheloadersorwriters,whichareprovidedbytheserver.
©CopyrightPivotalSoftwareInc,2013-2019 310 9.1
Page 311
LATESTVERSION:9.1.1- RELEASENOTES
APIProgrammingExample–C#SeeQuickStartExamplesforC#programmingexamples.
©CopyrightPivotalSoftwareInc,2013-2019 311 9.1
Page 312
LATESTVERSION:9.1.1- RELEASENOTES
APIProgrammingExample–C++SeeQuickStartExamplesforC++programmingexamples.
©CopyrightPivotalSoftwareInc,2013-2019 312 9.1
Page 313
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationExamplesThissectioncontainsdataserializationexamplesforC++,C#,andJava.
C++SerializationExample
C#SerializationExample
JavaSerializationExample
©CopyrightPivotalSoftwareInc,2013-2019 313 9.1
Page 314
LATESTVERSION:9.1.1- RELEASENOTES
C++SerializationExampleThisC++exampleimplementsanembeddedobject.
classUser:publicSerializable{private:std::stringname;int32_tuserId;ExampleObject*eo;public:User(std::stringname,int32_tuserId):name(name),userId(userId){eo=newExampleObject(this->userId);}
~User(){if(eo!=NULL)deleteeo;eo=NULL;}
User(){name="";userId=0;eo=newExampleObject(userId);}
User(constchar*strfmt,chardelimeter){std::stringuserId_str;std::stringsValue(strfmt);std::string::size_typepos1=sValue.find_first_of(delimeter);std::string::size_typepos2;if(pos1==std::string::npos){userId_str=sValue;name=sValue;}else{userId_str=sValue.substr(0,pos1);pos2=sValue.find(delimeter,pos1+1);intlen;len=sValue.length()-pos1;if(pos2==std::string::npos){}else{len=pos2-pos1;}name=sValue.substr(pos1+1,len);}userId=(int32_t)atoi(userId_str.c_str());eo=newExampleObject(userId_str);}
CacheableStringPtrtoString()const{CacheableStringPtreo_str=eo->toString();charuserId_str[128];sprintf(userId_str,"User:%d",userId);std::stringsValue=std::string(userId_str)+","+name+"\n";sValue+=std::string(eo_str->asChar());returnCacheableString::create(sValue.c_str());}
int32_tgetUserId(){returnuserId;}
std::stringgetName(){returnname;}
ExampleObject*getEO(){returneo;}
voidsetEO(ExampleObject*eObject){eo=eObject;}
//AddthefollowingfortheSerializableinterface//OurTypeFactoryMethod
staticSerializable*createInstance(){returnnewUser(std::string("gester"),123);
©CopyrightPivotalSoftwareInc,2013-2019 314 9.1
Page 315
returnnewUser(std::string("gester"),123);}
int32_tclassId()const{return0x2d;//45}
voidtoData(DataOutput&output)const{output.writeASCII(name.c_str(),name.size());output.writeInt(userId);eo->toData(output);}
uint32_tobjectSize()const{return(sizeof(char)*(name.size()+1))+sizeof(User)+eo->objectSize();}
Serializable*fromData(DataInput&input){char*readbuf;input.readASCII(&readbuf);name=std::string(readbuf);input.freeUTFMemory(readbuf);input.readInt(&userId);eo->fromData(input);returnthis;}};
ThisC++exampleimplementscomplexdatatypes.
classExampleObject:publicSerializable{private:doubledouble_field;floatfloat_field;longlong_field;intint_field;shortshort_field;std::stringstring_field;std::vector<std::string>string_vector;public:ExampleObject(){double_field=0.0;float_field=0.0;long_field=0;int_field=0;short_field=0;string_field="";string_vector.clear();}
~ExampleObject(){}
ExampleObject(intid){charbuf[64];sprintf(buf,"%d",id);std::stringsValue(buf);int_field=id;long_field=int_field;short_field=int_field;double_field=(double)int_field;float_field=(float)int_field;string_field=sValue;string_vector.clear();for(inti=0;i<3;i++){string_vector.push_back(sValue);}}
ExampleObject(std::stringsValue){int_field=atoi(sValue.c_str());long_field=int_field;short_field=int_field;double_field=(double)int_field;float_field=(float)int_field;string_field=sValue;string_vector.clear();for(inti=0;i<3;i++){string_vector.push_back(sValue);}}
©CopyrightPivotalSoftwareInc,2013-2019 315 9.1
Page 316
}
CacheableStringPtrtoString()const{charbuf[1024];std::stringsValue="ExampleObject:";sprintf(buf,"%f(double),%f(double),%ld(long),%d(int),%d(short),",double_field,float_field,long_field,int_field,short_field);sValue+=std::string(buf)+string_field+"(string),";if(string_vector.size()>0){sValue+="[";for(unsignedinti=0;i<string_vector.size();i++){sValue+=string_vector[i];if(i!=string_vector.size()-1){sValue+=",";}}sValue+="](stringvector)";}returnCacheableString::create(sValue.c_str());}
doublegetDouble_field(){returndouble_field;}
floatgetFloat_field(){returnfloat_field;}
longgetLong_field(){returnlong_field;}
intgetInt_field(){returnint_field;}
shortgetShort_field(){returnshort_field;}
std::string&getString_field(){returnstring_field;}
std::vector<std::string>&getString_vector(){returnstring_vector;}
//AddthefollowingfortheSerializableinterface//OurTypeFactoryMethod
staticSerializable*createInstance(){returnnewExampleObject();}
int32_tclassId()const{return0x2e;//46}
booloperator==(constSerializable&other)const{constExampleObject&otherEO=static_cast<constExampleObject&>(other);return(0==strcmp(otherEO.toString()->asChar(),toString()->asChar()));}
uint32_thashcode()const{returnint_field;}
uint32_tobjectSize()const{uint32_tobjectSize=sizeof(ExampleObject);objectSize+=sizeof(char)*(string_field.size()+1);size_titemCount=string_vector.size();for(size_tidx=0;idx<itemCount;idx++){//copyeachstringtotheserializationbuffer,includingthenull//terminatingcharacterattheendofthestring.objectSize+=sizeof(char)*(string_vector[idx].size()+1);}returnobjectSize;}
voidtoData(DataOutput&output)const{output.writeDouble(double_field);output.writeFloat(float_field);
©CopyrightPivotalSoftwareInc,2013-2019 316 9.1
Page 317
output.writeInt((int64_t)long_field);output.writeInt((int32_t)int_field);output.writeInt((int16_t)short_field);output.writeASCII(string_field.c_str(),string_field.size());size_titemCount=string_vector.size();output.writeInt((int32_t)itemCount);for(size_tidx=0;idx<itemCount;idx++){//copyeachstringtotheserializationbuffer,includingthenull//terminatingcharacterattheendofthestring.output.writeASCII(string_vector[idx].c_str(),string_vector[idx].size());}}
Serializable*fromData(DataInput&input){char*readbuf;input.readDouble(&double_field);input.readFloat(&float_field);input.readInt((int64_t*)(void*)&long_field);input.readInt((int32_t*)(void*)&int_field);input.readInt((int16_t*)(void*)&short_field);
int32_titemCount=0;input.readASCII(&readbuf);string_field=std::string(readbuf);input.freeUTFMemory(readbuf);
string_vector.clear();input.readInt((int32_t*)&itemCount);for(int32_tidx=0;idx<itemCount;idx++){//readfromserializationbufferintoacharacterarrayinput.readASCII(&readbuf);//andstoreinthehistorylistofstrings.string_vector.push_back(readbuf);input.freeUTFMemory(readbuf);}returnthis;}};typedefSharedPtr<ExampleObject>ExampleObjectPtr;
©CopyrightPivotalSoftwareInc,2013-2019 317 9.1
Page 318
LATESTVERSION:9.1.1- RELEASENOTES
C#SerializationExampleThisC#.NETexampleshowshowtoimplementauser-definedSerializableobject.
classUser:IGeodeSerializable{privatestringm_name;privateintm_userId;ExampleObjectm_eo;
publicUser(stringname,intuserId){m_name=name;m_userId=userId;m_eo=newExampleObject();}
publicUser(){m_name=string.Empty;m_userId=0;m_eo=newExampleObject();}
publicintUserId{get{returnm_userId;}
}
publicstringName{get{returnm_name;}}
publicExampleObjectEO{get{returnm_eo;}set{m_eo=value;}}
publicoverridestringToString(){returnstring.Format("User:{0},{1}\n{2}",m_userId,m_name,m_eo.ToString());}
//OurTypeFactoryMethodpublicstaticIGeodeSerializableCreateInstance(){returnnewUser();}
#regionIGeodeSerializableMembers
publicUInt32ClassId(){get{return45;//mustmatchJava}}
publicIGeodeSerializableFromData(DataInputinput){m_name=input.ReadUTF();m_userId=input.ReadInt32();m_eo.FromData(input);returnthis;
©CopyrightPivotalSoftwareInc,2013-2019 318 9.1
Page 319
returnthis;}
publicvoidToData(DataOutputoutput){output.writeUTF(m_name);output.writeInt32(m_userId);eo.ToData(output);}
#endregion}
©CopyrightPivotalSoftwareInc,2013-2019 319 9.1
Page 320
LATESTVERSION:9.1.1- RELEASENOTES
JavaSerializationExample
ImplementinganEmbeddedObject(Java)
publicclassUserimplementsDataSerializable{privateStringname;privateintuserId;privateExampleObjecteo;static{Instantiator.register(newInstantiator(User.class,(byte)45){publicDataSerializablenewInstance(){returnnewUser();}});}/***Createsan"empty"Userwhosecontentsarefilledinby*invokingitstoData()method*/
privateUser(){this.name="";this.userId=0;this.eo=newExampleObject(0);}
publicUser(Stringname,intuserId){this.name=name;this.userId=userId;this.eo=newExampleObject(userId);}
publicvoidsetEO(ExampleObjecteo){this.eo=eo;}
publicExampleObjectgetEO(){returneo;}
publicvoidtoData(DataOutputout)throwsIOException{out.writeUTF(this.name);out.writeInt(this.userId);eo.toData(out);}
publicvoidfromData(DataInputin)throwsIOException,ClassNotFoundException{this.name=in.readUTF();this.userId=in.readInt();this.eo.fromData(in);}
publicintgetUserId(){returnuserId;}
publicStringgetName(){returnname;}
publicbooleanequals(Usero){if(!this.name.equals(o.name))returnfalse;if(this.userId!=o.userId)returnfalse;if(!this.eo.equals(o.eo))returnfalse;returntrue;}}
ImplementingComplexDataTypes(Java)
©CopyrightPivotalSoftwareInc,2013-2019 320 9.1
Page 321
publicclassExampleObjectimplementsDataSerializable{privatedoubledouble_field;privatelonglong_field;privatefloatfloat_field;privateintint_field;privateshortshort_field;privatejava.lang.Stringstring_field;privateVectorstring_vector;static{Instantiator.register(newInstantiator(ExampleObject.class,(byte)46){publicDataSerializablenewInstance(){returnnewExampleObject();}});}publicExampleObject(){this.double_field=0.0D;this.long_field=0L;this.float_field=0.0F;this.int_field=0;this.short_field=0;this.string_field=null;this.string_vector=null;}publicExampleObject(intid){this.int_field=id;this.string_field=String.valueOf(id);this.short_field=Short.parseShort(string_field);this.double_field=Double.parseDouble(string_field);this.float_field=Float.parseFloat(string_field);this.long_field=Long.parseLong(string_field);this.string_vector=newVector();for(inti=0;i<3;i++){this.string_vector.addElement(string_field);}}publicExampleObject(Stringid_str){this.int_field=Integer.parseInt(id_str);this.string_field=id_str;this.short_field=Short.parseShort(string_field);this.double_field=Double.parseDouble(string_field);this.float_field=Float.parseFloat(string_field);this.long_field=Long.parseLong(string_field);this.string_vector=newVector();for(inti=0;i<3;i++){this.string_vector.addElement(string_field);}}publicdoublegetDouble_field(){returnthis.double_field;}publicvoidsetDouble_field(doubledouble_field){this.double_field=double_field;}publiclonggetLong_field(){returnthis.long_field;}publicvoidsetLong_field(longlong_field){this.long_field=long_field;}publicfloatgetFloat_field(){returnthis.float_field;}publicvoidsetFloat_field(floatfloat_field){this.float_field=float_field;}publicintgetInt_field(){returnthis.int_field;}publicvoidsetInt_field(intint_field){this.int_field=int_field;}publicshortgetShort_field(){returnthis.short_field;}publicvoidsetShort_field(shortshort_field){this.short_field=short_field;}publicjava.lang.StringgetString_field(){returnthis.string_field;}publicvoidsetString_field(java.lang.Stringstring_field){this.string_field=string_field;}publicVectorgetString_vector(){
©CopyrightPivotalSoftwareInc,2013-2019 321 9.1
Page 322
publicVectorgetString_vector(){returnthis.string_vector;}publicvoidsetString_vector(Vectorstring_vector){this.string_vector=string_vector;}publicvoidtoData(DataOutputout)throwsIOException{out.writeDouble(double_field);out.writeFloat(float_field);out.writeLong(long_field);out.writeInt(int_field);out.writeShort(short_field);out.writeUTF(string_field);out.writeInt(string_vector.size());for(inti=0;i<string_vector.size();i++){out.writeUTF((String)string_vector.elementAt(i));}}publicvoidfromData(DataInputin)throwsIOException,ClassNotFoundException{this.double_field=in.readDouble();this.float_field=in.readFloat();this.long_field=in.readLong();this.int_field=in.readInt();this.short_field=in.readShort();this.string_field=in.readUTF();this.string_vector=newVector();intsize=in.readInt();for(inti=0;i<size;i++){Strings=in.readUTF();string_vector.add(i,s);}}publicbooleanequals(ExampleObjecto){if(this.double_field!=o.double_field)returnfalse;if(this.float_field!=o.float_field)returnfalse;if(this.long_field!=o.long_field)returnfalse;if(this.int_field!=o.int_field)returnfalse;if(this.short_field!=o.short_field)returnfalse;if(!this.string_field.equals(o.string_field))returnfalse;if(!this.string_vector.equals(o.string_vector))returnfalse;returntrue;}}
©CopyrightPivotalSoftwareInc,2013-2019 322 9.1
Page 323
LATESTVERSION:9.1.1- RELEASENOTES
InteroperabilityofLanguageClassesandTypesThissectionprovidesatablethatmapsC++classmethodstocorresponding.NETclassmethodsandatablethatmapsJavatypesto.NETtypes.
C++Classto.NETClassMappings
Javato.NETTypeMappingTable
©CopyrightPivotalSoftwareInc,2013-2019 323 9.1
Page 324
LATESTVERSION:9.1.1- RELEASENOTES
InteroperabilityofC++TypesWhenUsingPDXSerializationThistopictableliststhemappingbetweenC++typesandotherlanguagetypeswhenusingPDXserialization.
Inaddition,thetablelistswhichPdxReaderandPdxWriterC++APIstousewhenserializinganddeserializingthetypes.
C++Type .NETType JavaType PdxReader/PdxWriterAPI
CacheableHashTable System::Collections::Hashtable java.util.Hashtable readObject/writeObject
CacheableHashMap System::Collections::Generic::IDictionary<Object,Object> java.util.HashMap readObject/writeObject
CacheableVector System::Collections::ArrayList java.util.Vector readObject/writeObject
CacheableArrayList System::Collections::Generic::IList<Object> java.util.ArrayList readObject/writeObject
bool bool boolean readBoolean/writeBoolean
int8_t sbyte Byte readByte/writeByte
wchar_t/char Char Char readChar/writeChar
wchar_t*/char* string string readString/writeString
double Double double readDouble/writeDouble
float float float readFloat/writeFloat
int16_t short short readShort/writeShort
int32_t Int32/int int readInt/writeInt
int64_t Int64/long long readLong/writeLong
int8_t* System.Byte[]/System.SByte[] Byte[] readByteArray/writeByteArray
double* System.Double[] Double[] readDoubleArray/writeDoubleArray
float* System.float[] Float[] readFloatArray/writeFloatArray
CacheableHashSet CacheableHashSet java.util.HashSet readObject/writeObject
CacheableLinkedHashSet CacheableLinkedHashSet java.util.LinkedHashSet readObject/writeObject
int16_t* System.Int16[] Short[] readShortArray/writeShortArray
int32_t* System.Int32[] Int[] readIntArray/writeIntArray
int64_t* System.Int64[] Long[] readLongArray/writeLongArray
bool* System.Boolean[] Boolean[] readBooleanArray/writeBooleanArray
wchar_t*/char* System.Char[] char[] readCharArray/writeCharArray
enum enum Enum readObject/writeObject
int8_t** byte[][]/Sbyte[][] Byte[][] readArrayOfByteArrays/writeArrayOfByteArrays
wchar_t**/char** System.String[] String[] readStringArray/writeStringArray
CacheableDate System.DateTime(UTC) Java.util.date readDate/writeDate
CacheableObjectArray object[]/System.Object[] Object[] readObjectArray/writeObjectArray
Cacheable/Serializable object/System.Object Object readObject/writeObject
C++allowsunicodeandnon-unicodecharacters,soC++PDXwillsupportbothwchar_t/charandwchar_t*/char*.
ForPdx,onlySByteisused,asJavaByteissigned.ButforDataSerializable,Byte[]arrayisusedasadatacontainer.
C++allowsexplicitsettingofordinalnumbers,butitisuptothedevelopertomaptheJavaenumNameswithC++enumNames.SeeUsingC++EnumTypewithPDXSerialization
1
1
2
1
3
1
1
2
3
©CopyrightPivotalSoftwareInc,2013-2019 324 9.1
Page 325
LATESTVERSION:9.1.1- RELEASENOTES
SystemStatisticsThissectiondiscussesstatisticsforcachinganddistributionactivities.Statisticsthatendwith“time”aretime-basedstatistics.Forperformancereasons,thesystemdoesnotcollectthesebydefault.Toenabletime-basedstatisticsgathering,setthesystemproperty enable-time-statistics asdescribedinAttributesingeode.properties—StatisticsArchivingProperties
SamplingStatisticsWhenapplicationsandcacheserversjoinadistributedsystem,theyindicatewhethertoenablestatisticssamplingandwhethertoarchivethestatisticsthataregathered.
SystemPerformanceStatisticsPerformancestatisticsarecollectedforeachapplicationorcacheserverthatconnectstoadistributedsystem.
OperatingSystemStatisticsUseoperatingsystemstatisticstodetermineamember’sCPU,memory,anddiskusage.
©CopyrightPivotalSoftwareInc,2013-2019 325 9.1
Page 326
LATESTVERSION:9.1.1- RELEASENOTES
SamplingStatisticsWhenapplicationsandcacheserversjoinadistributedsystem,theyindicatewhethertoenablestatisticssamplingandwhethertoarchivethestatisticsthataregathered.
Thefollowingstatisticsarerelatedtothestatisticsampler.
sampleCount Totalnumberofsamplestakenbythissampler.
sampleTime Totalamountoftimespenttakingsamples.
StatSampler Statisticsonthestatisticsampler.
Formoreinformationaboutconfiguringstatistics,seeAttributesingeode.properties.
©CopyrightPivotalSoftwareInc,2013-2019 326 9.1
Page 327
LATESTVERSION:9.1.1- RELEASENOTES
SystemPerformanceStatisticsPerformancestatisticsarecollectedforeachapplicationorcacheserverthatconnectstoadistributedsystem.
RegionStatisticsThesemethodshelptogetthestatisticsofaregion.
CachePerformanceStatisticsUsecacheperformancestatisticstodeterminethetypeandnumberofcacheoperationsbeingperformedandhowmuchtimetheyconsume.
ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.
CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.
PoolStatisticsUsethepoolobjecttogetstatisticsonconnectionpools.
DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.
©CopyrightPivotalSoftwareInc,2013-2019 327 9.1
Page 328
LATESTVERSION:9.1.1- RELEASENOTES
RegionStatisticsThesemethodshelptogetthestatisticsofaregion.
creates Totalnumberofcachecreatesforthisregion.
puts Totalnumberofcacheputoperationsforthisregion.
putTime Totaltimespentdoingputoperationsforthisregion.
putAll TotalnumberofcacheputAllsforthisregion.
putAllTime TotaltimespentdoingputAlloperationsforthisregion.
gets Totalnumberofcachegetsforthisregion.
getTime Totaltimespentdoinggetoperationsforthisregion.
getAll TotalnumberofcachegetAllsforthisregion.
getAllTime TotaltimespentdoinggetAlloperationsforthisregion.
hits Totalnumberofcachehitsforthisregion.
misses Totalnumberofcachemissesforthisregion.
entries Currentnumberofcacheentriesforthisregion.
destroys Totalnumberofcachedestroysforthisregion.
clears Totalnumberofcacheclearsforthisregion.
overflows Totalnumberofcacheoverflowstodiskforthisregion.
retrieves Totalnumberofcacheentriesfetchedfromdiskintothecacheregion.
metaDataRefreshCount Totalnumberoftimesmetadatawasrefreshedduetotheobservationofmultiplehops.
cacheLoaderCallCompleted Totalnumberoftimesaloadhascompletedforthisregion.
cacheLoaderCallTime Totaltimespentinvokingtheloadersforthisregion.
CacheWriterCallsCompleted Totalnumberoftimesacachewritercallhascompletedforthisregion.
CacheWriterCallTime Totaltimespentdoingcachewritercalls.
CacheListenerCallsCompleted Totalnumberoftimesacachelistenercallhascompletedforthisregion.
CacheListenerCallTime Totaltimespentdoingcachelistenercallsforthisregion.
©CopyrightPivotalSoftwareInc,2013-2019 328 9.1
Page 329
LATESTVERSION:9.1.1- RELEASENOTES
CachePerformanceStatisticsUsecacheperformancestatisticstodeterminethetypeandnumberofcacheoperationsbeingperformedandhowmuchtimetheyconsume.
Thesestatisticsareavailableifthemembercreatesacache.
creates Totalnumberofcachecreates.
puts Totalnumberofcacheputs.
gets Totalnumberofcachegets.
entries Currentnumberofcacheentries.
hits Totalnumberofcachehits.
misses Totalnumberofcachemisses.
destroys Totalnumberofcachedestroys.
overflows Totalnumberofcacheoverflowstopersistencebackup.
cacheListenerCallsCompleted Totalnumberoftimesacachelistenercallhascompleted.
pdxInstanceDeserializations TotalnumberoftimesgetObjecthasbeencalledonaPdxInstance.
pdxInstanceDeserializationTime Totalamountoftime,innanoseconds,spentdeserializingPdxInstancesbycallinggetObject.
pdxInstanceCreations TotalnumberoftimesadeserializationcreatedaPdxInstance.
pdxSerializations TotalnumberofPDXserializations.
pdxSerializedBytes TotalnumberofbytesproducedbyPDXserialization.
pdxDeserializations TotalnumberofPDXdeserializations.
pdxDeserializedBytes TotalnumberofbytesreadbyPDXdeserialization.
tombstoneCount Totalnumberoftombstoneentriescreatedforperformingconcurrencychecks.
nonReplicatedTombstoneSize Approximatetotalsize(inbytes)oftombstonespresentintheclientcache.
©CopyrightPivotalSoftwareInc,2013-2019 329 9.1
Page 330
LATESTVERSION:9.1.1- RELEASENOTES
ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.
inserts TotalnumberofinsertsforthisCQquery.
updates TotalnumberofupdatesforthisCQquery.
deletes TotalnumberofdeletesforthisCQquery.
events TotalnumberofeventsforthisCQquery.
©CopyrightPivotalSoftwareInc,2013-2019 330 9.1
Page 331
LATESTVERSION:9.1.1- RELEASENOTES
CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.
CqsActive TotalnumberofCQsactiveforthisCQservice.
CqsCreated TotalnumberofCQscreatedforthisCQservice.
CqsClosed TotalnumberofCQsclosedforthisCQservice.
CqsStopped TotalnumberofCQsstoppedforthisCQservice.
CqsOnClient TotalnumberofCQsontheclientforthisCQservice.
©CopyrightPivotalSoftwareInc,2013-2019 331 9.1
Page 332
LATESTVERSION:9.1.1- RELEASENOTES
PoolStatisticsUsethepoolobjecttogetstatisticsonconnectionpools.
locators Currentnumberoflocatorsdiscovered.
servers Currentnumberofserversdiscovered.
locatorRequests Numberofrequestsfromthisconnectionpooltoalocator.
locatorResponses Numberofresponsesfromthelocatortothisconnectionpool.
poolConnections Currentnumberofpoolconnections.
connects Totalnumberoftimesaconnectionhasbeencreated.
ConnectionWaitTime Totaltime(nanoseconds)spentwaitingforaconnection.
disconnects Totalnumberoftimesaconnectionhasbeendestroyed.
minPoolSizeConnect Totalnumberofconnectsdonetomaintainminimumpoolsize.
loadConditioningConnects Totalnumberofconnectsdoneduetoloadconditioning.
idleDisconnects Totalnumberofdisconnectsdoneduetoidleexpiration.
loadConditioningDisconnects Totalnumberofdisconnectsdoneduetoloadconditioningexpiration.
connectionWaitsInProgress Currentnumberofthreadswaitingforaconnection.
connectionWaits Totalnumberoftimesathreadcompletedwaitingforaconnection(bytimingoutorbygettingaconnection).
clientOpsInProgress CurrentnumberofclientOpsbeingexecuted.
clientOps TotalnumberofclientOpscompletedsuccessfully.
clientOpFailures TotalnumberofclientOpattemptsthathavefailed.
clientOpTimeouts TotalnumberofclientOpattemptsthathavetimedout.
QueryExecutions TotalnumberofqueryExecutions.
QueryExecutionTime TotaltimespentwhileprocessingqueryExecution.
©CopyrightPivotalSoftwareInc,2013-2019 332 9.1
Page 333
LATESTVERSION:9.1.1- RELEASENOTES
DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.
deltaMessageFailures Totalnumberofmessagescontainingdelta(receivedfromserver)butcouldnotbeprocessedafterreception.
deltaPuts Totalnumberofputscontainingdeltathathavebeensentfromclienttoserver.
processedDeltaMessages Totalnumberofmessagescontainingdeltareceivedfromserverandprocessedafterreception.
processedDeltaMessagesTime Totaltimespentapplyingdelta(receivedfromserver)onexistingvaluesatclient.
©CopyrightPivotalSoftwareInc,2013-2019 333 9.1
Page 334
LATESTVERSION:9.1.1- RELEASENOTES
OperatingSystemStatisticsUseoperatingsystemstatisticstodetermineamember’sCPU,memory,anddiskusage.
LinuxProcessStatisticsUsethesemethodstogetinformationaboutaLinuxoperatingsystemprocess.
SolarisProcessStatisticsUsethesemethodstogetinformationaboutaSolarisoperatingsystemprocess.
WindowsProcessStatisticsUsethesemethodstogetinformationaboutaWindowsoperatingsystemprocess.
©CopyrightPivotalSoftwareInc,2013-2019 334 9.1
Page 335
LATESTVERSION:9.1.1- RELEASENOTES
LinuxProcessStatisticsUsethesemethodstogetinformationaboutaLinuxoperatingsystemprocess.
imageSize Thesizeoftheprocess’simageinmegabytes.
rssSize Thesizeoftheprocess’sresidentsetsizeinmegabytes.
userTime TheoperatingsystemstatisticfortheprocessCPUusageinusertime
systemTime TheoperatingsystemstatisticfortheprocessCPUusageinsystemtime.
hostCpuUsage TheoperatingsystemstatisticforthehostCPUusage.
threads Numberofthreadscurrentlyactiveinthisprocess.
LinuxProcessStats StatisticsforaLinuxprocess.
©CopyrightPivotalSoftwareInc,2013-2019 335 9.1
Page 336
LATESTVERSION:9.1.1- RELEASENOTES
SolarisProcessStatisticsUsethesemethodstogetinformationaboutaSolarisoperatingsystemprocess.
imageSize Sizeoftheprocessimageinmegabytes.
rssSize Sizeoftheprocessresidentsetinmegabytes.
userTime OperatingsystemstatisticfortheprocessCPUusageinusertime.
systemTime OperatingsystemstatisticfortheprocessCPUusageinsystemtime.
processCpuUsage OperatingsystemstatisticfortheCPUusageofthisprocess.
hostCpuUsage OperatingsystemstatisticforthehostCPUusage.
threads Numberofthreadscurrentlyactiveinthisprocess.
©CopyrightPivotalSoftwareInc,2013-2019 336 9.1
Page 337
LATESTVERSION:9.1.1- RELEASENOTES
WindowsProcessStatisticsUsethesemethodstogetinformationaboutaWindowsoperatingsystemprocess.
handles
Totalnumberofhandlescurrentlyopenbythisprocess.Thisnumberisthesumofthehandlescurrentlyopenbyeachthreadinthisprocess.
priorityBase
Currentbasepriorityoftheprocess.Threadswithinaprocesscanraiseandlowertheirownbasepriorityrelativetotheprocess’sbasepriority.
threads
Numberofthreadscurrentlyactiveinthisprocess.Aninstructionisthebasicunitofexecutioninaprocessor,andathreadistheobjectthatexecutesinstructions.Everyrunningprocesshasatleastonethread.
activeTime
Elapsedtimeinmillisecondsthatallthreadsofthisprocessusedtheprocessortoexecuteinstructions.Aninstructionisthebasicunitofexecutioninacomputer,athreadistheobjectthatexecutesinstructions,andaprocessistheobjectcreatedwhenaprogramisrun.Codeexecutedtohandlesomehardwareinterruptsandtrapconditionsareincludedinthiscount.
pageFaults
Totalnumberofpagefaultsbythethreadsexecutinginthisprocess.Apagefaultoccurswhenathreadreferstoavirtualmemorypagethatisnotinitsworkingsetinmainmemory.Thiswillnotcausethepagetobefetchedfromdiskifitisonthestandbylistandhencealreadyinmainmemory,orifitisinusebyanotherprocesswithwhomthepageisshared.
pageFileSize
Currentnumberofbytesthisprocesshasusedinthepagingfile(s).Pagingfilesareusedtostorepagesofmemoryusedbytheprocessthatarenotcontainedinotherfiles.Pagingfilesaresharedbyallprocesses,andlackofspaceinpagingfilescanpreventotherprocessesfromallocatingmemory.
pageFile Maximumnumberofbytesthisprocesshasusedinthepagingfile(s).Pagingfilesareusedtostorepagesofmemoryusedbytheprocessthatarenotcontainedinotherfiles.
©CopyrightPivotalSoftwareInc,2013-2019 337 9.1
Page 338
SizePeak
Pagingfilesaresharedbyallprocesses,andlackofspaceinpagingfilescanpreventotherprocessesfromallocatingmemory.
privateSize
Currentnumberofbytesthisprocesshasallocatedthatcannotbesharedwithotherprocesses.
systemTime
Elapsedtimeinmillisecondsthatthethreadsoftheprocesshavespentexecutingcodeinprivilegedmode.WhenaWindowssystemserviceiscalled,theserviceoftenrunsinPrivilegedModetogainaccesstosystem-privatedata.Suchdataisprotectedfromaccessbythreadsexecutinginusermode.Callstothesystemcanbeexplicitorimplicit,suchaspagefaultsorinterrupts.Unlikesomeearlyoperatingsystems,Windowsusesprocessboundariesforsubsystemprotectioninadditiontothetraditionalprotectionofuserandprivilegedmodes.Thesesubsystemprocessesprovideadditionalprotection.Therefore,someworkdonebyWindowsonbehalfofyourapplicationmightappearinothersubsystemprocessesinadditiontotheprivilegedtimeinyourprocess.
userTime
Elapsedtimeinmillisecondsthatthisprocess’sthreadshavespentexecutingcodeinusermode.Applications,environmentsubsystems,andintegralsubsystemsexecuteinusermode.CodeexecutinginUserModecannotdamagetheintegrityoftheWindowsExecutive,Kernel,anddevicedrivers.Unlikesomeearlyoperatingsystems,Windowsusesprocessboundariesforsubsystemprotectioninadditiontothetraditionalprotectionofuserandprivilegedmodes.Thesesubsystemprocessesprovideadditionalprotection.Therefore,someworkdonebyWindowsonbehalfofyourapplicationmightappearinothersubsystemprocessesinadditiontotheprivilegedtimeinyourprocess.
virtualSize
Currentsizeinbytesofthevirtualaddressspacetheprocessisusing.Useofvirtualaddressspacedoesnotnecessarilyimplycorrespondinguseofeitherdiskormainmemorypages.Virtualspaceisfinite,andbyusingtoomuch,theprocesscanlimititsabilitytoloadlibraries.
virtualSizePeak
Maximumnumberofbytesofvirtualaddressspacetheprocesshasusedatanyonetime.Useofvirtualaddressspacedoesnotnecessarilyimplycorrespondinguseofeitherdiskormainmemorypages.Virtualspaceishoweverfinite,andbyusingtoomuch,theprocessmightlimititsabilitytoloadlibraries.
workingSetS
©CopyrightPivotalSoftwareInc,2013-2019 338 9.1
Page 339
Size
CurrentnumberofbytesintheWorkingSetofthisprocess.TheWorkingSetisthesetofmemorypagestouchedrecentlybythethreadsintheprocess.Iffreememoryinthecomputerisaboveathreshold,pagesareleftintheWorkingSetofaprocesseveniftheyarenotinuse.Whenfreememoryfallsbelowathreshold,pagesaretrimmedfromWorkingSets.Ifpagesareneeded,theyarethensoft-faultedbackintotheWorkingSetbeforetheyarepagedouttodisk.
workingSetSizePeak
MaximumnumberofbytesintheWorkingSetofthisprocessatanypointintime.TheWorkingSetisthesetofmemorypagestouchedrecentlybythethreadsintheprocess.Iffreememoryinthecomputerisaboveathreshold,pagesareleftintheWorkingSetofaprocesseveniftheyarenotinuse.Whenfreememoryfallsbelowathreshold,pagesaretrimmedfromWorkingSets.IftheyareneededtheywillthenbesoftfaultedbackintotheWorkingSetbeforetheyleavemainmemory.
cpuUsage
PercentageCPUusedbythisprocess.
WindowsProcessStats
StatisticsforaMicrosoftWindowsprocess.
©CopyrightPivotalSoftwareInc,2013-2019 339 9.1
Page 340
LATESTVERSION:9.1.1- RELEASENOTES
InstallingtheSQLitePersistenceManagerThissectiondescribeshowtodownload,buildandinstalltheSQLitedatabaselibrariesforusewithdiskoverflow.
SeePersistenceManagerforadditionalinformationabouttheSQLitedatabaselibraries.
LinuxInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronLinux.
SolarisInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronSolaris.
WindowsInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronWindows.
©CopyrightPivotalSoftwareInc,2013-2019 340 9.1
Page 341
LATESTVERSION:9.1.1- RELEASENOTES
LinuxInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronLinux.
The product-dir directoryreferstothepathtothedirectorythatcontainsthebuiltlibrary.
Thefollowinglibrariesmustbepresentintheruntimelinkingpath:
libSqLiteImpl.so isprovidedin product-dir/lib ,soitisalreadypresentintheruntimelinkingpath.
libsqlite3.so istheSQLiteLibrary.Youneedtocreatethislibraryandmakeavailableintheruntimelinkingpath,orcopiedto product-dir/lib ,asdescribedbelow.
ThelibraryhasbeentestedwithSQLitev3.7.14.1.
Downloading,BuildingandInstallingtheLibraryCreatetheSQLitedatabaselibrarybydownloadingthelatest.zipfileandcompilingthesourcecode.
1. Downloadthesourcecode sqlite-autoconf-NNNNNNN.tar.gz file(whereNNNNNNNcorrespondstotheversion)forSQLitev3.7.14.1orlaterfromhttp://www.sqlite.org/download.html .
2. Extractthesourcecodefromthe.tar.gzfile.Forexample:
tar-xvfsqlite-autoconf-3071401.tar.gz
3. Changedirectoriestotheextractedsourcefiles,andfollowtheinstallinstructionslocatedinthe“INSTALL”file.
a. Runthe configure commandfor32-bitor64-bitwiththefollowingoptions,allenteredonasinglecommandline.Changethe --prefix directoryspecificationtothelocationwhereyouwantthelibraries:
32-bit:CFLAGS="-m32"./configure--prefix=/desired-binary-location/sqlite-binaries
64-bit:./configure--prefix=/desired-binary-location/sqlite-binaries
b. Run gmakeinstall asdescribedinthebuildinstructions.Thelibrarieswillbeavailableinthe sqlite-binaries directoryspecified.
4. Copy /desired-binary-location/sqlite-binaries/lib/libsqlite3.so fileto product-dir/lib .
©CopyrightPivotalSoftwareInc,2013-2019 341 9.1
Page 342
LATESTVERSION:9.1.1- RELEASENOTES
SolarisInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronSolaris.
The product-dir directoryreferstothepathtothedirectorythatcontainsthebuiltlibrary.
Thefollowinglibrariesmustbepresentintheruntimelinkingpath:
libSqLiteImpl.so isprovidedin product-dir/lib ,soitisalreadypresentintheruntimelinkingpath.
libsqlite3.so istheSQLiteLibrary.Youneedtocreatethislibraryandmakeavailableintheruntimelinkingpath,orcopiedto product-dir/lib ,asdescribedbelow.
ThelibraryhasbeentestedwithSQLitev3.7.14.1.
Downloading,Building,andInstallingtheLibraryCreatetheSQLitedatabaselibrarybydownloadingthelatest.zipfileandcompilingthesourcecode.
1. Downloadthesourcecode sqlite-autoconf-NNNNNNN.tar.gz file(whereNNNNNNNcorrespondstotheversion)forSQLitev3.7.14.1orlaterfromhttp://www.sqlite.org/download.html .
2. UpdateyourPATHenvironmentvariabletoincludethelocationoftheSolaris ar command.
exportPATH=/usr/css/bin:$PATH
3. Extractthesourcecodefromthe.tar.gzfile.Firstunzip:
gzip-dsqlite-autoconf-3071401.tar.gz
Thenuntarthefile:
tar-xvfsqlite-autoconf-3071401.tar
4. Changedirectoriestotheextractedsourcefiles,andfollowtheinstallinstructionslocatedinthe“INSTALL”file.
a. Runthe configure commandfor32-bitor64-bitSolarissystemswiththefollowingoptions,allenteredonasinglecommandline.Changethe --prefix directoryspecificationtothelocationwhereyouwantthelibraries:
32-bit:CC=ccCFLAGS="-xarch=v8plus-code=pic32"./configure--prefix=/desired-binary-location/sqlite-binaries
64-bit:CC=ccCFLAGS="-xarch=v9-code=pic32"./configure--prefix=/desired-binary-location/sqlite-binariesCFLAGS="-m64"
b. Run gmakeinstall .Thelibrarieswillbeavailableinthe sqlite-binaries directoryspecified.
5. Copy /desired-binary-location/sqlite-binaries/lib/libsqlite3.so fileto product-dir/lib .
©CopyrightPivotalSoftwareInc,2013-2019 342 9.1
Page 343
LATESTVERSION:9.1.1- RELEASENOTES
WindowsInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronWindows.
ThelibraryhasbeentestedwithSQLitev3.7.14.1.
The product-dir directoryreferstothepathtothedirectorythatcontainsthebuiltlibrary.
Thefollowinglibrariesarerequired.The product-dir/bin directorycontainingtheselibrariesmustbepresentintheWindows PATH environmentvariable,andthatdirectoryisaddedtoPATH duringtheGemFireproductinstallation.
The sqliteimpl.dll and Apache.Geode.Plugins.SQLite.dll filesareprovidedin product-dir/bin .
For.NETC#nativeclientapplicationdevelopment,youneedtoobtainthe System.Data.SQLite.dll SQLitelibrary,asdescribedbelow.Thelibrarycanbecopiedtoproduct-dir/bin .
ForC++nativeclientapplicationdevelopment,youneedthe SqLite3.dll SQLiteLibrary.Youcreatethislibraryandmakeitavailableintheruntimelinkingpath,orcopiedtoproduct-dir/bin ,asdescribedbelow.
DownloadingPre-builtSystem.Data.SQLite.dllBinariesIfyouarewritingnativeclientapplicationsusingthe.NETcachingAPI,obtaintheSQLitelibrary(version3.12.2orlater)forWindowsasfollows:
1. AccesstheSystem.Data.SQLiteDownloadPageatthefollowingURL:http://system.data.sqlite.org/index.html/doc/trunk/www/downloads.wiki .
2. Downloadtheappropriatesetupfileforyour.NETFrameworkinstallationandhardwarearchitecture.
For64-bitWindows,underPrecompiledBinariesfor64-bitWindows(.NETFramework4.5.1)download sqlite-netFx451-binary-bundle-x64-2013-1.0.101.0.zip
3. Executethesetup.exefile,andfollowthepromptsintheinstallationwizard.Acceptalldefaultinstallationoptions.
4. Copythe C:\ProgramFiles\System.Data.SQLite\2010\bin\System.Data.SQLite.dll filetoyourdistributionat product-dir\bin .
Downloading,Building,andInstallingtheLibraryIfyouarewritingnativeclientapplicationsusingtheC++cachingAPI,youneedtobuildtheSQLitesolutionforyourWindowsplatformarchitecture.
1. Downloadthesourcecode sqlite-autoconf-NNNNNNN.tar.gz file(whereNNNNNNNcorrespondstotheversion)forSQLiteversion3.12.2orlaterfromhttp://www.sqlite.org/download.html .
2. Extractthesourcecodefromthe.tar.gzfile.YoumayneedtouseCygWinoraWindows-compatibletarextractiontool.
3. UsingVisualStudio,buildtheversion-specificSqLitesolutioneitherasareleaseordebugbuild:
Ifyouareusing64-bitWindows,usethex64configuration.
4. Fromthebuiltfiles,copythe SqLite3.dll filetoyourdistributionat product-dir/bin .
©CopyrightPivotalSoftwareInc,2013-2019 343 9.1
Page 344
LATESTVERSION:9.1.1- RELEASENOTES
GlossaryThisglossarydefinestermsusedinthedocumentation.
APIApplicationProgrammingInterface.GemFireprovidesAPIstocacheddataforC++and.NETapplications.
applicationprogramAprogramdesignedtoperformaspecificfunctiondirectlyfortheuseror,insomecases,foranotherapplicationprogram.GemFireapplicationsusetheGemFireapplicationprogramminginterfaces(APIs)tomodifycacheddata.
cacheAcachecreatedbyanapplicationorcacheserverprocess.Fortheprocess,itscacheisthepointofaccesstoallcachingfeaturesandtheonlyviewofthecachethatisavailable.Cachecreationrequiresmembershipinthedistributedsystem.Seealsolocalcacheandremotecache.
cacheconfigurationfileAnXMLfilethatdeclarestheinitialconfigurationofacache,commonlynamed cache.xml .C++and.NETapplicationscanconfigurethecacheadditionallythroughtheGemFireprogrammingAPIs.
cachelistenerUser-implementedplug-inforreceivingandhandlingregionentryevents.Aregion’scachelisteneriscalledafteranentryinthelocalcacheismodified.
cacheloaderUser-implementedplug-inforloadingdataintoaregion.Aregion’scacheloaderisusedtoloaddatathatisrequestedoftheregionbutisnotavailableinthedistributedsystem.Foradistributedregion,theloaderthatisusedcanbeinadifferentcachefromtheonewherethedata-requestoperationoriginated.SeealsocachewriterandnetSearch.
cacheserverAlong-running,configurablecachingprocess,generallyusedtoservecacheddatatotheapplications.Usually,cacheserversareconfiguredtooperateasserversinaclient-servertypologyandtheirregionsareconfiguredtobereplicates.Seealsoserver.
cachewriterUser-implementedplug-inintendedforsynchronizingthecachewithanoutsidedatasource.Aregion’scachewriterisasynchronouslistenertocachedataevents.Thecachewriterhastheabilitytoabortadatamodification.Seealsocacheloader.
cachingenabledSpecifieswhetherdataiscachedintheregion.GemFiregivesyoutheoptionofrunningapplicationswithoutentrycaching.Forexample,youcanconfigureadistributedsystemasasimplemessagingservice.
©CopyrightPivotalSoftwareInc,2013-2019 344 9.1
Page 345
clientInaclient-servertopology,clientscanconnecttocacheservers,createnewregionsonthecacheserver,andstoredatainthecacheserverregion.Clientscanalsoconnecttoexistingregionsonacacheserveranddodirectedgetsandputsonthecacheserver.Clientsdonottrackmembershipinformationaboutotherclients,nordotheyshareinformationwithotherclients.
concurrencylevelAnestimateofthenumberofthreadsexpectedtoconcurrentlymodifyvaluesintheregion.Theactualconcurrencymayvary;thisvalueisusedtooptimizetheallocationofsystemresources.
connectionWhatanapplicationusestoaccessaGemFiredistributedsystem.AnapplicationcanconnecttoaGemFiresystembycallingtheDistributedSystem::connect functionwiththeappropriateparametersettings.AnapplicationmustconnecttoadistributedsystemtogainaccesstoGemFirefunctionality.
destroyRemoveanentryfromaregionorremovearegionfromacache.
diskpolicyDetermineswhetherLRUentriesexceedingtheentrieslimitforacachingregionaredestroyedorwrittentodisk.
distributedscopeEnablesaregiontoautomaticallysendentryvalueupdatestoremotecachesandincorporateupdatesreceivedfromremotecaches.Thescopeidentifieswhetherdistributionoperationsmustwaitforacknowledgementfromothercachesbeforecontinuing.Adistributedregion’scacheloaderandcachewriter(definedinthelocalcache)canbeinvokedforoperationsoriginatinginremotecaches.
distributedsystemOneormoreGemFiresystemmembersthathavebeenconfiguredtocommunicatewitheachother,formingasingle,logicalsystem.Alsousedfortheobjectthatisinstantiatedtocreatetheconnectionbetweenthedistributedsystemmembers.
DTDDocumentTypeDefinition.AlanguagethatdescribesthecontentsofaStandardGeneralizedMarkupLanguage(SGML)document.TheDTDisalsousedwithXML.TheDTDdefinitionscanbeembeddedwithinanXMLdocumentorinaseparatefile.
entryAdataobjectinaregion.Aregionentryconsistsofakeyandavalue.Thevalueiseithernull(invalid)oranobject.Aregionentryknowswhatregionitisin.Seealsoregiondatakey,andentryvalue.
entrykeyTheuniqueidentifierforanentryinaregion.
©CopyrightPivotalSoftwareInc,2013-2019 345 9.1
Page 346
entryvalueThedatacontainedinanentry.
expirationAcachedobjectexpireswhenitstime-to-liveoridletimeoutcountersareexhausted.Aregionhasonesetofexpirationattributesforitselfandonesetforallregionentries.
expirationactionTheactiontobetakenwhenacachedobjectexpires.Theexpirationactionspecifieswhethertheobjectistobeinvalidatedordestroyed,andwhethertheactionistobeperformedonlyinthelocalcacheorthroughoutthedistributedsystem.Adestroyedobjectiscompletelyremovedfromthecache.Aregionisinvalidatedbyinvalidatingallentriescontainedintheregion.Anentryisinvalidatedbyhavingitsvaluemarkedasinvalid.
Expirationattributesaresetattheregionlevelfortheregionandattheentrylevelforentries.Seealsoidletimeoutandtime-to-live.
factorymethodAninterfaceforcreatinganobjectwhichatcreationtimecanletitssubclassesdecidewhichclasstoinstantiate.Thefactorymethodhelpsinstantiatetheappropriatesubclassbycreatingthecorrectobjectfromagroupofrelatedclasses.
idletimeoutTheamountoftimearegionorregionentrymayremaininthecacheunaccessedbeforebeingexpired.Accesstoanentryincludesany get operationandanyoperationthatresetstheentry’stime-to-livecounter.Regionaccessincludesanyoperationthatresetsanentryidletimeout,andanyoperationthatresetstheregion’stime-to-live.
Idletimeoutattributesaresetattheregionlevelfortheregionandattheentrylevelforentries.Seealsotime-to-liveandexpirationaction.
interestlistAmechanismthatallowsaregiontomaintaininformationaboutreceiversforaparticularkey-valuepairintheregion,andsendoutupdatesonlytothosenodes.Interestlistsareparticularlyusefulwhenyouexpectalargenumberofupdatesonakeyaspartoftheentrylifecycle.
invalidThestateofanobjectwhenthecacheholdingitdoesnothavethecurrentvalueoftheobject.
invalidateRemoveonlythevalueofanentryinacache,nottheentryitself.
listenerAneventhandler.Thelistenerregistersitsinterestinoneormoreeventsandisnotifiedwhentheeventsoccur.
loadfactorAregionattributethatsetsinitialparametersontheunderlyinghashmapusedforstoringregionentries.
©CopyrightPivotalSoftwareInc,2013-2019 346 9.1
Page 347
localcacheThepartofthedistributedcachethatisresidentinthecurrentprocess.Thistermisusedtodifferentiatethecachewhereaspecificoperationisbeingperformedfromothercachesinthedistributedsystem.Seealsoremotecache.
localscopeEnablesaregiontoholdaprivatedatasetthatisnotvisibletoothercaches.Seealsoscope.
LRULeastRecentlyUsed.Referstoaregionentryorentriesmosteligibleforevictionduetolackofinterestbyclientapplications.
LRUentrieslimitAregionattributethatsetsthemaximumnumberofentriestoholdinacachingregion.Whenthecapacityofthecachingregionisexceeded,LRUisusedtoevictentries.
membershipApplicationsandcacheserversconnecttoaGemFiredistributedsystembyinvokingthestaticfunctionDistributedSystem::connect .Throughthisconnection,theapplicationgainsaccesstotheAPIsfordistributeddatacaches.WhenaC++or.NETapplicationconnectstoadistributedsystem,itspecifiesthesystemitisconnectingtobyindicatingthecommunicationprotocolandaddresstousetofindothersystemmembers.
netSearchThemethodusedbyGemFiretosearchremotecachesforadataentrythatisnotfoundinthelocalcacheregion.Thisoperatesonlyondistributedregions.
overflowsAnevictionoptionthatcausesthevaluesofLRUentriestobemovedtodiskwhentheregionreachescapacity.Seediskpolicy.
persistencemanagerThepersistencemanagermanagesthememory-to-diskanddisk-to-memoryactionsforLRUentries.Seeoverflows.
regionAlogicalgroupingofdatawithinacache.Regionsareusedtostoredataentries(seeentry).Eachregionhasasetofattributesgoverningactivitiessuchasexpiration,distribution,dataloading,events,andevictioncontrol.
regionattributesTheclassofattributesgoverningthecreation,location,distribution,andmanagementofaregionanditsentries.
regiondataAlloftheentriesdirectlycontainedintheregion.
©CopyrightPivotalSoftwareInc,2013-2019 347 9.1
Page 348
regionentrySeeentry.
remotecacheAnypartofthedistributedcachethatisresidentinaprocessotherthanthecurrentone.Ifanapplicationorcacheserverdoesnothaveadataentryintheregioninitslocalcache,itcandoa netSearch inanattempttoretrievetheentryfromtheregioninaremotecache.Seealsolocalcache.
scopeRegionattribute.Identifieswhetheraregionkeepsitsentriesprivateorautomaticallysendsentryvalueupdatestoremotecachesandincorporatesupdatesreceivedfromremotecaches.Thescopealsoidentifieswhetherdistributionoperationsmustwaitforacknowledgementfromothercachesbeforecontinuing.Seealsodistributedscopeandlocalscope
serializationTheprocessofconvertinganobjectgraphtoastreamofbytes.
serverInaclient-servertopology,theservermanagesmembershipandallowsremoteoperations.Theservermaintainsmembershipinformationforitsclientsinthedistributedsystem,alongwithinformationaboutpeerapplicationsandotherserversinthesystem.Seealsocacheserver.
systemmemberAprocessthathasestablishedaconnectiontoadistributedsystem.
time-to-liveTheamountoftimearegionorregionentrymayremaininthecachewithoutbeingmodifiedbeforebeingexpired.Entrymodificationincludescreation,update,andremoval.Regionmodificationincludescreation,update,orremovaloftheregionoranyofitsentries.
Time-to-liveattributesaresetattheregionlevelfortheregion,andattheentrylevelforentries.Seealsoidletimeoutandexpirationaction.
XMLEXtensibleMarkupLanguage.AnopenstandardfordescribingdatafromtheW3C,XMLisamarkuplanguagesimilartoHTML.Botharedesignedtodescribeandtransformdata,butwhereHTMLusespredefinedtags,XMLallowstagstobedefinedinsidetheXMLdocumentitself.UsingXML,virtuallyanydataitemcanbeidentified.TheXMLprogrammercreatesandimplementsdata-appropriatetagswhosesyntaxisdefinedinanXSD(XMLschemadefinition)oraDTD(DocumentTypeDefinition)file.
XMLschemadefinitionThedefinitionofthestructure,content,andsemanticsusedinanXMLdocument.Thedefinitioncanbeusedtoverifythateachitemofcontentinadocumentadherestothespecificationoftheelementinwhichthecontentisplaced.TheXMLschemaisasupersetofDTD.UnlikeDTD,XMLschemasarewritteninXMLsyntax,which,althoughmoreverbosethanDTD,aremoredescriptiveandcanhavestrongertyping.FilescontainingXMLschemadefinitionsgenerallyhavetheXSDextension.
XSDSeeXMLschemadefinition.
©CopyrightPivotalSoftwareInc,2013-2019 348 9.1
Page 349
©CopyrightPivotalSoftwareInc,2013-2019 349 9.1