Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
PivotalGemFire®NativeClient9.1
Note:ThesupportperiodforGemFireNativeClient9.1hasexpired,andthisversionisnolongersupported.Tostayuptodatewiththelatestsoftwareandsecurityupdates,upgradetoasupportedversion.
©CopyrightPivotalSoftwareInc,2013-2019
289
101213141516181921212225282930313233343536394043444546474849505050515253545556575859616263
TableofContents
TableofContentsPivotalGemFire®NativeClient9.1DocumentationPivotalGemFireNativeClient9.1ReleaseNotesGemFireNativeClientSupportedConfigurationsGettingStartedwithaNativeClientAbouttheClientInstallingtheNativeClientRunningClientApplicationsDevelopingC++ProgramsonLinuxDevelopingC++ProgramsonSolarisDevelopingC++ProgramsonWindowsQuickStartExamplesConfiguringtheQuickStartEnvironmentAbouttheQuickStartExamplesRunningtheExamplesSettingSystemPropertiesConfiguringtheClientandServerClientConfigurationCacheServerConfigurationAttributeDefinitionPrioritySearchPathforMultiplePropertiesFilesOverridingPropertiesFileSettingsDefiningPropertiesProgrammaticallyAttributesinthePropertiesFilePropertiesFileExampleUsingtheDefaultSampleFileConfiguringtheNativeClientCacheCachesAbouttheClientCacheCacheAPIsLocal,Remote,andDistributedCachesCreatingandAccessingaCacheClosingtheCacheCacheInitializationFile(cache.xml)CacheInitializationFileBasicsExamplecache.xmlFileRegionsDeclarativeRegionCreationProgrammaticRegionCreationInvalidatingandDestroyingRegionsRegionAccessGettingtheRegionSizeRegionEntriesEntryDistributionRequirementsRegisteringInterestforEntriesUsingserverKeystoRetrieveaSetofRegionKeysAddingEntriestotheCacheUpdatingEntries
©CopyrightPivotalSoftwareInc,2013-2019 2 9.1
646566676869707172737475767778798385909192939495969799
100101102103104105106107108110112113118119120122124125130131132133134
AccessingEntriesInvalidatingorDestroyingCachedEntriesNotificationforOperationsRegionConsistencyRegionAttributesSpecifyingRegionAttributesRegionShortcutsMutableandImmutableRegionAttributesCachingEnabledInitialCapacityLoadFactorConcurrencyLevelConcurrencyChecksEnabledLruEntriesLimitDiskPolicyPersistenceManagerSpecifyingExpirationAttributesApplicationPlug-insCacheManagementClient-to-ServerConnectionProcessControllingCacheSizeManagingtheLifetimeofaCachedObjectUsingThreadSafetyinCacheManagementTroubleshootingC++ClientAPIAbouttheC++ClientAPICreatingaCacheCreatingaProxyClient-SideRegionAddinganEntrytotheCacheAccessinganEntryRemovinganEntrySerializingDataRegionDataRequiringSerializationDataSerializationOptionsSerializingDatawithPDXSerializationSerializeYourDomainObjectswithPdxSerializerandPdxWrapperSerializeUsingthePdxSerializableClassPerformingput,get,andlocalDestroyOperationswithaPDXDomainObjectUsingAutomaticPDXSerializationProgrammingYourApplicationtoUsePdxInstancesConfiguringPDXtoIgnoreUnreadFieldsDuringDeserializationUsingPdxInstanceFactorytoCreatePdxInstancesUsingC++EnumTypewithPDXSerializationUsingPDXSerializationwithDeltaPropagationSerializingDatawiththeSerializableInterfaceSerializingObjectGraphsSerializingandAccessingDataasaBlobImplementingUser-DefinedObjectsinJavaClientsUsingaCustomClassCreatingNewStatistics
©CopyrightPivotalSoftwareInc,2013-2019 3 9.1
135136137138139140141142143144146148149150151152153154155156157158159160161162163165166167168169170171173174176178179180181182183184185186187188189190
.NETClientAPIAboutthe.NETClientAPI.NETNamingandUsageConventionsPrimaryAPIsCacheAPIsRegionandEntryAPIsDataSerializationAPIsEventHandlingAPIsPropertyCollectionsandLoggingAPIsC++Classto.NETClassMappingsJavato.NETTypeMappingTableObjectLifetimes.NETApplicationDomainsProblemScenariosCreatingaCacheCreatingaRegionAddinganEntrytotheCacheAccessinganEntryRemovinganEntryDataSerializationDataSerializationOptionsSerializewithPDXSerializationGemFirePDXSerializationFeaturesSerializeUsingtheGemFirePDXAutoserializerExtendthePDXAutoserializerSerializeYourDomainObjectswithIPdxSerializerSerializeUsingtheIPdxSerializableInterfaceProgramYourApplicationtoUseIPdxInstanceUsetheIPdxInstanceFactorytoCreateIPdxInstancesMap.NETDomainTypeNamestoPDXTypeNameswithIPdxTypeMapperSerializewiththeIGeodeSerializableInterfaceGenericandCustomSerializableTypesHowSerializationWorkswithIGeodeSerializableImplementtheIGeodeSerializableInterfaceRegistertheTypeUsingaCustomClassWithIGeodeSerializableApplicationCallbacksASimpleC#ExampleTroubleshooting.NETApplicationsResolvingtheErrorUsingApache.Geode.dllAsaPrivateAssemblyImplementingtheSharedAssemblyPreservingDataHighAvailabilityforClient-ServerCommunicationConfiguringClientsforHighAvailabilitySendingPeriodicAcknowledgmentEnablingQueueConflationtoImproveUpdatePerformanceDurableClientMessagingDurableClientMessagingRequirementsClient-SideConfiguration
©CopyrightPivotalSoftwareInc,2013-2019 4 9.1
191192193194195196197198199200201202203204205206208209210211212213214215216217218219220221221221223224225226227229230231232233234235236237238239241242
ConfiguringaDurableClientConfiguringDurableInterestinKeysConfiguringDurableClientReconnectionSendingCacheReadyMessagestotheServerDisconnectingfromtheServerLifeCycleofaDurableClientInitialOperationDisconnectionReconnectionDurableMessageReplayApplicationOperationsDuringInterestRegistrationImplementingCacheListenersforDurableClientsSecurityAuthenticationProcessandMultiuserAuthenticationConfiguringCredentialsforAuthenticationConfiguringAuthenticationbytheCacheServerServerAuthenticationErrorsCreatingMultipleSecureUserConnectionsRequirementsandCaveatsforRegionServiceUsinganLDAPServerforClientAuthenticationEncryptedAuthenticationEncryptCredentialswithDiffe-HellmanUsingPKCSforEncryptedAuthenticationClientAuthorizationConfiguringClientAuthorizationPost-OperativeAuthorizationDeterminingPre-orPost-OperationAuthorizationSecurity-RelatedSystemProperties(gemfire.properties)SSLClient/ServerCommunicationSetUpOpenSSLStartingandstoppingtheclientandserverwithSSLinplaceRemoteQueryingRemoteQueryingBasicsExampleDataandClassDefinitionsExecutingaQueryfromtheClientQueryingthePortfoliosRegionModifyingCacheContentsCreatingIndexesRemoteQueryingRequirementsUsingQueryStringsintheClientFROMClauseUsingIteratorVariablesImportingandUsingObjectClassesPredefinedClassTypesSpecifyingtheObjectTypesofFROMClauseCollectionsSELECTProjectionListSELECTStatementQueryResultsWHEREClauseJoins
©CopyrightPivotalSoftwareInc,2013-2019 5 9.1
243244245246247248249250251252253254255256257260261263264265266271272273274275276277278279280281282283284286287288289290291292293294297298300301302303
AccessingCachedDataBasicRegionAccessAttributeVisibilityModifyingQueryScopeNestedQueryScopesWhenNamesCannotBeResolvedQueryLanguageElementsMethodInvocationSupportedQueryLanguageLiteralsTypeConversionsRemoteQueryAPICreatingandManagingQueriesQueryResultSetsQueryCodeSamplesReturningResultSetQueryCodeSamplesReturningStructSetContinuousQueryingHowContinuousQueryingWorksImplementingaContinuousQueryConfiguringYourSystemforContinuousQueryingWritingtheContinuousQueryWritingtheCQListenerorCQStatusListenerCqEventObjectRunningtheContinuousQueryCodeCQExecutionOptionsWhenanErrorOccursinaRunningCQManagingContinuousQueriesCQAPIandMainFeaturesUsingConnectionPoolsHowClientLoadBalancingWorksServerLocatorsConnectionPoolsDiscoveringLocatorsDynamicallyConfiguringPoolsNativeClientPoolAPIPoolConfigurationExampleandSettingsSubscriptionPropertiesRunningtheConnectionPoolCodeTransactionsHowClientTransactionsWorkRunningaTransactionSuspendingandResumingTransactionsFunctionExecutionUnderstandingData-AwareFunctionRoutingHowFunctionsExecuteExecutingFunctionsRunningtheFunctionProgrammingtoGetFunctionResultsSolutionsandUseCasesDeltaPropagationHowDeltaPropagationWorks
©CopyrightPivotalSoftwareInc,2013-2019 6 9.1
304305306307309310311312313314318320323324325326327328329330331332333334335336337341342343344345
DeltaPropagationAPICloningImplementingDeltaPropagationExceptionsandLimitationsProgrammingExamplesDeclaringaClientRegionAPIProgrammingExample–C#APIProgrammingExample–C++DataSerializationExamplesC++SerializationExampleC#SerializationExampleJavaSerializationExampleInteroperabilityofLanguageClassesandTypesInteroperabilityofC++TypesWhenUsingPDXSerializationSystemStatisticsSamplingStatisticsSystemPerformanceStatisticsRegionStatisticsCachePerformanceStatisticsContinuousQueryStatisticsCQServiceStatisticsPoolStatisticsDeltaStatisticsOperatingSystemStatisticsLinuxProcessStatisticsSolarisProcessStatisticsWindowsProcessStatisticsInstallingtheSQLitePersistenceManagerLinuxInstallationSolarisInstallationWindowsInstallationGlossary
©CopyrightPivotalSoftwareInc,2013-2019 7 9.1
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
RunningClientApplicationsSetuptheenvironmentfortheGemFireclientonmultipleplatforms.Compileandrunclientprograms.
DevelopingC++ProgramsonLinuxThissectiondescribeshowtobuildandrunaclientapplicationonLinux.
DevelopingC++ProgramsonSolarisThissectiondescribeshowtobuildandrunaclientapplicationonSolaris.
DevelopingC++ProgramsonWindowsGemFireusestheVisualStudio2010ServicePack1compilerforC++programsonWindows,whichinvokesMicrosoft cl.exe fromthecommandlineatcompiletime.®
©CopyrightPivotalSoftwareInc,2013-2019 15 9.1
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
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
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
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
©CopyrightPivotalSoftwareInc,2013-2019 20 9.1
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
SettingSystemPropertiesThissectiondescribeshowtoconfigureclientsandcacheserverstoparticipateinadistributedsystem.
ConfiguringtheClientandServerYoucanconfigureclientsthroughfilesandAPIcalls.Theserversareconfiguredthroughcommand-lineinputandconfigurationfiles.
AttributesinthePropertiesFileAvarietyof geode.properties settingscanbeusedwhenaclientconnectstoadistributedsystem.
PropertiesFileExampleUsethegeode.propertiesfiletoconfiguredistributedsystemconnectionsfortheclient.
©CopyrightPivotalSoftwareInc,2013-2019 28 9.1
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
OverridingPropertiesFileSettingsApplicationdevelopershavetheoptionofconfiguringsystemattributesprogrammatically,ratherthanusingthe geode.properties file.
Attributessetprogrammaticallyoverrideanymatchingattributesettingsinthe geode.properties file,butadditionalattributesnotsetprogrammaticallywillbeconfiguredusingthesettingsin geode.properties .
©CopyrightPivotalSoftwareInc,2013-2019 34 9.1
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
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
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
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
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
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
#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
©CopyrightPivotalSoftwareInc,2013-2019 42 9.1
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
Local,Remote,andDistributedCachesThedistributedsystemdefineshowclientandserverprocessesfindeachother.
Thedistributedsystemkeepstrackofitsmembershiplistandmakesitsmembersawareoftheidentitiesoftheothermembersinthedistributedsystem.
Acachewithintheclientisreferredtoasitslocalcache.Allothercachesinthedistributedsystemareconsideredremotecachestotheapplication.Everycacheserverandapplicationprocesshasitsowncache.Thetermdistributedcacheisusedtodescribetheunionofallcachesinthedistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 47 9.1
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
LATESTVERSION:9.1.1- RELEASENOTES
ClosingtheCacheUsethe Cache::close functiontoreleasesystemresourceswhenyoufinishusingthecache.
Afterthecacheisclosed,anyfurthermethodcallsonthecacheoranyregionobjectresultina CacheClosedException .
Ifthecacheisinadurableclient,youneedtousethe keepalive versionoftheclosemethod.SeeDisconnectingFromtheServer.
©CopyrightPivotalSoftwareInc,2013-2019 49 9.1
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
RegionAccessYoucanuse Cache::getRegion toretrieveareferencetoaspecifiedregion.
RegionPtr returns NULL iftheregionisnotalreadypresentintheapplication’scache.Aserverregionmustalreadyexist.
Aregionnamecannotcontainthesecharacters:
<
>
:
“
/
\
|
?
*
©CopyrightPivotalSoftwareInc,2013-2019 55 9.1
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
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
LATESTVERSION:9.1.1- RELEASENOTES
EntryDistributionRequirementsEntrydatadistributedamongmembersofthedistributedsystemmustbeserializable.Entrykeysandvaluesareserializedfordistribution.
Ifaclientdefinesaregion,itmustregisteranyserializabletypesforallclassesofobjectsstoredintheregion.Thisincludesentriesthattheapplicationgetsorputs,aswellasentriesthatarepushedtotheclient’scacheautomaticallythroughdistribution.Thetypesmustberegisteredbeforetheclientconnectstothedistributedsystem.
SeeSerializingData formoreinformationabouttheserequirements.
©CopyrightPivotalSoftwareInc,2013-2019 58 9.1
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
SpecifyingRegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.
Specifyregionattributesbeforecreatingtheregion.YoucandothiseitherthroughthedeclarativeXMLfileorthroughtheAPI.TheAPIincludesclassesfordefiningaregion’sattributesbeforecreationandformodifyingsomeofthemaftercreation.Fordetails,seetheAPIfor RegionShortcut , RegionAttributes , AttributesFactory ,and AttributesMutator .
©CopyrightPivotalSoftwareInc,2013-2019 69 9.1
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
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
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
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
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
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
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
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
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
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
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
///<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
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
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
©CopyrightPivotalSoftwareInc,2013-2019 84 9.1
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
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
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
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
SpecifyingApplicationPlug-InAttributesTheplug-inattributesallowyoutocustomizeclientregionbehaviorforloading,updating,deleting,andoverflowingregiondataandforaccessingdatainserverpartitionedregions.Allclientplug-insareavailablethroughtheC++and.NETAPI.
Applicationplug-insforcacheregionsinclientscanbedeclaredeitherprogrammaticallyorinthe cache.xml file.
Figure:WhereApplicationPlug-InsRun
©CopyrightPivotalSoftwareInc,2013-2019 89 9.1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
#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
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
#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
#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
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
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
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
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
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
//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
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
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
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
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
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
Primitiveobjecttypessupportedinalllanguages( CacheableInt32 , CacheableString , CacheableBytes )functionwithoutrequiringcustomdefinitionswiththeJavacacheserver.Forthekeys,theJavacacheserverhastodeserializethemandlocatethehashcodetobeabletoinserttheinternalmaps.Becauseofthis,keytypesforC++clientsusedwithaJavaserverarerequiredtoberegisteredontheJavaserver,butthevaluetypesdonotneedtoberegistered.ThisneedstobedoneeveniftherearenoJavaclients.
©CopyrightPivotalSoftwareInc,2013-2019 129 9.1
LATESTVERSION:9.1.1- RELEASENOTES
SerializingObjectGraphsIfyouhaveagraphofobjectswhereeachnodecanbeserializable,theparentnodecancall DataOutput::writeObject todelegatetheserializationresponsibilitytoitschildnodes.Similarly,yourapplicationcancall DataInput::readObject todeserializetheobjectgraph.
©CopyrightPivotalSoftwareInc,2013-2019 130 9.1
LATESTVERSION:9.1.1- RELEASENOTES
SerializingandAccessingDataasaBlobIfyouhavedatathatisbesthandledasablob,suchasstructsthatdonotcontainpointers,usetheserializabletype CacheableBytes . CacheableBytes isablobclassthatimplementstheserializationforyou.
CacheableBytes alsoprovidesdirectaccesstotheblobdata.Becauseitisnotderivedfromthe CacheableKey interface, CacheableBytes enablesyoutomodifydatainplaceandthenputitintotheregionagaintodistributethechange.
©CopyrightPivotalSoftwareInc,2013-2019 131 9.1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
ResolvingtheErrorEachcomputerwherethecommonlanguageruntimeisinstalledhasamachine-widecodecachecalledtheGlobalAssemblyCache(GAC).Theglobalassemblycachestoresassembliesspecificallydesignatedtobesharedbyseveralapplicationsonthecomputer.
Asageneralguideline,keepassemblydependenciesprivate,andlocateassembliesintheapplicationdirectoryunlesssharinganassemblyisexplicitlyrequired.Shareassembliesbyinstallingthemintotheglobalassemblycacheonlywhennecessary.
©CopyrightPivotalSoftwareInc,2013-2019 180 9.1
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
HighAvailabilityforClient-ServerCommunicationTheclientprovidesreliableeventmessagingfromcacheservertoclienttopreventdatalossduringserverfailoveroperations.Highavailabilityisimplementedinthecacheserverandisconfiguredintheclient.
SeeserverdocumentationatConfiguringHighlyAvailableServers fordetailsaboutconfiguringaserverforhighavailability.
ConfiguringClientsforHighAvailabilityConfigurehighavailabilitybysettingthepoolattribute subscription-redundancy tothenumberofcopiesmaintained.
SendingPeriodicAcknowledgmentServersuseperiodicacknowledgmenttoreducethelikelihoodofduplicatenotifications,andtoreduceresourceusage.
©CopyrightPivotalSoftwareInc,2013-2019 184 9.1
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
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
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
InitialOperationTheinitialstartupofadurableclientissimilartothestartupofanyotherclient,exceptthatitspecificallycallstheCache.readyForEvents methodwhenallregionsandlistenersontheclientarereadytoprocessmessagesfromtheserver.
SeeSendingtheCacheReadyMessagetotheServer.
©CopyrightPivotalSoftwareInc,2013-2019 197 9.1
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
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
ServerAuthenticationErrorsAn AuthenticationRequiredException isthrownwhentheserverisconfiguredwithsecurityandtheclientdoesnotpresentitscredentialswhileattemptingtoconnect.Thiscanoccurifthesecurityclient-auth-factory and security-client-auth-library propertiesarenotconfiguredontheclient.
©CopyrightPivotalSoftwareInc,2013-2019 209 9.1
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
EncryptedAuthenticationYoucansetupencryptedauthenticationusingDiffe-HellmanorthesamplePKCSimplementation.
EncryptCredentialswithDiffe-HellmanForsecuretransmissionofsensitivecredentialslikepasswords,encryptcredentialsusingtheDiffie-Hellmankeyexchangealgorithm.WithDiffie-Hellmanenabled,youcanhaveyourclientauthenticateitsservers.
UsingPKCSforEncryptedAuthenticationThissectiondiscussestheconceptsandconfigurationsforthesampleUserPasswordandPKCSimplementations.Descriptionsoftheirinterfaces,classes,andmethodsareavailableintheAPI.
©CopyrightPivotalSoftwareInc,2013-2019 213 9.1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
AccessingCachedDataAccessingyourcacheddatathroughthequeryingserviceissimilartoaccessingdatabasecontentsthroughSQLqueries.Howyouspecifyyourregionsandregioncontentsisparticulartotheclient.
Thequerylanguagesupportsdrillingdownintonestedobjectstructures.RegionscancontainnesteddatacollectionsthatareunavailableuntilreferencedintheFROMclause.
Thisdiscussiondescribeshowtonavigatetoyourcacheddatathroughtheclientqueryservice.
Queryingandindexingonlyoperateonremotecacheservercontents.
©CopyrightPivotalSoftwareInc,2013-2019 243 9.1
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
WhenNamesCannotBeResolvedWhenaqueryisexecutedandanameorpathexpressionresolvestomorethanoneregionnameinthescope,orifthenamecannotberesolvedatall,theclientreceivesaThe QueryException containsthemessagethatisgeneratedfortheexceptionthatoccursontheserver.
©CopyrightPivotalSoftwareInc,2013-2019 248 9.1
LATESTVERSION:9.1.1- RELEASENOTES
QueryLanguageElementsThissectiondiscussesvariousaspectsandtoolsofthenativeclientqueryengine.
MethodInvocationThequerylanguagesupportsmethodinvocationinsidequeryexpressions.
SupportedQueryLanguageLiteralsQuerylanguageexpressionscancontainliteralsaswellasoperatorsandattributenames.Theclientsupportsmanytypesofliterals.
TypeConversionsJavaruleswithinaquerystringrequirethequeryprocessortoperformimplicitconversionsandpromotionsundercertaincasesinordertoevaluateexpressionsthatcontaindifferenttypes.
©CopyrightPivotalSoftwareInc,2013-2019 249 9.1
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
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
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
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
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
ContinuousQueryingContinuousQueryingdescribeshowtoimplementcontinuousqueryinginthePivotalGemFirenativeclientsothatC++and.NETclientscanrunqueriesagainsteventsintheGemFirecacheserverregion.ItalsodescribesmainfeaturesandthenativeclientCQAPI.
HowContinuousQueryingWorksC++and.NETclientsregisterinterestineventsusingsimplequeryexpressions.Eventsaresenttoclientlistenersthatyoucanprogramtodowhateveryourapplicationrequires.
ImplementingaContinuousQueryYoucanspecifyCQsforanyclientregion.
ManagingContinuousQueriesThissectiondiscusseshowtoaccessandmanageyourCQsfromyourclient.Thecallsdiscussedhereareallexecutedspecificallyforthecallingclient.AclientcannotaccessormodifytheCQsbelongingtoanotherclient.
CQAPIandMainFeaturesThischapterdocumentstheprimarynativeclientAPIforCQmanagement.
©CopyrightPivotalSoftwareInc,2013-2019 260 9.1
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
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
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
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
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
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
//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
{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
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
©CopyrightPivotalSoftwareInc,2013-2019 270 9.1
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
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
UsingConnectionPoolsUsingConnectionPoolsdescribeshowconnectionpoolsachieveloadbalancingfortheclientanddescribeshowtoconfigureconnectionpoolsasserverlocatorsorasalistofservers.
HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.
ConfiguringPoolsApoolcanbeconfiguredaslocatorsorasalistofservers.
©CopyrightPivotalSoftwareInc,2013-2019 277 9.1
LATESTVERSION:9.1.1- RELEASENOTES
HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.
TheconnectionpoolAPIsupportsconnectingtoserversthroughserverlocatorsordirectlyconnectingtoservers.
ServerLocatorsServerlocatorscontinuouslymonitorserveravailabilityandserverloadinformation.Theclientisconfiguredwithalistofserverlocatorsandconsultsaserverlocatortorequestaconnectiontoaserverinthedistributedsystem.
ConnectionPoolsClientscontainconnectionpools.Eachregionisassociatedwithaconnectionpoolusingaregionattribute,andoperationsontheregionuseconnectionsfromtherespectivepools.
DiscoveringLocatorsDynamicallyAbackgroundthreadperiodicallyqueriesthelocatorforanyotherlocatorsjoiningthedistributedsystem.
©CopyrightPivotalSoftwareInc,2013-2019 278 9.1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Figure:Data-DependentFunctionInvokedFromaClient
Thisshowsthesamedata-dependentfunctionwiththeaddedspecificationofasetofkeysonwhichtorun.Serversthatdon’tholdanyofthekeysareleftoutofthefunctionexecution.
Figure:Data-DependentFunctionwithFilterInvokedfromaClient
Thisscenariodemonstratesthestepsinacalltoahighlyavailablefunction.Thecallfailsthefirsttimeononeoftheparticipatingserversandissuccessfullyrunasecondtimeonallservers.
Figure:HighlyAvailableData-DependentFunctionwithFailureonFirstExecutions
©CopyrightPivotalSoftwareInc,2013-2019 295 9.1
©CopyrightPivotalSoftwareInc,2013-2019 296 9.1
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
SolutionsandUseCasesThefunctionexecutionserviceprovidessolutionsfortheseapplicationusecases:
Anapplicationthatexecutesaserver-sidetransactionormakesdataupdatesusingtheGemFiredistributedlockingservice.
Anapplicationthatinitializessomeofitscomponentsonceoneachserver,whichmightbeusedlaterbyexecutedfunctions.
Initializationandstartupofathird-partyservice,suchasamessagingservice.
Anyarbitraryaggregationoperationthatrequiresiterationoverlocaldatasetsthatcanbedonemoreefficientlythroughasinglecalltothecacheserver.
Anykindofexternalresourceprovisioningthatcanbedonebyexecutingafunctiononaserver.
©CopyrightPivotalSoftwareInc,2013-2019 301 9.1
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
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
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
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
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
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
nolocaldatastorage,aswhenyouareusingthemtoprovidedataupdateinformationtolisteners.
Inlessobviouscases,aswhenanentryhasbeenlocallydeleted,firstthedeltaissent,thenthereceiverrequestsafullvalueandthatissent.Wheneverthefullvalueisreceived,anyfurtherdistributionstothereceiver’speersorclientsusesthefullvalue.
Nodeltasarepropagatedfor:
Transactionalcommitontheserver
The putAll operation
©CopyrightPivotalSoftwareInc,2013-2019 308 9.1
LATESTVERSION:9.1.1- RELEASENOTES
ProgrammingExamplesThischapterprovidesasetofprogrammingexamplestohelpyouunderstandtheclientAPI.
DeclaringaClientRegion
Thefollowingexampleshowshowtodeclareaclientregionina cache.xml file.
APIProgrammingExample–C#ThisC#programmingcodeinthenextexampledemonstrateshowtousetwoormoreclientssharingadistributedregioninaGeodecache.
APIProgrammingExample–C++
DataSerializationExamples
©CopyrightPivotalSoftwareInc,2013-2019 309 9.1
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
LATESTVERSION:9.1.1- RELEASENOTES
APIProgrammingExample–C#SeeQuickStartExamplesforC#programmingexamples.
©CopyrightPivotalSoftwareInc,2013-2019 311 9.1
LATESTVERSION:9.1.1- RELEASENOTES
APIProgrammingExample–C++SeeQuickStartExamplesforC++programmingexamples.
©CopyrightPivotalSoftwareInc,2013-2019 312 9.1
LATESTVERSION:9.1.1- RELEASENOTES
DataSerializationExamplesThissectioncontainsdataserializationexamplesforC++,C#,andJava.
C++SerializationExample
C#SerializationExample
JavaSerializationExample
©CopyrightPivotalSoftwareInc,2013-2019 313 9.1
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
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
}
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
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
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
returnthis;}
publicvoidToData(DataOutputoutput){output.writeUTF(m_name);output.writeInt32(m_userId);eo.ToData(output);}
#endregion}
©CopyrightPivotalSoftwareInc,2013-2019 319 9.1
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
InteroperabilityofLanguageClassesandTypesThissectionprovidesatablethatmapsC++classmethodstocorresponding.NETclassmethodsandatablethatmapsJavatypesto.NETtypes.
C++Classto.NETClassMappings
Javato.NETTypeMappingTable
©CopyrightPivotalSoftwareInc,2013-2019 323 9.1
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
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
LATESTVERSION:9.1.1- RELEASENOTES
SamplingStatisticsWhenapplicationsandcacheserversjoinadistributedsystem,theyindicatewhethertoenablestatisticssamplingandwhethertoarchivethestatisticsthataregathered.
Thefollowingstatisticsarerelatedtothestatisticsampler.
sampleCount Totalnumberofsamplestakenbythissampler.
sampleTime Totalamountoftimespenttakingsamples.
StatSampler Statisticsonthestatisticsampler.
Formoreinformationaboutconfiguringstatistics,seeAttributesingeode.properties.
©CopyrightPivotalSoftwareInc,2013-2019 326 9.1
LATESTVERSION:9.1.1- RELEASENOTES
SystemPerformanceStatisticsPerformancestatisticsarecollectedforeachapplicationorcacheserverthatconnectstoadistributedsystem.
RegionStatisticsThesemethodshelptogetthestatisticsofaregion.
CachePerformanceStatisticsUsecacheperformancestatisticstodeterminethetypeandnumberofcacheoperationsbeingperformedandhowmuchtimetheyconsume.
ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.
CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.
PoolStatisticsUsethepoolobjecttogetstatisticsonconnectionpools.
DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.
©CopyrightPivotalSoftwareInc,2013-2019 327 9.1
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
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
LATESTVERSION:9.1.1- RELEASENOTES
ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.
inserts TotalnumberofinsertsforthisCQquery.
updates TotalnumberofupdatesforthisCQquery.
deletes TotalnumberofdeletesforthisCQquery.
events TotalnumberofeventsforthisCQquery.
©CopyrightPivotalSoftwareInc,2013-2019 330 9.1
LATESTVERSION:9.1.1- RELEASENOTES
CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.
CqsActive TotalnumberofCQsactiveforthisCQservice.
CqsCreated TotalnumberofCQscreatedforthisCQservice.
CqsClosed TotalnumberofCQsclosedforthisCQservice.
CqsStopped TotalnumberofCQsstoppedforthisCQservice.
CqsOnClient TotalnumberofCQsontheclientforthisCQservice.
©CopyrightPivotalSoftwareInc,2013-2019 331 9.1
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
LATESTVERSION:9.1.1- RELEASENOTES
DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.
deltaMessageFailures Totalnumberofmessagescontainingdelta(receivedfromserver)butcouldnotbeprocessedafterreception.
deltaPuts Totalnumberofputscontainingdeltathathavebeensentfromclienttoserver.
processedDeltaMessages Totalnumberofmessagescontainingdeltareceivedfromserverandprocessedafterreception.
processedDeltaMessagesTime Totaltimespentapplyingdelta(receivedfromserver)onexistingvaluesatclient.
©CopyrightPivotalSoftwareInc,2013-2019 333 9.1
LATESTVERSION:9.1.1- RELEASENOTES
OperatingSystemStatisticsUseoperatingsystemstatisticstodetermineamember’sCPU,memory,anddiskusage.
LinuxProcessStatisticsUsethesemethodstogetinformationaboutaLinuxoperatingsystemprocess.
SolarisProcessStatisticsUsethesemethodstogetinformationaboutaSolarisoperatingsystemprocess.
WindowsProcessStatisticsUsethesemethodstogetinformationaboutaWindowsoperatingsystemprocess.
©CopyrightPivotalSoftwareInc,2013-2019 334 9.1
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
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
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
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
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
LATESTVERSION:9.1.1- RELEASENOTES
InstallingtheSQLitePersistenceManagerThissectiondescribeshowtodownload,buildandinstalltheSQLitedatabaselibrariesforusewithdiskoverflow.
SeePersistenceManagerforadditionalinformationabouttheSQLitedatabaselibraries.
LinuxInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronLinux.
SolarisInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronSolaris.
WindowsInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronWindows.
©CopyrightPivotalSoftwareInc,2013-2019 340 9.1
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
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
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
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
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
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
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
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
©CopyrightPivotalSoftwareInc,2013-2019 349 9.1