Pivotal GemFire® Native Client 9 · 2019-11-05 · Using Apache.Geode.dll As a Private Assembly Implementing the Shared Assembly Preserving Data High Availability for Client-Server

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


135136137138139140141142143144146148149150151152153154155156157158159160161162163165166167168169170171173174176178179180181182183184185186187188189190

.NETClientAPIAboutthe.NETClientAPI.NETNamingandUsageConventionsPrimaryAPIsCacheAPIsRegionandEntryAPIsDataSerializationAPIsEventHandlingAPIsPropertyCollectionsandLoggingAPIsC++Classto.NETClassMappingsJavato.NETTypeMappingTableObjectLifetimes.NETApplicationDomainsProblemScenariosCreatingaCacheCreatingaRegionAddinganEntrytotheCacheAccessinganEntryRemovinganEntryDataSerializationDataSerializationOptionsSerializewithPDXSerializationGemFirePDXSerializationFeaturesSerializeUsingtheGemFirePDXAutoserializerExtendthePDXAutoserializerSerializeYourDomainObjectswithIPdxSerializerSerializeUsingtheIPdxSerializableInterfaceProgramYourApplicationtoUseIPdxInstanceUsetheIPdxInstanceFactorytoCreateIPdxInstancesMap.NETDomainTypeNamestoPDXTypeNameswithIPdxTypeMapperSerializewiththeIGeodeSerializableInterfaceGenericandCustomSerializableTypesHowSerializationWorkswithIGeodeSerializableImplementtheIGeodeSerializableInterfaceRegistertheTypeUsingaCustomClassWithIGeodeSerializableApplicationCallbacksASimpleC#ExampleTroubleshooting.NETApplicationsResolvingtheErrorUsingApache.Geode.dllAsaPrivateAssemblyImplementingtheSharedAssemblyPreservingDataHighAvailabilityforClient-ServerCommunicationConfiguringClientsforHighAvailabilitySendingPeriodicAcknowledgmentEnablingQueueConflationtoImproveUpdatePerformanceDurableClientMessagingDurableClientMessagingRequirementsClient-SideConfiguration


191192193194195196197198199200201202203204205206208209210211212213214215216217218219220221221221223224225226227229230231232233234235236237238239241242

ConfiguringaDurableClientConfiguringDurableInterestinKeysConfiguringDurableClientReconnectionSendingCacheReadyMessagestotheServerDisconnectingfromtheServerLifeCycleofaDurableClientInitialOperationDisconnectionReconnectionDurableMessageReplayApplicationOperationsDuringInterestRegistrationImplementingCacheListenersforDurableClientsSecurityAuthenticationProcessandMultiuserAuthenticationConfiguringCredentialsforAuthenticationConfiguringAuthenticationbytheCacheServerServerAuthenticationErrorsCreatingMultipleSecureUserConnectionsRequirementsandCaveatsforRegionServiceUsinganLDAPServerforClientAuthenticationEncryptedAuthenticationEncryptCredentialswithDiffe-HellmanUsingPKCSforEncryptedAuthenticationClientAuthorizationConfiguringClientAuthorizationPost-OperativeAuthorizationDeterminingPre-orPost-OperationAuthorizationSecurity-RelatedSystemProperties(gemfire.properties)SSLClient/ServerCommunicationSetUpOpenSSLStartingandstoppingtheclientandserverwithSSLinplaceRemoteQueryingRemoteQueryingBasicsExampleDataandClassDefinitionsExecutingaQueryfromtheClientQueryingthePortfoliosRegionModifyingCacheContentsCreatingIndexesRemoteQueryingRequirementsUsingQueryStringsintheClientFROMClauseUsingIteratorVariablesImportingandUsingObjectClassesPredefinedClassTypesSpecifyingtheObjectTypesofFROMClauseCollectionsSELECTProjectionListSELECTStatementQueryResultsWHEREClauseJoins


243244245246247248249250251252253254255256257260261263264265266271272273274275276277278279280281282283284286287288289290291292293294297298300301302303

AccessingCachedDataBasicRegionAccessAttributeVisibilityModifyingQueryScopeNestedQueryScopesWhenNamesCannotBeResolvedQueryLanguageElementsMethodInvocationSupportedQueryLanguageLiteralsTypeConversionsRemoteQueryAPICreatingandManagingQueriesQueryResultSetsQueryCodeSamplesReturningResultSetQueryCodeSamplesReturningStructSetContinuousQueryingHowContinuousQueryingWorksImplementingaContinuousQueryConfiguringYourSystemforContinuousQueryingWritingtheContinuousQueryWritingtheCQListenerorCQStatusListenerCqEventObjectRunningtheContinuousQueryCodeCQExecutionOptionsWhenanErrorOccursinaRunningCQManagingContinuousQueriesCQAPIandMainFeaturesUsingConnectionPoolsHowClientLoadBalancingWorksServerLocatorsConnectionPoolsDiscoveringLocatorsDynamicallyConfiguringPoolsNativeClientPoolAPIPoolConfigurationExampleandSettingsSubscriptionPropertiesRunningtheConnectionPoolCodeTransactionsHowClientTransactionsWorkRunningaTransactionSuspendingandResumingTransactionsFunctionExecutionUnderstandingData-AwareFunctionRoutingHowFunctionsExecuteExecutingFunctionsRunningtheFunctionProgrammingtoGetFunctionResultsSolutionsandUseCasesDeltaPropagationHowDeltaPropagationWorks


304305306307309310311312313314318320323324325326327328329330331332333334335336337341342343344345

DeltaPropagationAPICloningImplementingDeltaPropagationExceptionsandLimitationsProgrammingExamplesDeclaringaClientRegionAPIProgrammingExample–C#APIProgrammingExample–C++DataSerializationExamplesC++SerializationExampleC#SerializationExampleJavaSerializationExampleInteroperabilityofLanguageClassesandTypesInteroperabilityofC++TypesWhenUsingPDXSerializationSystemStatisticsSamplingStatisticsSystemPerformanceStatisticsRegionStatisticsCachePerformanceStatisticsContinuousQueryStatisticsCQServiceStatisticsPoolStatisticsDeltaStatisticsOperatingSystemStatisticsLinuxProcessStatisticsSolarisProcessStatisticsWindowsProcessStatisticsInstallingtheSQLitePersistenceManagerLinuxInstallationSolarisInstallationWindowsInstallationGlossary


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.


http://gemfire-apis.docs.pivotal.io

https://gemfire-native.docs.pivotal.io/91/geode/setting-properties/chapter-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/client-cache/chapter-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/cpp-caching-api/cpp-caching-api.html

https://gemfire-native.docs.pivotal.io/releases/latest/api/cppdocs

https://gemfire-native.docs.pivotal.io/91/geode/dotnet-caching-api/dotnet-caching-api.html

https://gemfire-native.docs.pivotal.io/releases/latest/api/dotnetdocs

https://gemfire-native.docs.pivotal.io/91/geode/preserving-data/preserving-data.html

https://gemfire-native.docs.pivotal.io/91/geode/security/overviewsecurity.html

https://gemfire-native.docs.pivotal.io/91/geode/remote-querying/remote-querying.html

https://gemfire-native.docs.pivotal.io/91/geode/continuous-querying/continuous-querying.html

https://gemfire-native.docs.pivotal.io/91/geode/connection-pools/connection-pools.html

https://gemfire-native.docs.pivotal.io/91/geode/transactions/transactions.html

https://gemfire-native.docs.pivotal.io/91/geode/function-execution/function-execution.html

https://gemfire-native.docs.pivotal.io/91/geode/type-mappings/chapter-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/system-statistics/chapter-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/sqlite-persistence/chapter-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/glossary.html


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.


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


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.


https://www.microsoft.com/en-us/download/details.aspx?id=40784

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.


https://msdn.microsoft.com/en-us/library/dd831853(v=vs.120).aspx

https://gemfire-native.docs.pivotal.io/91/geode/security/sslclientserver.html


GettingStartedwithaNativeClientThissectiongivesyouaconceptualoverviewofthenativeclient.Itshowsyouhowtoinstalltheproduct,buildnativeclientapplicationsonvariousplatforms,andruntheproductexamples.

ThenativeclientprovidesaccessforC++andMicrosoft .NET™clientstoaGeodedistributedsystem.

AbouttheClient

ThenativeclientdeliversthefullsetofcapabilitiessuppliedbyJavaclientscommunicatingwithaGeodeserver.

InstallingtheNativeClientInstallthenativeclientbyextractingthecontentsofaZIPfileandsettinguptheenvironment.

RunningClientApplications

Setuptheenvironmentforthenativeclientonmultipleplatforms.Compileandrunclientprograms.

QuickStartExamplesRunthenativeclientQuickStartexamplestounderstandnativeclientfunctionality.

®


https://gemfire-native.docs.pivotal.io/91/geode/introduction/client-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/introduction/running-client-apps.html


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.



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


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


RunningClientApplicationsSetuptheenvironmentfortheGemFireclientonmultipleplatforms.Compileandrunclientprograms.

DevelopingC++ProgramsonLinuxThissectiondescribeshowtobuildandrunaclientapplicationonLinux.

DevelopingC++ProgramsonSolarisThissectiondescribeshowtobuildandrunaclientapplicationonSolaris.

DevelopingC++ProgramsonWindowsGemFireusestheVisualStudio2010ServicePack1compilerforC++programsonWindows,whichinvokesMicrosoft cl.exe fromthecommandlineatcompiletime.®



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.


-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


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.



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.


-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.



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.


/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.

®


http://msdn.microsoft.com/en-us/library/dd831853(v=vs.100).aspx

http://msdn.microsoft.com/en-us/library/vstudio/w0x726c2(v=vs.100).aspx



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.


https://cmake.org

http://java.sun.com

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


>cmake--build.--configRelease


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


>cmake--build.--configRelease


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


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.


https://gemfire-native.docs.pivotal.io/91/geode/cpp-caching-api/serialization-overview.html

https://gemfire-native.docs.pivotal.io/91/geode/client-cache/expiration-attributes.html

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.


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


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.


Enteroption:

Enteranumberfromthelisttostartthatexample

RunningaC#ExampleFromtheMenu

StarttheC#menu.

>runcsPleaseselectaGemFireC#QuickStartexampletorun.


Enteroption:

Enteranumberfromthelisttostartthatexample.


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.



SettingSystemPropertiesThissectiondescribeshowtoconfigureclientsandcacheserverstoparticipateinadistributedsystem.

ConfiguringtheClientandServerYoucanconfigureclientsthroughfilesandAPIcalls.Theserversareconfiguredthroughcommand-lineinputandconfigurationfiles.

AttributesinthePropertiesFileAvarietyof geode.properties settingscanbeusedwhenaclientconnectstoadistributedsystem.

PropertiesFileExampleUsethegeode.propertiesfiletoconfiguredistributedsystemconnectionsfortheclient.



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.



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.



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.



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.



SearchPathforMultiplePropertiesFilesTheclientandcacheserverprocessesfirstlookfortheirpropertiesfileinthe product-dir/defaultSystem directory,thenintheworkingdirectory.

Anypropertiessetintheworkingdirectoryoverridesettingsinthe defaultSystem/geode.properties file.

Ifyouarerunningmultipleprocessesononemachine,youcanconfigurethe geode.properties fileinthe defaultSystem directoryasasharedfilethatallprocessescanfind.Ifafewprocessesneedaslightlydifferentconfiguration,youcanputindividual geode.properties filesintheirhomedirectoriestooverridespecificproperties.



OverridingPropertiesFileSettingsApplicationdevelopershavetheoptionofconfiguringsystemattributesprogrammatically,ratherthanusingthe geode.properties file.

Attributessetprogrammaticallyoverrideanymatchingattributesettingsinthe geode.properties file,butadditionalattributesnotsetprogrammaticallywillbeconfiguredusingthesettingsin geode.properties .



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);



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


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


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.



PropertiesFileExampleUsethe geode.properties filetoconfiguredistributedsystemconnectionsfortheclient.

Thefollowingexampleshowstheformatofageode.propertiesfile.Thefirsttwoattributesinthisexampleshouldbesetbyprogrammersduringapplicationdevelopment,whileotherattributesareseton-siteduringsystemintegration.ThepropertiesandtheirdefaultsettingsthatcanbesetinthisfilearedescribedindetailinAttributesintheProperitesFile

geode.propertiesFileFormat

#TueFeb1417:24:02PDT2006log-level=infocache-xml-file=./cache.xmlstacktrace-enabled=true


https://gemfire-native.docs.pivotal.io/91/geode-native-client/setting-properties/propfile_attributes.html#attributes-gfcpp


UsingtheDefaultSampleFileAsample geode.properties fileisincludedwiththePivotalGemFirenativeclientinstallationinthe product-dir/defaultSystem directory.

Tousethisfile:

1. Copythefiletothedirectorywhereyoustarttheapplication.

2. Uncommentthelinesyouneedandeditthesettingsasshowninthisexample:

cache-xml-file=test.xml

3. Starttheapplication.

Defaultgeode.propertiesFile


#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




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.



CachesThecacheistheentrypointtodatacachinginGemFire.Throughthecache,clientsgainaccesstotheGemFirecachingframeworkfordataloading,distribution,andmaintenance.

AbouttheClientCacheThecacheconsistsofdataregions,eachofwhichcancontainanynumberofentries.Regionentriesholdthecacheddata.Everyentryhasakeythatuniquelyidentifiesitwithintheregionandavaluewherethedataobjectisstored.

CacheAPIsTheclienthastwocacheAPIs, RegionService and Cache .

Local,Remote,andDistributedCachesThedistributedsystemdefineshowclientandcacheserverprocessesfindeachother.

CreatingandAccessingaCacheWhenyoucreateaclientcache,youarecreatingaclientcacheinstance.Youmustprovidesomebasicconfigurationinformationsuchasaconnectionnameandcacheinitializationparametersfortheclient’scacheinstance.

ClosingtheCacheUsethe Cache::close functiontoreleasesystemresourceswhenyoufinishusingthecache.



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.



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.



Local,Remote,andDistributedCachesThedistributedsystemdefineshowclientandserverprocessesfindeachother.

Thedistributedsystemkeepstrackofitsmembershiplistandmakesitsmembersawareoftheidentitiesoftheothermembersinthedistributedsystem.

Acachewithintheclientisreferredtoasitslocalcache.Allothercachesinthedistributedsystemareconsideredremotecachestotheapplication.Everycacheserverandapplicationprocesshasitsowncache.Thetermdistributedcacheisusedtodescribetheunionofallcachesinthedistributedsystem.



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.



ClosingtheCacheUsethe Cache::close functiontoreleasesystemresourceswhenyoufinishusingthecache.

Afterthecacheisclosed,anyfurthermethodcallsonthecacheoranyregionobjectresultina CacheClosedException .

Ifthecacheisinadurableclient,youneedtousethe keepalive versionoftheclosemethod.SeeDisconnectingFromtheServer.



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"><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>


http://geode.apache.org/schema/cache/cache-1.0.xsd


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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/client-cache/geodeman/basic_config/data_regions/chapter_overview.html


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.


http://geode.apache.org/schema/cache/cache-1.0.xsd


ProgrammaticRegionCreationYoucreateregionsprogrammaticallywiththe regionFactory class.

Note:Beforecreatingaregion,specifyregionattributes.SeeRegionAttributes.

Createyourregionsusingthe regionFactory class.

C++RegionFactoryExample

RegionFactoryPtrregionFactory=cachePtr->createRegionFactory(CACHING_PROXY);RegionPtrregPtr0=regionFactory->setLruEntriesLimit(20000)->create("exampleRegion0");



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.



RegionAccessYoucanuse Cache::getRegion toretrieveareferencetoaspecifiedregion.

RegionPtr returns NULL iftheregionisnotalreadypresentintheapplication’scache.Aserverregionmustalreadyexist.

Aregionnamecannotcontainthesecharacters:

<

>

:

“

/

\

|

?

*



GettingtheRegionSizeThe Region APIprovidesa size method( Size propertyfor.NET)thatgetsthesizeofaregion.

Forclientregions,thisgivesthenumberofentriesinthelocalcache,notontheservers.

Seethe Region APIdocumentationfordetails.



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.



EntryDistributionRequirementsEntrydatadistributedamongmembersofthedistributedsystemmustbeserializable.Entrykeysandvaluesareserializedfordistribution.

Ifaclientdefinesaregion,itmustregisteranyserializabletypesforallclassesofobjectsstoredintheregion.Thisincludesentriesthattheapplicationgetsorputs,aswellasentriesthatarepushedtotheclient’scacheautomaticallythroughdistribution.Thetypesmustberegisteredbeforetheclientconnectstothedistributedsystem.

SeeSerializingData formoreinformationabouttheserequirements.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/cpp-caching-api/serialization_overview.html#concept_2A8DC49D93394392BA34B17AA3452B14


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:


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.



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.



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.



UpdatingEntriesAcachedentrycanbeupdatedusingthesemethods:

Explicitly,whenaclientinvokesa put operationonanexistingentry.

Implicitly,whena get isperformedonanentrythathasaninvalidvalueinthecache.AnentrycanbecomeinvalidthroughanexplicitAPIcall,throughanautomatedexpirationaction,orbybeingcreatedwithavalueofnull.

Automatically,whenanewentryvalueisdistributedfromanothercache.

Similartoentrycreation,alloftheseoperationscanbeabortedbyacachewriter.

The get functionreturnsadirectreferencetotheentryvalueobject.Achangemadeusingthatreferenceiscalledanin-placechangebecauseitdirectlymodifiesthecontentsofthevalueinthelocalcache.Fordetailsonsafecacheaccess,seeManagingtheLifetimeofaCachedObject.



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.



InvalidatingorDestroyingCachedEntriesInvalidatinganentrysetstheentry’svalueto NULL .Destroyingitremovestheentryfromtheregionaltogether.Theseoperationscanbecarriedoutinthelocalcacheinthefollowingways:

ThroughdirectAPIcallsfromtheclient.

Throughexpirationactivitiesbasedontheentry’sstatisticsandtheregion’sattributesettings.

Note:Auser-definedcachewriteriscalledbeforeanoperationiscompleted,andcanabortanentrydestroyoperation.

Whethercarriedoutexplicitlyorthroughexpirationactivities,invalidationanddestructioncauseeventnotification:The CacheEvent objecthasan isExpiration flagthatissettotrueforeventsresultingfromexpirationactivities,andsetto false forallotherevents.



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).



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/client-cache/geodeman/developing/distributed_regions/region_entry_versions.html#topic_CF2798D3E12647F182C2CEC4A46E2045


RegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.

Regionattributesettingsdeterminewherethedataresides,howtheregionismanagedinmemory,andtheautomaticloading,distribution,andexpirationofregionentries.

SpecifyingRegionAttributes

RegionShortcuts

MutableandImmutableRegionAttributes

CachingEnabled

InitialCapacity

LoadFactor

ConcurrencyLevel

ConcurrencyChecksEnabled

LruEntriesLimit

DiskPolicy

PersistenceManager

SpecifyingExpirationAttributes



SpecifyingRegionAttributesRegionattributesgoverntheautomatedmanagementofaregionanditsentries.

Specifyregionattributesbeforecreatingtheregion.YoucandothiseitherthroughthedeclarativeXMLfileorthroughtheAPI.TheAPIincludesclassesfordefiningaregion’sattributesbeforecreationandformodifyingsomeofthemaftercreation.Fordetails,seetheAPIfor RegionShortcut , RegionAttributes , AttributesFactory ,and AttributesMutator .



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.



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.



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>



InitialCapacityUsethisattribute,togetherwiththe LoadFactor attribute,tosettheinitialparametersontheunderlyinghashmapthatstoresregionentries.Thisisthenumberofentriesthattheregionmapwillbereadytoholdwhenitiscreated.

Thisdeclarationsetstheregion’sinitialcapacityto 10000 :

<region-attributesinitial-capacity="10000"></region-attributes>



LoadFactorUsethisattribute,togetherwiththe InitialCapacity attribute,tosettheinitialparametersontheunderlyinghashmapthatstoresregionentries.Whenthenumberofentriesinthemapexceedsthe LoadFactor timescurrentcapacity,thecapacityisincreasedandthemapisrehashed.Yougetthebestperformanceifyouconfigureaproperlysizedregionatthestartanddonothavetorehashit.

Thisdeclarationsetstheregion’sloadfactorto 0.75 :

<region-attributesload-factor="0.75"></region-attributes>



ConcurrencyLevelThisattributeestimatesthemaximumnumberofapplicationthreadsthatconcurrentlyaccessaregionentryatonetime.Thisattributehelpsoptimizetheuseofsystemresourcesandreducethreadcontention.

Thefollowingdeclarationsetstheregion’s ConcurrencyLevel to 16 :

<region-attributesconcurrency-level="16"></region-attributes>

Note:When CachingEnabled is false ,donotsetthe ConcurrencyLevel attribute.An IllegalStateException isthrowniftheattributeisset.



ConcurrencyChecksEnabledThisattributedetermineswhethermembersperformcheckstoprovideconsistenthandlingforconcurrentorout-of-orderupdatestodistributedregions.

Aclientcachecandisableconsistencycheckingforaregionevenifservercachesenableconsistencycheckingforthesameregion.Thisconfigurationensuresthattheclientseesalleventsfortheregion,butitdoesnotpreventtheclientcacheregionfrombecomingout-of-syncwiththeservercache.

Optionallyenableconcurrencychecksfortheregion.Example:

<region-attributesconcurrency-checks-enabled="true"></region-attributes>

SeeRegionConsistencyformoreinformation.



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.



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.



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.


http://www.sqlite.org

http://www.sqlite.org/compile.html#default_page_size

http://www.sqlite.org/compile.html#default_page_size

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:


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


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}



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.




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 .


Note:Donotperformregionoperationsinsidethecachelistener.Onceyouhaveconfiguredacachelistener,theeventsuppliesthenewentryvaluestotheapplication.Performingagetwithakeyfromthe EntryEvent canresultindistributeddeadlock.Formoreaboutthis,seetheAPIdocumentationfor EntryEvent .

Whenaregiondisconnectsfromacachelistener,youcanimplementthe afterRegionDisconnected callback.Thiscallbackisonlybeinvokedwhenusingthe pool APIand subscriptionenabledonthepool.Forexample:

classDisconnectCacheListener:publicCacheListener{voidafterRegionDisconnected(constRegionPtr&region){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++:


https://gemfire-native.docs.pivotal.io/91/geode-native-client/client-cache/geodeman/reference/topics/client-cache.html

https://gemfire-native.docs.pivotal.io/91/geode-native-client/client-cache/geodeman/developing/partitioned_regions/chapter_overview.html

https://gemfire-native.docs.pivotal.io/91/geode-native-client/client-cache/geodeman/developing/partitioned_regions/overview_custom_partitioning_and_data_colocation.html

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:


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&region){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&region){AttributesMutatorPtrregionAttributesMutator=region->getAttributesMutator();

//Changecachelistenerforregion.regionAttributesMutator->setCacheListener("Library","createTestCacheListener");}

Touse AttributesMutator toremoveaplug-infromaregion,settheplug-in’svalueto NULLPTR ,asshowninthefollowingexample.

voidremoveListener(RegionPtr&region){CacheListenerPtrnullListener=NULLPTR;AttributesMutatorPtrregionAttributesMutator=region->getAttributesMutator();

//ChangecachelistenerforregiontoNULLPTRregionAttributesMutator->setCacheListener(nullListener);}

ConsiderationsforImplementingCallbacksKeepyourcallbackimplementationslightweightandpreventsituationsthatmightcausethemtohang.Forexample,donotperformdistributionoperationsordisconnectsinsideeventhandlers.

Yourcodeshouldhandleanyexceptionsthatitgenerates.Ifnot,GemFirehandlesthemaswellaspossible.BecauseC++hasnostandardforexceptions,inmanycasesGemFirecanonlyprintan unknown

errormessage.


SpecifyingApplicationPlug-InAttributesTheplug-inattributesallowyoutocustomizeclientregionbehaviorforloading,updating,deleting,andoverflowingregiondataandforaccessingdatainserverpartitionedregions.Allclientplug-insareavailablethroughtheC++and.NETAPI.

Applicationplug-insforcacheregionsinclientscanbedeclaredeitherprogrammaticallyorinthe cache.xml file.

Figure:WhereApplicationPlug-InsRun



CacheManagementThissectioncoverscachemanagement.

Client-to-ServerConnectionProcessItisimportanttounderstandthesequenceofeventsthatoccurwhentheclientconnectswithaserver.

ControllingCacheSizeYoucancontrolcachesizethroughregionsizelimits,cachesizelimits,oracombinationofthetwo.

ManagingtheLifetimeofaCachedObjectAllcacheableobjectsderivefrom SharedBase ,whichprovidesreferencecounting.Cacheableobjectsarereferencedusing SharedPtr types.

UsingThreadSafetyinCacheManagementWhenyouperformstructuralchangesonyourcache,suchascreatingorclosingaCache , Pool ,or Region ,synchronizeyouroperationsordotheminasinglethread.

TroubleshootingThissectionprovidestroubleshootinginformationfortheclient.



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.



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 .



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.



UsingThreadSafetyinCacheManagementWhenyouperformstructuralchangesonyourcache,suchascreatingorclosingaCache , Pool ,or Region ,synchronizeyouroperationsordotheminasinglethread.

Othernon-structuraloperations,likeregiongets,puts,andqueries,arethreadsafe,andyoucanperformtheminamultithreadedway.Therearecaveatstothis,forexample,whentwothreadsupdatethesamekeysimultaneously,thereisnowaytodeterminewhichthread’soperationwillprevail.

Youmayneedtoprotectcachedobjectsfromconcurrentusageandmodification.Theclientdoesnotguardcachedobjectsthemselvesfromconcurrentaccess.

Alwayscatchandhandleexceptionsthatmaybethrown,forproblemsliketryingtocreatea Pool withthesamenamemorethanonce.



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).


http://support.microsoft.com/kb/226371/en-us

http://support.microsoft.com/kb/310426

http://support.microsoft.com/kb/146906


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.


http://geode.apache.org/docs/

https://gemfire-native.docs.pivotal.io/91/geode-native-client/introduction/quickstart.html


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.



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.



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();



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");



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.



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.



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.



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.



RegionDataRequiringSerializationCertainregiontypes(includingclientregions)requireserialization.

Regiondatainthefollowingtypesofregionsmustbeserializable:

Partitionedregions(exceptfunctionsthatadddatalocallytoapartitionedregionusethedeserializedform).

Distributedregions.

Regionsthatarepersistedoroverflowedtodisk.

Serverorclientregionsinaclient/serverinstallation.

Regionsdistributedbetweengatewaysinamulti-siteinstallation.

Regionsthatreceiveeventsfromremotecaches.

Regionsthatprovidefunctionargumentsandresults.

Tominimizethecostofserializationanddeserialization,GemFireavoidschangingthedataformatwheneverpossible.Thismeansyourdatamaybestoredinthecacheinserializedordeserializedform,dependingonhowyouuseit.Forexample,ifaserveractsonlyasastoragelocationfordatadistributionbetweenclients,itmakessensetoleavethedatainserializedform,readytobetransmittedtoclientsthatrequestit.Partitionedregiondataisalwaysstoredinserializedformwithoneexception—functionsthatadddatatoapartitionedregionlocallyusethedeserializedform.



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**


*Youcanmixdomainobjectversionswherethedifferencesbetweenversionsaretheadditionandremovalofobjectfields.

**SeeUsingPDXSerializationwithDeltaPropagationforrequirements.



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.



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.


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());



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


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);}



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());



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:


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


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:


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


#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());



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.



ConfiguringPDXtoIgnoreUnreadFieldsDuringDeserializationUsethe setPdxIgnoreUnreadFields APItocontrolwhetherPDXignoresfieldsthatwereunreadduringdeserialization.

Thedefaultistopreserveunreadfieldsbyincludingtheirdataduringserialization.However,ifyouconfigurethecachetoignoreunreadfieldsthentheirdatawillbelostduringserialization.

Youshouldonlysetthisattributeto true ifyouknowthismemberwillonlybereadingcachedata.InthisusecaseyoudonotneedtopaythecostofpreservingunreadfieldssinceyouwillneverreserializethePDXdata.

Forexample:

CacheFactoryPtrcfPtr=CacheFactory::createCacheFactory(PropertiesObj);cfPtr->setPdxReadSerialized(tue);cfPtr->setPdxIgnoreUnreadFields(false);cachePtr=cfPtr->create();



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);


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());}}



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:


//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");}



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...

};



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 :


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.


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 .


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


Primitiveobjecttypessupportedinalllanguages( CacheableInt32 , CacheableString , CacheableBytes )functionwithoutrequiringcustomdefinitionswiththeJavacacheserver.Forthekeys,theJavacacheserverhastodeserializethemandlocatethehashcodetobeabletoinserttheinternalmaps.Becauseofthis,keytypesforC++clientsusedwithaJavaserverarerequiredtoberegisteredontheJavaserver,butthevaluetypesdonotneedtoberegistered.ThisneedstobedoneeveniftherearenoJavaclients.



SerializingObjectGraphsIfyouhaveagraphofobjectswhereeachnodecanbeserializable,theparentnodecancall DataOutput::writeObject todelegatetheserializationresponsibilitytoitschildnodes.Similarly,yourapplicationcancall DataInput::readObject todeserializetheobjectgraph.



SerializingandAccessingDataasaBlobIfyouhavedatathatisbesthandledasablob,suchasstructsthatdonotcontainpointers,usetheserializabletype CacheableBytes . CacheableBytes isablobclassthatimplementstheserializationforyou.

CacheableBytes alsoprovidesdirectaccesstotheblobdata.Becauseitisnotderivedfromthe CacheableKey interface, CacheableBytes enablesyoutomodifydatainplaceandthenputitintotheregionagaintodistributethechange.



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.



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;}



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);



.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).


http://geode.apache.org/docs/

https://gemfire-native.docs.pivotal.io/91/geode-native-client/dotnet-caching-api/cpp-class-to-dotnet-class-mappings.html

https://gemfire-native.docs.pivotal.io/91/geode-native-client/dotnet-caching-api/java-to-dotnet-type-mapping.html


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.



.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.



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.



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.



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



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.



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.



PropertyCollectionsandLoggingAPIsThissectiondescribesclassesforpropertycollectionsandlogging.

Propertiesclass.Providesacollectionofproperties,eachofwhichisakey/valuepair.Eachkeyisastring,andthevaluecanbeastringoraninteger.

Logclass.DefinesmethodsavailabletoclientsthatneedtowritealogmessagetotheirGemFiresystemsharedlogfile.AnyattempttouseaninstanceafteritsconnectionisdisconnectedthrowsaNotConnectedException.Foranyloggedmessagethelogfilecontains:

Theloglevelofthemessage.Thetimethemessagewaslogged.TheIDoftheconnectionandthreadthatloggedthemessage.Themessageitself,possiblywithanexceptionincludingitsstacktrace.



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


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



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[]


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



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



.NETApplicationDomainsApplicationdomains,or AppDomain s,areunitsofisolation,securityboundaries,anddotheloadingandunloadingforapplicationsinthe.NETruntime.Multipleapplicationdomainscanruninasingleprocess.Eachcanhaveoneormanythreads,andathreadcanswitchapplicationdomainsatruntime.

The.NETmanagedassembliesrequireinterfacemethodsinvokedbytheC++layertobeinthesame AppDomain asthatofthe.NETDLL.Ifnot,anexceptionisthrownbecausethethreadisunabletocross AppDomain boundaries.



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.



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.



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");



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.



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.



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.



DataSerializationAlldatamovingoutoftheclientcachemustbeserializable.

Regiondatathatmustbeserializablefallsunderthefollowingcategories:

Partitionedregions(exceptfunctionsthatadddatalocallytoapartitionedregionusethedeserializedform).

Distributedregions.

Regionsthatarepersistedoroverflowedtodisk.

Serverorclientregionsinaclient/serverinstallation.

Regionsdistributedbetweengatewaysinamulti-siteinstallation.

Regionsthatreceiveeventsfromremotecaches.

Regionsthatprovidefunctionargumentsandresults.

Tominimizethecostofserializationanddeserialization,GemFireavoidschangingthedataformatwheneverpossible.Thismeansyourdatamaybestoredinthecacheinserializedordeserializedform,dependingonhowyouuseit.Forexample,ifaserveractsonlyasastoragelocationfordatadistributionbetweenclients,itmakessensetoleavethedatainserializedform,readytobetransmittedtoclientsthatrequestit.Partitionedregiondataisalwaysstoredinserializedformwithoneexception—functionsthatadddatatoapartitionedregionlocallyusethedeserializedform.



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.


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.



SerializewithPDXSerializationGemFire’sPortableDataeXchange(PDX)isacross-languagedataformatthatcanreducethecostofdistributingandserializingyourobjects.PDXstoresdatainnamedfieldsthatyoucanaccessindividually,toavoidthecostofdeserializingtheentiredataobject.PDXalsoallowsyoutomixversionsofobjectswhereyouhaveaddedorremovedfields.

YouhavetwooptionsforGemFirePDXserializationwhenusingthe.NETcachingAPI.Youcanprogramyourdomainobjectsusingthe IPdxSerializable interface,oryoucanuseGemFire’sreflection-basedautoserializer.



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.



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.



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);}}



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());



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:


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.



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.



UsetheIPdxInstanceFactorytoCreateIPdxInstancesYoucanusethe IPdxInstanceFactory tocreatean IPdxInstance fromrawdatawhenthedomainclassisnotavailableontheserver.

Thisoptioncanbeusefulwhenyouneedaninstanceofadomainclassforplug-incodesuchasafunctionoraloader.Ifyouhavetherawdataforthedomainobject(theclassnameandeachfield’stypeanddata),thenyoucanexplicitlycreatea IPdxInstance .The IPdxInstanceFactory isverysimilartothe IPdxWriter exceptthatafterwritingeachfield,youneedtocallthecreatemethodwhichreturnsthecreated IPdxInstance.

ViewthePdxInstanceQuickStartforanexample.



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_"}}


https://gemfire-native.docs.pivotal.io/91/geode-native-client/dotnet-caching-api/java-to-dotnet-type-mapping.html#concept_24D0AAC71FF1483AB47A7772DA018966


SerializewiththeIGeodeSerializableInterfaceThe.NET IGeodeSerializable interfaceprovidesfastandcompactdataserialization.

GenericandCustomSerializableTypesAllbuilt-ingenericsareautomaticallyregisteredatinitialization.Youhaveacoupleofoptionsforcomplexkeytypes.

HowSerializationWorkswithIGeodeSerializableWhenyourapplicationputsanobjectintothecachefordistribution,GemFireserializesthedatabytakingthesesteps.

ImplementtheIGeodeSerializableInterfaceTostoreyourowndatatypesinthecache,youimplementtheGemFire IGeodeSerializable interface.

RegistertheTypeTousethe BankAccount type,youmustregisteritwiththetypesystem.Then,whenanincomingstreamcontainsa BankAccount ,itcanbemanufacturedfromtheassociatedTypeFactoryMethod.



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.



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.



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:


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));}}}



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.



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.


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}



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 .


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}



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();}}}



Troubleshooting.NETApplicationsThe.NETFrameworkdoesnotfindmanagedDLLsusingtheconventional PATH environmentvariable.InorderforyourassemblytofindandloadamanagedDLL,itmusteitherbeloadedasaprivateassemblyusing assemblyBinding ,oritmustbeinstalledintotheGlobalAssemblyCache(GAC).

TheGACutilitymustberunoneverymachinethatrunsthe.NETcode.

Ifanassemblyattemptstoloadthe Apache.Geode.Client.dll withoutmeetingthisrequirement,a System.IO.FileNotFoundException willbethrown.



ResolvingtheErrorEachcomputerwherethecommonlanguageruntimeisinstalledhasamachine-widecodecachecalledtheGlobalAssemblyCache(GAC).Theglobalassemblycachestoresassembliesspecificallydesignatedtobesharedbyseveralapplicationsonthecomputer.

Asageneralguideline,keepassemblydependenciesprivate,andlocateassembliesintheapplicationdirectoryunlesssharinganassemblyisexplicitlyrequired.Shareassembliesbyinstallingthemintotheglobalassemblycacheonlywhennecessary.



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.



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/? .


https://msdn.microsoft.com


PreservingDataAservermaypreservethedataqueuedandintendedtobesenttoaclient,suchthatthedataisnotdiscardedifcommunicationbetweentheserverandclientisdisrupted.Preservationpreventsmessageloss,whichcancauseaclienttohaveinconsistentdata.Redundantqueuesandahighavailabilityserverimplementationmayfurtherensurethatqueueddataisnotlost.

Thereisatradeoffbetweenthequantityofdatathataservermustqueueandtheamountoftimethattheservermaintainsandcontinuestoqueuedataintendedforaclientthatisnotcommunicatingwiththedistributedsystem.Clientconfigurationspecifiestheamountoftimethattheserveristocontinuequeueingmessages.Highavailabilitypermitsasecondaryservertoassumetheroleofaprimaryserverwithrespecttoqueueddataintheeventthattheprimaryservernolongerfunctions.Designationofprimaryandsecondaryservers,aswellasthenumberofredundantcopiesofthequeueareconfigurable.

HighAvailabilityforClient-ServerCommunicationTheclientprovidesreliableeventmessagingfromcacheservertoclienttopreventdatalossduringserverfailoveroperations.Highavailabilityisimplementedinthecacheserverandisconfiguredintheclient.

EnablingQueueConflationtoImproveUpdatePerformanceConflationofentryupdatemessagescanreducethenumberofupdatemessagesaclientreceives,therebyincreasingperformance.Theclientreceivesonlythemostrecentupdateforaparticularentrykey.

DurableClientMessagingConfiguretheredundancylevelforclientqueuesthatarestoredoncacheservers.Thisensuresthattheclientwillnotlosemessagesifitlosestheconnectiontoitsprimaryserver.



HighAvailabilityforClient-ServerCommunicationTheclientprovidesreliableeventmessagingfromcacheservertoclienttopreventdatalossduringserverfailoveroperations.Highavailabilityisimplementedinthecacheserverandisconfiguredintheclient.

SeeserverdocumentationatConfiguringHighlyAvailableServers fordetailsaboutconfiguringaserverforhighavailability.

ConfiguringClientsforHighAvailabilityConfigurehighavailabilitybysettingthepoolattribute subscription-redundancy tothenumberofcopiesmaintained.

SendingPeriodicAcknowledgmentServersuseperiodicacknowledgmenttoreducethelikelihoodofduplicatenotifications,andtoreduceresourceusage.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/preserving-data/geodeman/developing/events/configuring_highly_available_servers.html


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.



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.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/preserving-data/geodeman/developing/events/conflate_server_subscription_queue.html


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.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/preserving-data/geodeman/developing/events/implementing_durable_client_server_messaging.html


Client-SideConfigurationAlldurablemessagingconfigurationsareperformedontheclient.

ConfiguringaDurableClientThedurableclientcanbeconfiguredinthe geode.properties file,orinthe CacheFactory::set(name,value) call.

ConfiguringDurableInterestinKeysWhenadurableclientdisconnects,itsserverskeepqueuingmessagesforselectedkeys.Theclientindicateswhichkeysbyregisteringdurableinterestforthosekeys.

ConfiguringDurableClientReconnectionYoucanconfigurethedurableclienttoobtainanapproximatecountofpendingeventsupondurableclientreconnection.Basedonthereturnednumber,youcandeterminewhethertoproceedandreceivethependingeventsortoclosethecache.



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);


https://gemfire-native.docs.pivotal.io/91/geode-native-client/preserving-data/geodeman/developing/events/implementing_durable_client_server_messaging.html


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.



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.



SendingCacheReadyMessagestotheServerAfteradurableclientconnectsandinitializesitscache,regions,cachelisteners,andanyinterestregistration,itinvokes readyForEvents toindicatetotheserversthattheclientisreadytoreceiveanymessagesaccumulatedforit.

DurableClientCacheReadyNotification(C++)Thefollowingexampleshowshowtocall readyForEvents .

//Sendreadyforeventmessagetoserver(onlyfordurableclients).//Serverwillsendqueuedeventstoclientafterreceivingthis.cachePtr->readyForEvents();

Tokeeptheclientfromlosingevents,donotcallthismethoduntilallregionsandlistenersarecreated.Formoreinformation,seeReconnection.



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);



LifeCycleofaDurableClientThissectiondiscussesthehigh-leveloperationofadurableclientthroughinitialstartup,disconnection,andreconnection.

InitialOperationTheinitialstartupofadurableclientissimilartothestartupofanyotherclient,exceptthatitspecificallycallstheCache.readyForEvents methodwhenallregionsandlistenersontheclientarereadytoprocessmessagesfromtheserver.

DisconnectionWhiletheclientandserversaredisconnected,theiroperationvariesdependingonthecircumstances.

ReconnectionDuringinitialization,operationsontheclientcachecancomefrommultiplesources.

DurableMessageReplayWhentheprimaryserverreceivesthecachereadymessage,theserversandclientexecuteaproceduretoupdatethequeueandreplaytheeventsfromthestoredmessages.

ApplicationOperationsDuringInterestRegistrationAssoonastheclientcreatesitsregions,theapplicationhostingtheclientcanstartcacheoperations,evenwhiletheclientisstillreceivingitsinterestregistrationresponses.



InitialOperationTheinitialstartupofadurableclientissimilartothestartupofanyotherclient,exceptthatitspecificallycallstheCache.readyForEvents methodwhenallregionsandlistenersontheclientarereadytoprocessmessagesfromtheserver.

SeeSendingtheCacheReadyMessagetotheServer.



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.



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.



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.



ApplicationOperationsDuringInterestRegistrationAssoonastheclientcreatesitsregions,theapplicationhostingtheclientcanstartcacheoperations,evenwhiletheclientisstillreceivingitsinterestregistrationresponses.

Inthatcase,applicationoperationstakeprecedenceoverinterestregistrationresponses.

Whenaddingregisterinterestresponsestothecache,thefollowingrulesareapplied:

Iftheentryalreadyexistsinthecachewithavalidvalue,itisnotupdated.

Iftheentryisinvalidandtheregisterinterestresponseisvalid,thevalidvalueisputintothecache.

Ifanentryismarkeddestroyed,itisnotupdated.Destroyedentriesareremovedfromthesystemaftertheregisterinterestresponseiscompleted.

Iftheinterestresponsedoesnotcontainanyresultsbecauseallofthosekeysareabsentfromtheserver’scache,theclient’scachecanstartoutempty.Ifthequeuecontainsoldmessagesrelatedtothosekeys,theeventsarestillreplayedintheclient’scache.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/preserving-data/geodeman/developing/events/implementing_cache_event_handlers.html


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.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/security/geodeman/topologies_and_comm/cs_configuration/chapter_overview.html


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.



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.


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);



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();}



ServerAuthenticationErrorsAn AuthenticationRequiredException isthrownwhentheserverisconfiguredwithsecurityandtheclientdoesnotpresentitscredentialswhileattemptingtoconnect.Thiscanoccurifthesecurityclient-auth-factory and security-client-auth-library propertiesarenotconfiguredontheclient.



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



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.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/security/geodeman/managing/security/chapter_overview.html#security


EncryptedAuthenticationYoucansetupencryptedauthenticationusingDiffe-HellmanorthesamplePKCSimplementation.

EncryptCredentialswithDiffe-HellmanForsecuretransmissionofsensitivecredentialslikepasswords,encryptcredentialsusingtheDiffie-Hellmankeyexchangealgorithm.WithDiffie-Hellmanenabled,youcanhaveyourclientauthenticateitsservers.

UsingPKCSforEncryptedAuthenticationThissectiondiscussestheconceptsandconfigurationsforthesampleUserPasswordandPKCSimplementations.Descriptionsoftheirinterfaces,classes,andmethodsareavailableintheAPI.



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.



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.



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.



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


https://gemfire-native.docs.pivotal.io/91/managing/security/authorization_example.html#authorization_example


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



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 .


https://gemfire-native.docs.pivotal.io/91/geode-native-client/security/geodeman/managing/security/authorization_overview.html


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àll`,`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.



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.


https://gemfire-native.docs.pivotal.io/serverman/about_gemfire.html

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


https://gemfire-native.docs.pivotal.io/91/geode-native-client/security/geodeman/configuring/running/starting_up_shutting_down.html


RemoteQueryingThissectiondocumentsremotequeryingfromtheclienttotheserver.Usingexamplesandprocedures,itdescribeshowtousetheAPIstorunqueriesagainstcacheddata,workwithquerystringsintheclient,createandmanagequeries,andcreateindexes.

RemoteQueryingBasicsUsetheclientqueryAPItoqueryyourcacheddatastoredonacacheserver.Thequeryisevaluatedandexecutedonthecacheserver,andtheresultsarereturnedtotheclient.

UsingQueryStringsintheClientTouseaquerystringinaclient,specifythestringasaparameterina QueryService::newQuery method,thenexecutethequeryusing Query::execute ,passingintherequiredparameters.

AccessingCachedDataAccessingyourcacheddatathroughthequeryingserviceissimilartoaccessingdatabasecontentsthroughSQLqueries.Howyouspecifyyourregionsandregioncontentsisparticulartotheclient.

QueryLanguageElementsThissectiondiscussesvariousaspectsandtoolsoftheclientqueryengine.

RemoteQueryAPIYouusetheclientqueryingAPItoaccessallthequeryingfunctionalitydiscussedintheprevioussections.



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.


http://www.odmg.org

https://gemfire-native.docs.pivotal.io/91/geode-native-client/remote-querying/91-quickintro/geodeman/developing/querying_basics/chapter_overview.html


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.



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());}



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’


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());}



ModifyingCacheContentsTomodifythecachebasedoninformationretrievedthroughquerying,retrievetheentrykeysandusetheminthestandardentryupdatemethods.

Thequeryserviceisadataaccesstool,soitdoesnotprovideanycacheupdatefunctionality.

Thenextexampleshowsentrykeyretrieval.

Getdistinctentrykeysandpositionsfromactiveportfolioswithatleasta$25.00marketvalueInthefollowingexample,retrievingtheentrykeysallowsyoutoaccessthecachedregionentriesforupdate.Youcannotupdatethecachethroughthequeryengine.

Querystring:SELECTDISTINCTkey,posnValFROM/portfolios.entrySet,value.positions.valuesposnValTYPEPositionWHEREposnVal.mktValue>=25.00

Results:ASelectResultsofStructinstancescontainingkey,Positionpairs.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/remote-querying/91-quickintro/geodeman/developing/query_index/query_index.html


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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/remote-querying/91-quickintro/geodeman/developing/distributed_regions/chapter_overview.html


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.



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.



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



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.



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



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.



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'



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.)



SELECT <*> FROM <multiple expression>

IMPORTjavaobject.Position;SELECTDISTINCT*

FROM/portfolios,positions.valuesTYPEPosition


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.



WHEREClauseTheoptionalWHEREclausedefinesthesearchcriteriafortheselection,filteringthesetofelementsspecifiedbytheFROMclause.

WithoutaWHEREclause,theSELECTprojectionlistreceivestheentirecollectionorsetofcollectionsasspecifiedintheFROMclause.

ThequeryprocessorsearchesthecollectionforelementsthatmatchtheconditionsspecifiedintheWHEREclauseconditions.IfthereisanindexonanexpressionmatchedbytheWHEREclause,thenthequeryprocessormayusetheindextooptimizethesearchandavoiditeratingovertheentirecollection.

AWHEREclauseexpressionisabooleanconditionthatisevaluatedforeachelementinthecollection.Iftheexpressionevaluatestotrueforanelement,thequeryprocessorpassesthatelementontotheSELECTprojectionlist.ThisexampleusestheWHEREclausetoreturntheportfolioobjectsintheregionthathaveatypexyz.

SELECTDISTINCT*FROM/portfoliosWHERE"type"='xyz'

Thenextqueryreturnsthesetofallportfolioswithatypeofxyzandactivestatus.

SELECTDISTINCT*FROM/portfoliosWHERE"type"='xyz'ANDstatus='active'



JoinsIfcollectionsinthe FROM clausearenotrelatedtoeachother,youcanusethe WHERE clausetojointhem.

Thestatementbelowreturnsallthepersonsfromthe /Persons regionwiththesamenameasaflowerinthe /Flowers region.

SELECTDISTINCTpFROM/Personsp,/FlowersfWHEREp.name=f.name

Indexesaresupportedforregionjoins.Tocreateindexesforregionjoins,youcreatesingle-regionindexesforbothsidesofthejoincondition.Theseareusedduringqueryexecutionforthejoincondition.



AccessingCachedDataAccessingyourcacheddatathroughthequeryingserviceissimilartoaccessingdatabasecontentsthroughSQLqueries.Howyouspecifyyourregionsandregioncontentsisparticulartotheclient.

Thequerylanguagesupportsdrillingdownintonestedobjectstructures.RegionscancontainnesteddatacollectionsthatareunavailableuntilreferencedintheFROMclause.

Thisdiscussiondescribeshowtonavigatetoyourcacheddatathroughtheclientqueryservice.

Queryingandindexingonlyoperateonremotecacheservercontents.



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 .



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



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.



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



WhenNamesCannotBeResolvedWhenaqueryisexecutedandanameorpathexpressionresolvestomorethanoneregionnameinthescope,orifthenamecannotberesolvedatall,theclientreceivesaThe QueryException containsthemessagethatisgeneratedfortheexceptionthatoccursontheserver.



QueryLanguageElementsThissectiondiscussesvariousaspectsandtoolsofthenativeclientqueryengine.

MethodInvocationThequerylanguagesupportsmethodinvocationinsidequeryexpressions.

SupportedQueryLanguageLiteralsQuerylanguageexpressionscancontainliteralsaswellasoperatorsandattributenames.Theclientsupportsmanytypesofliterals.

TypeConversionsJavaruleswithinaquerystringrequirethequeryprocessortoperformimplicitconversionsandpromotionsundercertaincasesinordertoevaluateexpressionsthatcontaindifferenttypes.



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.



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.



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.



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.



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'");



QueryResultSetsSelectResults.Executesthequeryonthecacheserverandreturnstheresultsaseithera ResultSet oraStructSet.

SelectResultsIterator.Iteratesovertheitemsavailableina ResultSet or StructSet .

ResultSet.Obtainedafterexecutinga Query ,whichisobtainedfroma QueryService thatisobtainedfromaCacheclass.

StructSet.Usedwhena SELECT statementreturnsmorethanonesetofresults.Thisisaccompaniedbya Struct ,whichprovidesthe StructSet definitionandcontainsitsfieldvalues.



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



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


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


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



ContinuousQueryingContinuousQueryingdescribeshowtoimplementcontinuousqueryinginthePivotalGemFirenativeclientsothatC++and.NETclientscanrunqueriesagainsteventsintheGemFirecacheserverregion.ItalsodescribesmainfeaturesandthenativeclientCQAPI.

HowContinuousQueryingWorksC++and.NETclientsregisterinterestineventsusingsimplequeryexpressions.Eventsaresenttoclientlistenersthatyoucanprogramtodowhateveryourapplicationrequires.

ImplementingaContinuousQueryYoucanspecifyCQsforanyclientregion.

ManagingContinuousQueriesThissectiondiscusseshowtoaccessandmanageyourCQsfromyourclient.Thecallsdiscussedhereareallexecutedspecificallyforthecallingclient.AclientcannotaccessormodifytheCQsbelongingtoanotherclient.

CQAPIandMainFeaturesThischapterdocumentstheprimarynativeclientAPIforCQmanagement.



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:


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.



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.



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


https://gemfire-native.docs.pivotal.io/91/geode-native-client/continuous-querying/serverman/developing/events/configuring_highly_available_servers.html


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.



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)


//CqListenerclasspublicclassTradeEventListener:ICqListener{voidOnEvent(CqEvent<TKey,TResult>êv){//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>êv){//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(){


{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)


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;}}




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.



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();



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.



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.



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.





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.





UsingConnectionPoolsUsingConnectionPoolsdescribeshowconnectionpoolsachieveloadbalancingfortheclientanddescribeshowtoconfigureconnectionpoolsasserverlocatorsorasalistofservers.

HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.

ConfiguringPoolsApoolcanbeconfiguredaslocatorsorasalistofservers.



HowClientLoadBalancingWorksInadistributedsystem,serverscanbeaddedorremovedandtheircapacitytoservicenewclientconnectionsmayvary.Theserverconnectivityoptionsarespecifiedintheconnectionpoolconfiguration.

TheconnectionpoolAPIsupportsconnectingtoserversthroughserverlocatorsordirectlyconnectingtoservers.

ServerLocatorsServerlocatorscontinuouslymonitorserveravailabilityandserverloadinformation.Theclientisconfiguredwithalistofserverlocatorsandconsultsaserverlocatortorequestaconnectiontoaserverinthedistributedsystem.

ConnectionPoolsClientscontainconnectionpools.Eachregionisassociatedwithaconnectionpoolusingaregionattribute,andoperationsontheregionuseconnectionsfromtherespectivepools.

DiscoveringLocatorsDynamicallyAbackgroundthreadperiodicallyqueriesthelocatorforanyotherlocatorsjoiningthedistributedsystem.



ServerLocatorsServerlocatorscontinuouslymonitorserveravailabilityandserverloadinformation.Theclientisconfiguredwithalistofserverlocatorsandconsultsaserverlocatortorequestaconnectiontoaserverinthedistributedsystem.

Locatorsprovideclientswithdynamicserverdiscoveryandserverloadbalancing.Theygiveclientsconnectioninformationfortheserverwiththeleastloadatanygiventime.

Serverlocatorsprovidethesemainfeatures:

Automateddiscoveryofserversandlocators.Addingandremovingserversorlocatorsismadeeasyaseachclientdoesnotrequirealistofserverstobeconfiguredatthetimeofpoolcreation.

Clientloadrebalancing.Serverlocatorsgiveclientsdynamicserverinformationandprovideserverloadrebalancingafterserversdepartorjointhesystem.

Highavailability.Whenaclient/serverconnectionreceivesanexception,theconnectionisautomaticallyfailedovertoanotheravailableconnectioninthepool.Redundancyisalsoprovidedforclientsubscriptions.

Alternatively,youcanconfigureapoolstaticallywithalistofendpoints.Whenthepoolsarestaticallyconfigured,around-robinloadbalancingpolicyisusedtodistributeconnectionsacrosstheservers.



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.


https://gemfire-native.docs.pivotal.io/91/reference/topics/client-cache.html#cc-pool


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.



ConfiguringPoolsApoolcanbeconfiguredaslocatorsorasalistofservers.

Youconfigurelocator,server,andpoolsettingsdeclarativelyintheclient’s cache.xml fileorprogrammaticallythroughthe PoolFactory method.Youcreateaninstanceofthrough PoolManager .

NativeClientPoolAPIThenativeclientAPIallowsyourclientstocreateandmanageconnectionpools.TheserversidedoesnothaveanAPI.

PoolConfigurationExampleandSettingsConnectionpoolsrequirestandardclient/serverdistributedsystemandcacheconfigurationsettings.Youmustalsoconfiguresettingsforthelocator,server,andpoolelements.

SubscriptionPropertiesEachconnectionpoolhasasinglesubscriptionconnectionthatcanbetoanyserverthatmatchestherequirementsoftheconnectionpool.

RunningtheConnectionPoolCodeExamplesdemonstrateasimpleproceduretocreateapoolfactoryandthencreateapoolinstanceinC++andC#.Theyalsohelpyoutoexecuteaquery.



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.



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.


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 …



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.



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);



TransactionsThissectiondescribeshowtransactionsworkontheclientside.Itprovidesexamplesforrunning,suspending,andresumingtransactions.

Clienttransactionsrunontheservertier.Theclientusesaserverdelegatethatrunsthetransactionasitwouldalocaltransaction.Thus,thekeytorunningclienttransactionsliesinmakingsuretheserverisproperlyconfiguredandprogrammed.ForcompleteinformationabouttransactionsintheJavaserver,seetheserverdocumentationatTransactionsprovidesdetailedinformationincludingserverdatarequirements,interactionsoftransactionswithotheroperationsrunningontheservertier,server-sideapplicationplug-inswithtransactions,andqueryingwithtransactions.

HowClientTransactionsWorkThesyntaxforwritingclienttransactionsisthesameaswithserverorpeertransactions,butwhenaclientperformsatransaction,thetransactionisdelegatedtoaserverthatbrokersthetransaction.

RunningaClientTransactionBeforeyoucanrunaclienttransaction,youmustconfigureyourclientsandservers;defineyourserverregionsforyourtransactions;anddefineyourclientregions.

SuspendingandResumingTransactionsTheabilitytosuspendandresumetransactionsisusefulwhenathreadmustperformoperationsthatshouldnotbepartofthetransactionbeforethetransactioncancomplete.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/transactions/geodeman/developing/transactions/chapter_overview.html


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


https://gemfire-native.docs.pivotal.io/91/geode-native-client/transactions/geodeman/developing/transactions/chapter_overview.html


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.



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.



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.



UnderstandingData-AwareFunctionRoutingAchievinglinearscalabilityispredicateduponbeingabletohorizontallypartitiontheapplicationdatasuchthatconcurrentoperationsbydistributedapplicationscanbedoneindependentlyacrosspartitions.

Inotherwords,iftheapplicationrequirementsfortransactionscanberestrictedtoasinglepartition,andalldatarequiredforthetransactioncanbecolocatedtoasingleservermemberorasmallsubsetofservermembers,thentrueparallelismcanbeachievedbyvectoringtheconcurrentaccessorstotheever-growingnumberofpartitions.

Mostscalableenterpriseapplicationsgrowindatavolume,wherethenumberofdataitemsmanagedratherthanthesizeofindividualitemsgrowsovertime.Iftheabovelogicholds(especiallytrueforOLTPclassapplications),thenwecanderivesizablebenefitsbyroutingthedata-dependentapplicationcodetothefabricmemberhostingthedata.Thisroutingofapplicationcodetothedataofinterestiscalleddata-awarefunctionrouting,orbehaviorrouting.



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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/function-execution/geodeman/developing/function_exec/function_execution.html

Figure:Data-DependentFunctionInvokedFromaClient

Thisshowsthesamedata-dependentfunctionwiththeaddedspecificationofasetofkeysonwhichtorun.Serversthatdon’tholdanyofthekeysareleftoutofthefunctionexecution.

Figure:Data-DependentFunctionwithFilterInvokedfromaClient

Thisscenariodemonstratesthestepsinacalltoahighlyavailablefunction.Thecallfailsthefirsttimeononeoftheparticipatingserversandissuccessfullyrunasecondtimeonallservers.

Figure:HighlyAvailableData-DependentFunctionwithFailureonFirstExecutions




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.


https://gemfire-native.docs.pivotal.io/91/geode-native-client/function-execution/geodeman/developing/function_exec/chapter_overview.html


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++)


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);



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.



SolutionsandUseCasesThefunctionexecutionserviceprovidessolutionsfortheseapplicationusecases:

Anapplicationthatexecutesaserver-sidetransactionormakesdataupdatesusingtheGemFiredistributedlockingservice.

Anapplicationthatinitializessomeofitscomponentsonceoneachserver,whichmightbeusedlaterbyexecutedfunctions.

Initializationandstartupofathird-partyservice,suchasamessagingservice.

Anyarbitraryaggregationoperationthatrequiresiterationoverlocaldatasetsthatcanbedonemoreefficientlythroughasinglecalltothecacheserver.

Anykindofexternalresourceprovisioningthatcanbedonebyexecutingafunctiononaserver.



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


https://gemfire-native.docs.pivotal.io/91/geode/delta-propagation/how-delta-propagation-works.html

https://gemfire-native.docs.pivotal.io/91/geode/delta-propagation/delta-propagation-api.html

https://gemfire-native.docs.pivotal.io/91/geode/delta-propagation/delta-propagation-properties.html

https://gemfire-native.docs.pivotal.io/91/geode/delta-propagation/performance.html


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.



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.



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");


https://gemfire-native.docs.pivotal.io/91/geode-native-client/delta-propagation/geodeman/developing/delta_propagation/chapter_overview.html


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.


https://gemfire-native.docs.pivotal.io/91/gemfire-native-client/delta-propagation/performance.html#performance

https://gemfire-native.docs.pivotal.io/91/gemfire-native-client/delta-propagation/delta-propagation-properties.html#delta-propagation-properties


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


nolocaldatastorage,aswhenyouareusingthemtoprovidedataupdateinformationtolisteners.

Inlessobviouscases,aswhenanentryhasbeenlocallydeleted,firstthedeltaissent,thenthereceiverrequestsafullvalueandthatissent.Wheneverthefullvalueisreceived,anyfurtherdistributionstothereceiver’speersorclientsusesthefullvalue.

Nodeltasarepropagatedfor:

Transactionalcommitontheserver

The putAll operation



ProgrammingExamplesThischapterprovidesasetofprogrammingexamplestohelpyouunderstandtheclientAPI.

DeclaringaClientRegion

Thefollowingexampleshowshowtodeclareaclientregionina cache.xml file.

APIProgrammingExample–C#ThisC#programmingcodeinthenextexampledemonstrateshowtousetwoormoreclientssharingadistributedregioninaGeodecache.

APIProgrammingExample–C++

DataSerializationExamples


https://gemfire-native.docs.pivotal.io/91/geode/programming-examples/client-region.html

https://gemfire-native.docs.pivotal.io/91/geode/programming-examples/serialization-overview.html


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.



APIProgrammingExample–C#SeeQuickStartExamplesforC#programmingexamples.



APIProgrammingExample–C++SeeQuickStartExamplesforC++programmingexamples.



DataSerializationExamplesThissectioncontainsdataserializationexamplesforC++,C#,andJava.

C++SerializationExample

C#SerializationExample

JavaSerializationExample



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);


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);}}


}

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);


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;



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;


returnthis;}

publicvoidToData(DataOutputoutput){output.writeUTF(m_name);output.writeInt32(m_userId);eo.ToData(output);}

#endregion}



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)


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(){


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;}}



InteroperabilityofLanguageClassesandTypesThissectionprovidesatablethatmapsC++classmethodstocorresponding.NETclassmethodsandatablethatmapsJavatypesto.NETtypes.

C++Classto.NETClassMappings

Javato.NETTypeMappingTable



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



SystemStatisticsThissectiondiscussesstatisticsforcachinganddistributionactivities.Statisticsthatendwith“time”aretime-basedstatistics.Forperformancereasons,thesystemdoesnotcollectthesebydefault.Toenabletime-basedstatisticsgathering,setthesystemproperty enable-time-statistics asdescribedinAttributesingeode.properties—StatisticsArchivingProperties

SamplingStatisticsWhenapplicationsandcacheserversjoinadistributedsystem,theyindicatewhethertoenablestatisticssamplingandwhethertoarchivethestatisticsthataregathered.

SystemPerformanceStatisticsPerformancestatisticsarecollectedforeachapplicationorcacheserverthatconnectstoadistributedsystem.

OperatingSystemStatisticsUseoperatingsystemstatisticstodetermineamember’sCPU,memory,anddiskusage.



SamplingStatisticsWhenapplicationsandcacheserversjoinadistributedsystem,theyindicatewhethertoenablestatisticssamplingandwhethertoarchivethestatisticsthataregathered.

Thefollowingstatisticsarerelatedtothestatisticsampler.

sampleCount Totalnumberofsamplestakenbythissampler.

sampleTime Totalamountoftimespenttakingsamples.

StatSampler Statisticsonthestatisticsampler.

Formoreinformationaboutconfiguringstatistics,seeAttributesingeode.properties.



SystemPerformanceStatisticsPerformancestatisticsarecollectedforeachapplicationorcacheserverthatconnectstoadistributedsystem.

RegionStatisticsThesemethodshelptogetthestatisticsofaregion.

CachePerformanceStatisticsUsecacheperformancestatisticstodeterminethetypeandnumberofcacheoperationsbeingperformedandhowmuchtimetheyconsume.

ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.

CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.

PoolStatisticsUsethepoolobjecttogetstatisticsonconnectionpools.

DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.



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.



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.



ContinuousQueryStatisticsContinuousquerystatisticsgiveinformationaboutaregisteredContinuousQuery(CQ)representedbytheCqQueryobject.

inserts TotalnumberofinsertsforthisCQquery.

updates TotalnumberofupdatesforthisCQquery.

deletes TotalnumberofdeletesforthisCQquery.

events TotalnumberofeventsforthisCQquery.



CQServiceStatisticsUseCQservicemethodstogetaggregatestatisticalinformationaboutthecontinuousqueriesofaclient.

CqsActive TotalnumberofCQsactiveforthisCQservice.

CqsCreated TotalnumberofCQscreatedforthisCQservice.

CqsClosed TotalnumberofCQsclosedforthisCQservice.

CqsStopped TotalnumberofCQsstoppedforthisCQservice.

CqsOnClient TotalnumberofCQsontheclientforthisCQservice.



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.



DeltaStatisticsDeltastatisticsprovideinformationaboutupdatestodata.

deltaMessageFailures Totalnumberofmessagescontainingdelta(receivedfromserver)butcouldnotbeprocessedafterreception.

deltaPuts Totalnumberofputscontainingdeltathathavebeensentfromclienttoserver.

processedDeltaMessages Totalnumberofmessagescontainingdeltareceivedfromserverandprocessedafterreception.

processedDeltaMessagesTime Totaltimespentapplyingdelta(receivedfromserver)onexistingvaluesatclient.



OperatingSystemStatisticsUseoperatingsystemstatisticstodetermineamember’sCPU,memory,anddiskusage.

LinuxProcessStatisticsUsethesemethodstogetinformationaboutaLinuxoperatingsystemprocess.

SolarisProcessStatisticsUsethesemethodstogetinformationaboutaSolarisoperatingsystemprocess.

WindowsProcessStatisticsUsethesemethodstogetinformationaboutaWindowsoperatingsystemprocess.



LinuxProcessStatisticsUsethesemethodstogetinformationaboutaLinuxoperatingsystemprocess.

imageSize Thesizeoftheprocess’simageinmegabytes.

rssSize Thesizeoftheprocess’sresidentsetsizeinmegabytes.

userTime TheoperatingsystemstatisticfortheprocessCPUusageinusertime

systemTime TheoperatingsystemstatisticfortheprocessCPUusageinsystemtime.

hostCpuUsage TheoperatingsystemstatisticforthehostCPUusage.

threads Numberofthreadscurrentlyactiveinthisprocess.

LinuxProcessStats StatisticsforaLinuxprocess.



SolarisProcessStatisticsUsethesemethodstogetinformationaboutaSolarisoperatingsystemprocess.

imageSize Sizeoftheprocessimageinmegabytes.

rssSize Sizeoftheprocessresidentsetinmegabytes.

userTime OperatingsystemstatisticfortheprocessCPUusageinusertime.

systemTime OperatingsystemstatisticfortheprocessCPUusageinsystemtime.

processCpuUsage OperatingsystemstatisticfortheCPUusageofthisprocess.

hostCpuUsage OperatingsystemstatisticforthehostCPUusage.

threads Numberofthreadscurrentlyactiveinthisprocess.



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.


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


Size

CurrentnumberofbytesintheWorkingSetofthisprocess.TheWorkingSetisthesetofmemorypagestouchedrecentlybythethreadsintheprocess.Iffreememoryinthecomputerisaboveathreshold,pagesareleftintheWorkingSetofaprocesseveniftheyarenotinuse.Whenfreememoryfallsbelowathreshold,pagesaretrimmedfromWorkingSets.Ifpagesareneeded,theyarethensoft-faultedbackintotheWorkingSetbeforetheyarepagedouttodisk.

workingSetSizePeak

MaximumnumberofbytesintheWorkingSetofthisprocessatanypointintime.TheWorkingSetisthesetofmemorypagestouchedrecentlybythethreadsintheprocess.Iffreememoryinthecomputerisaboveathreshold,pagesareleftintheWorkingSetofaprocesseveniftheyarenotinuse.Whenfreememoryfallsbelowathreshold,pagesaretrimmedfromWorkingSets.IftheyareneededtheywillthenbesoftfaultedbackintotheWorkingSetbeforetheyleavemainmemory.

cpuUsage

PercentageCPUusedbythisprocess.

WindowsProcessStats

StatisticsforaMicrosoftWindowsprocess.



InstallingtheSQLitePersistenceManagerThissectiondescribeshowtodownload,buildandinstalltheSQLitedatabaselibrariesforusewithdiskoverflow.

SeePersistenceManagerforadditionalinformationabouttheSQLitedatabaselibraries.

LinuxInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronLinux.

SolarisInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronSolaris.

WindowsInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronWindows.



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 .


http://www.sqlite.org/download.html


SolarisInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronSolaris.


Thefollowinglibrariesmustbepresentintheruntimelinkingpath:

libSqLiteImpl.so isprovidedin product-dir/lib ,soitisalreadypresentintheruntimelinkingpath.

libsqlite3.so istheSQLiteLibrary.Youneedtocreatethislibraryandmakeavailableintheruntimelinkingpath,orcopiedto product-dir/lib ,asdescribedbelow.


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 .




WindowsInstallationThistopicdescribeshowtoinstalltheSQLitePersistenceManageronWindows.



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 .


http://system.data.sqlite.org/index.html/doc/trunk/www/downloads.wiki



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.


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.


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.


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.


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.

Documents

Pivotal GemFire® Native Client 9 · 2019-11-05 · Using Apache.Geode.dll As a Private Assembly Implementing the Shared Assembly Preserving Data High Availability for Client-Server