http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/persistence-manager.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/persistence-manager.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/persistence-manager.html.md.erb new file mode 100644 index 0000000..6d863b1 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/persistence-manager.html.md.erb @@ -0,0 +1,224 @@ +--- +title: PersistenceManager +--- + +For each region, if the disk-policy attribute is set to overflows, a persistence-manager plug-in must perform cache-to-disk and disk-to-cache operations. See the [Overview of Application Plug-Ins](application-plugins.html#application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597). + +Persistence manager declaration: + +``` pre +<region-attributes lru-entries-limit="nnnnn" + disk-policy="overflows"> + <persistence-manager library-name="libraryName" + library-function-name="functionName"> + <properties> + <property name="propertyName" value="propertyValue" /> + </properties> + </persistence-manager> +</region-attributes> +``` + +The optional properties set parameters for the plug-in. + + +## <a id="persistence-manager__section_9FC7089FDF8044868F17A2659397402A" class="no-quick-link"></a>Using SQLite as a Persistence Manager + +The Geode native client distribution includes a persistence manager that uses the open-source SQLite library. + +SQLite is a software library that implements a self-contained transactional SQL database. SQLite does not require its own server or separate configuration, and the source code for SQLite is in the public domain. For more information on SQLite, see [http://www.sqlite.org](http://www.sqlite.org). + +Each SQLite persistence manager persists its region data in a SQLite database that is stored in disk files. In a given native client application process, each region must have a unique persistence (overflow) directory. + +<a id="persistence-manager__fig_6A0C9F1A29134ACBA0FDD8236CD836B6"></a> +<span class="figtitleprefix">Figure: </span>SQLite Database Persistence Manager Directory Structure + +<img src="../images/SQLite_Persistence_Mgr.png" id="persistence-manager__image_BD1AF915E09548D68D9307E2F52737F9" class="image" /> + +## <a id="persistence-manager__section_3C6991A39C5F4FB8A945EF15FB089287" class="no-quick-link"></a>SQLite Persistence Manager Region Attributes + +The following table describes the region attributes that can be configured for the SQLite persistence manager. + +| Property | Description | Default Setting | +|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PersistenceDirectory | Directory where each region's database files are stored. This setting must be different for each region including regions in different processes. This directory is created by the persistence manager. The persistence manager fails to initialize if this directory already exists or cannot be created. | Default is to create a subdirectory named GemFireRegionData in the directory where the process using the region was started. | +| PageSize | Maximum page size of the SQLite database. SQLite can limit the size of a database file to prevent the database file from growing too large and consuming too much disk space. | Ordinarily, if no value is explicitly provided, SQLite creates a database with the page size set to SQLITE\_DEFAULT\_PAGE\_SIZE (default is 1024). However, based on certain device characteristics (for example, sector-size and atomic write() support) SQLite may choose a larger value. PageSize specifies the maximum value that SQLite will be able to choose on its own. See <a href="http://www.sqlite.org/compile.html#default_page_size";>http://www.sqlite.org/compile.html#default_page_size</a>. for more details on SQLITE\_DEFAULT\_PAGE\_SIZE. | +| MaxPageCount | Maximum number of pages in one database file. | SQLite default, which is 1073741823. | + +## <a id="persistence-manager__section_A9583FBEB5D74B92AD61CB6158AE2B4C" class="no-quick-link"></a>Configuring the SQLite Persistence Manager Plug-In for C++ Applications + +To load the SQLite persistence manager plug-in for C++ applications, you can configure it either in your client's `cache.xml` or programmatically using the native client C++ API. + +The following is an example of how to specify the following region attributes in your client's cache.xml: + +``` pre +<region-attributes> + <persistence-manager library-name="libSqLiteImpl.so" library-function-name="createSqLiteInstance"> + <properties> + <property name="PersistenceDirectory" value="/xyz"/> + <property name="PageSize" value="65536"/> + <property name="MaxPageCount" value="1073741823"/> + </properties> + </persistence-manager> +</region-attributes> +``` + +## C++ API Example + +To use the native client C++ API, set SQLite persistence manager attributes programmatically as follows: + +``` pre +PropertiesPtr sqliteProperties = Properties::create(); +sqliteProperties->insert("MaxPagecount", "5"); +sqliteProperties->insert("PageSize", "1024"); +sqliteProperties->insert("PersistenceDirectory", "SqLite-Test779"); +regionFactory->setPersistenceManager("SqLiteImpl","createSqLiteInstance", + sqliteProperties); +``` + +## <a id="persistence-manager__section_7410F68E0BB144A584A9AFE7E8CDBE22" class="no-quick-link"></a>Configuring the SQLite Persistence Manager Plug-In for .NET Applications + +To load the SQLite persistence manager plug-in for .NET applications, you can configure it either in your client's cache.xml or programmatically using the .NET API: + +``` pre +<persistence-manager library-name="Gemstone.Gemfire.Plugins.SqLite" + library-function-name="GemStone.GemFire.Plugins.SqLite.SqLiteImpl<System.Object, System.Object>.Create"> + <properties> + <property name="PersistenceDirectory" value="SqLite"/> + <property name="MaxPageCount" value="1073741823"/> + <property name="PageSize" value="65536"/> + </properties> +</persistence-manager> +``` + +## .NET API Example + +To use the native client .NET API, set the SQLite persistence manager attributes programmatically as follows: + +``` pre +Properties<string, string> sqliteProperties = new Properties<string, string>(); +sqliteProperties.Insert("PageSize", "65536"); +sqliteProperties.Insert("MaxFileSize", "51200000"); +sqliteProperties.Insert("PersistenceDirectory", SqLiteDir); +rf.SetPersistenceManager("Gemstone.Gemfire.Plugins.SqLite", +"Gemstone.Gemfire.Plugins.SqLiteSqLiteImpl<System.Object,System.Object>.Create", +sqliteProperties); +``` + +You can also use and configure the C++ SQLite persistence manager library from your .NET application as follows: + +``` pre +rf.SetPersistenceManager("SqliteImpl", "createSqLiteInstance", sqliteProperties); +``` + +## <a id="persistence-manager__section_9D038C438E01415EA4D32000D5CB5596" class="no-quick-link"></a>Implementing a PersistenceManager with the IPersistenceManager Interface + +When developing .NET managed applications, you can use the IPersistenceManager managed interface to implement your own persistence manager. The following code sample provides the IPersistenceManager interface: + +``` pre +/// <summary> +/// IPersistenceManager interface for persistence and overflow. +/// This class abstracts the disk-related operations in case of persistence or overflow to disk. +/// A specific disk storage implementation will implement all the methods described here. +/// </summary> +generic<class TKey, class TValue> +public interface class IPersistenceManager + { + public: + /// <summary> + /// Called after an implementation object is created. Initializes all the implementation specific environments needed. + /// </summary> + /// <param name="region"> + /// Region for which this PersistenceManager is initialized. + /// </param> + /// <param name="diskProperties"> + /// Configuration Properties used by PersistenceManager implementation. + /// </param> + void Init(IRegion<TKey, TValue>^ region, Properties<String^, String^>^ diskProperties); + + /// <summary> + /// Writes a key, value pair of region to the disk. The actual file or database related write operations should be implemented in this method. + /// </summary> + /// <param name="key"> + /// the key to write. + /// </param> + /// <param name="value"> + /// the value to write. + /// </param> + void Write(TKey key, TValue value); + + /// <summary> + /// This method is not used. + /// </summary> + bool WriteAll(); + + /// <summary> + /// Reads the value for the key from the disk. + /// </summary> + /// <param name="key"> + /// key for which the value has to be read. + /// </param> + TValue Read(TKey key); + + /// <summary> + /// This method is not used. + /// </summary> + bool ReadAll(); + + /// <summary> + /// Destroys the entry specified by the key in the argument. + /// </summary> + /// <param name="key"> + /// key of the entry which is being destroyed. + /// </param> + void Destroy(TKey key); + + /// <summary> + /// Closes the persistence manager instance. + /// </summary> + void Close(); +} +``` + +The following is a sample interface implementation: + +``` pre +class MyPersistenceManager<TKey, TValue> : IPersistenceManager<TKey, TValue> + { + #region IPersistenceManager<TKey,TValue> Members + public void Close() + { + throw new NotImplementedException(); + } + + public void Destroy(TKey key) + { + throw new NotImplementedException(); + } + + public void Init(IRegion<TKey, TValue> region, Properties<string, string> disk Properties) + { + throw new NotImplementedException(); + } + + public TValue Read(TKey key) + { + throw new NotImplementedException(); + } + + public void Write(TKey key, TValue value) + { + throw new NotImplementedException(); + } + + public bool ReadAll() + { + throw new NotImplementedException(); + } + + public bool WriteAll() + { + throw new NotImplementedException(); + } + #endregion + } +```
http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/programmatic-region-creation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/programmatic-region-creation.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/programmatic-region-creation.html.md.erb new file mode 100644 index 0000000..6027ff5 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/programmatic-region-creation.html.md.erb @@ -0,0 +1,20 @@ +--- +title: Programmatic Region Creation +--- + +You create regions programmatically with the `regionFactory` class. + +**Note:** +Before creating a region, specify region attributes. See [Region Attributes](region-attributes.html). + +Create your regions using the `regionFactory` class. + +**C++ RegionFactory Example** + +``` pre +RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(CACHING_PROXY); +RegionPtr regPtr0 = regionFactory->setLruEntriesLimit(20000) + ->create("exampleRegion0"); + +``` http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/region-access.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/region-access.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/region-access.html.md.erb new file mode 100644 index 0000000..efb6fee --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/region-access.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Region Access +--- + +You can use `Cache::getRegion` to retrieve a reference to a specified region. + +`RegionPtr` returns `NULL` if the region is not already present in the application's cache. A server region must already exist. + +A region name *cannot* contain these characters: + +- < +- > +- : +- " +- / +- \\ +- | +- ? +- \* + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/region-attributes-desc.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/region-attributes-desc.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/region-attributes-desc.html.md.erb new file mode 100644 index 0000000..456ad95 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/region-attributes-desc.html.md.erb @@ -0,0 +1,39 @@ +--- +title: Mutable and Immutable Region Attributes +--- + +Attributes that are immutable (fixed) after region creation govern storage location, data distribution, statistics, application plug-ins, and the configuration and management of the region's data hashmap. + +This table lists the immutable attributes and their default settings. + +<a id="region-attributes-desc__table_B1CC036A7929449A8CD06E56678A6CB2"></a> + +| Immutable Region Attribute | Default Setting | +|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| See [CachingEnabled](caching-enabled.html#caching-enabled) | true | +| See [InitialCapacity](initial-capacity.html#initial-capacity) | 16 (entries) | +| See [LoadFactor](load-factor.html#load-factor) | 0.75 | +| See [ConcurrencyLevel](concurrency-level.html#concurrency-level) | 16 | +| See [DiskPolicy](disk-policy.html#disk-policy) | | +| See [PersistenceManager](persistence-manager.html#persistence-manager) | NULL | +| PartitionResolver. See [Overview of Application Plug-Ins](application-plugins.html#application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597). | | + + +Mutable region attributes identify expiration and cache listener, cache writer and cache loader actions that are run from the defining client. The next table lists the mutable attributes that generally can be modified after region creation by using the `AttributesMutator` for the region. + +<a id="region-attributes-desc__table_98120276A645432A840F991C18039621"></a> + +| Mutable Region Attribute | Default Setting | +|------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +| Expiration attributes. See [Specifying Expiration Attributes](expiration-attributes.html#expiration-attributes). | no expiration | +| See [LruEntriesLimit](lru-entries-limit.html#concept_75D723D60E044FF9AE97C939699AB10A). | 0 (no limit) | +| CacheLoader. See [Overview of Application Plug-Ins](application-plugins.html#application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597). | | +| CacheWriter. See [Overview of Application Plug-Ins](application-plugins.html#application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597). | | +| CacheListener. See [Overview of Application Plug-Ins](application-plugins.html#application-plugins__section_8FEB62EEC7A042E0A85E0FEDC9F71597). | | + + +See [Specifying Application Plug-In Attributes](application-plugins.html#application-plugins) for information about using `AttributesMutator` with cache listeners, cache loaders, and cache writers. + +The remainder of this section examines these attributes in detail. Throughout the descriptions, `cache.xml` file snippets show how each attribute can be set declaratively. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/region-attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/region-attributes.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/region-attributes.html.md.erb new file mode 100644 index 0000000..8bfa7f3 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/region-attributes.html.md.erb @@ -0,0 +1,35 @@ +--- +title: Region Attributes +--- + +Region attributes govern the automated management of a region and its entries. + +Region attribute settings determine where the data resides, how the region is managed in memory, and the automatic loading, distribution, and expiration of region entries. + +- **[Specifying Region Attributes](specify-region-attributes.html)** + +- **[Region Shortcuts](region-shortcuts.html)** + +- **[Mutable and Immutable Region Attributes](region-attributes-desc.html)** + +- **[CachingEnabled](caching-enabled.html)** + +- **[InitialCapacity](initial-capacity.html)** + +- **[LoadFactor](load-factor.html)** + +- **[ConcurrencyLevel](concurrency-level.html)** + +- **[ConcurrencyChecksEnabled](concurrency-checks-enabled.html)** + +- **[LruEntriesLimit](lru-entries-limit.html)** + +- **[DiskPolicy](disk-policy.html)** + +- **[PersistenceManager](persistence-manager.html)** + +- **[Specifying Application Plug-In Attributes](application-plugins.html)** + +- **[Specifying Expiration Attributes](expiration-attributes.html)** + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/region-shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/region-shortcuts.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/region-shortcuts.html.md.erb new file mode 100644 index 0000000..bd4a75f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/region-shortcuts.html.md.erb @@ -0,0 +1,58 @@ +--- +title: Region Shortcuts +--- + +<a id="region-shortcuts__section_62D2AB580EDB4165970E4FC42A35C80B"></a> +Geode provides a number of predefined, shortcut region attributes settings for your use, in `RegionShortcut`. + +Shortcut attributes are a convenience only. They are named attributes that Geode has already stored for you. You can override their settings by storing new attributes with the same `id` as the predefined attributes. + +You can also create custom region attributes and store them with an identifier for later retrieval. Both types of stored attributes are referred to as named region attributes. You can create and store your attribute settings in the `cache.xml` file and through the API. + +Retrieve named attributes by providing the ID to the region creation. This example uses the shortcut `CACHING_PROXY` attributes to create a region: + +``` pre +<region name="testRegion" refid="CACHING_PROXY"/> +``` + +You can modify named attributes as needed. For example, this adds a cache listener to the region: + +``` pre +<region name="testRegion" refid="CACHING_PROXY"> + <region-attributes> + <cache-listener library-name="myAppLib" + library-function-name ="myCacheListener" /> + </region-attributes> +</region> +``` + +In this example, the modified region shortcut is saved to the cache using the region attribute id, for retrieval and use by a second region: + +``` pre +<region name="testRegion" refid="CACHING_PROXY"> + <region-attributes id="Caching_Proxy_With_Listener"> + <cache-listener library-name="myAppLib" + library-function-name ="myCacheListener" /> + </region-attributes> +</region> +<region name="newTestRegion" refid="Caching_Proxy_With_Listener"/> +``` + +## <a id="region-shortcuts__section_49150358B8F443E8AF027E4E920E820A" class="no-quick-link"></a>Shortcut Attribute Options + +You can select the most common region attributes settings from `RegionShortcut`, the predefined named region attributes. + +This section provides an overview of the options available in the region shortcut settings. + +**Communication with Servers and Data Storage** + +- `PROXY` does not store data in the client cache, but connects the region to the servers for data requests and updates, interest registrations, and so on. +- `CACHING_PROXY` stores data in the client cache and connects the region to the servers for data requests and updates, interest registrations, and so on. +- `LOCAL` stores data in the client cache and does not connect the region to the servers. This is a client-side-only region. + +**Data Eviction** + +For the non-`PROXY` regions--the regions that store data in the client cache--you can add data eviction: + +- `ENTRY_LRU` causes least recently used data to be evicted from memory when the region reaches the entry count limit. + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/regions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/regions.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/regions.html.md.erb new file mode 100644 index 0000000..5510fb4 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/regions.html.md.erb @@ -0,0 +1,30 @@ +--- +title: Regions +--- + +You create cache regions either programmatically or through declarative statements in the `cache.xml` file. Generally, a cache is organized and populated through a combination of the two approaches. + +<a id="regions__section_1BE4ABB76537488C966E452C2D89478F"></a> +The region is the core building block of the Geode distributed system. All cached data is organized into data regions and you do all of your data puts, gets, and querying activities against them. + +A distributed region can be either non-partitioned or a partitioned region. See [Data Regions](geodeman/basic_config/data_regions/chapter_overview.html) for detailed descriptions of both non-partitioned and partitioned regions. Region creation is subject to attribute consistency checks. The requirements for consistency between attributes are detailed both in the API documentation and throughout the discussion of [Region Attributes](region-attributes.html#region-attributes). + +- **[Declarative Region Creation](declarative-region-creation.html)** + + Declarative region creation involves placing the region's XML declaration, with the appropriate attribute settings, in the `cache.xml` file that is loaded at cache creation. + +- **[Programmatic Region Creation](programmatic-region-creation.html)** + + You create regions programmatically with the `regionFactory` class. + +- **[Invalidating and Destroying Regions](invalidating-region.html)** + + Invalidation marks all entries contained in the region as invalid (with null values). Destruction removes the region and all of its contents from the cache. + +- **[Region Access](region-access.html)** + + You can use `Cache::getRegion` to retrieve a reference to a specified region. + +- **[Getting the Region Size](getting-the-region-size.html)** + + The `Region` API provides a `size` method (`Size` property for .NET) that gets the size of a region. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb new file mode 100644 index 0000000..aac6fae --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb @@ -0,0 +1,93 @@ +--- +title: Registering Interest for Entries +--- + +For native client regions, you can programmatically register interest in entry keys stored on a cache server region. A client region receives update notifications from the cache server for the keys of interest. + +You can register interest for specific entry keys or for all keys. Regular expressions can be used to register interest for keys whose strings match the expression. You can also unregister interest for specific keys, groups of keys based on regular expressions, or for all keys. + +**Note:** Interest registration and unregistration are symmetrical operations. Consequently, you cannot register interest in all keys and then unregister interest in a specific set of keys. Also, if you first register interest in specific keys with `registerKeys`, then call `registerAllKeys`, you must call `unregisterAllKeys` before specifying interest in specific keys again. + + +## <a id="registering-interest-for-entries__section_C9A3D7F193B24ACD83B2D67813E596A0" class="no-quick-link"></a>Client API for Registering Interest + +You register client interest through the C++ or NET API. The C++ API provides the `registerKeys`, `registerAllKeys`, and `registerRegex` methods, with corresponding unregistration accomplished using the `unregisterKeys`, `unregisterAllKeys`, and `unregisterRegex` methods. The .NET API provides the `RegisterKeys`, `RegisterAllKeys`, and `RegisterRegex` methods, with corresponding unregistration accomplished using the `UnregisterKeys`, `UnregisterAllKeys`, and `UnregisterRegex` methods. + +The `registerKeys`, `registerRegex` and `registerAllKeys` methods have the option to populate the cache with the registration results from the server. The `registerRegex` and `registerAllKeys` methods can also optionally return the current list of keys registered on the server. + +## <a id="registering-interest-for-entries__section_C1A3F89EE73448D7AFF2076F41848F55" class="no-quick-link"></a>Setting Up Client Notification + +In addition to the programmatic function calls, to register interest for a server region and receive updated entries you need to configure the region with the `PROXY` or `CACHING_PROXY RegionShortcut` setting. The region's pool should have `subscription-enabled=true` set either in the client XML or programmatically via a `CacheFactory::setSubscriptionEnabled(true)` API call. Otherwise, when you register interest, you will get an `UnsupportedOperationException`. + +``` pre +<region name = "listenerWriterLoader" refid="CACHING_PROXY"> + ... +``` + +Both native clients and Java clients that have subscriptions enabled track and drop (ignore) any duplicate notifications received. To reduce resource usage, a client expires tracked sources for which new notifications have not been received for a configurable amount of time. + +**Notification Sequence** + +Notifications invoke `CacheListeners` of cacheless clients in all cases for keys that have been registered on the server. Similarly, invalidates received from the server invoke `CacheListeners` of cacheless clients. + +If you register to receive notifications, listener callbacks are invoked irrespective of whether the key is in the client cache when a `destroy` or `invalidate` event is received. + +## <a id="registering-interest-for-entries__section_8772147940754C2D9688C789EB2F2AA6" class="no-quick-link"></a>Registering Interest for Specific Keys + +You register and unregister interest for specific keys through the `registerKeys` and `unregisterKeys` functions. You register interest in a key or set of keys by specifying the key name using the programmatic syntax shown in the following example: + +``` pre +keys0.push_back(keyPtr1); +keys1.push_back(keyPtr3); +regPtr0->registerKeys(keys0); +regPtr1->registerKeys(keys1); +``` + +The programmatic code snippet in the next example shows how to unregister interest in specific keys: + +``` pre +regPtr0->unregisterKeys(keys0); +regPtr1->unregisterKeys(keys1); +``` + +## <a id="registering-interest-for-entries__section_EA4525CCDC474DD495410E948EAF566C" class="no-quick-link"></a>Registering Interest for All Keys + +If the client registers interest in all keys, the server provides notifications for all updates to all keys in the region. The next example shows how to register interest in all keys: + +``` pre +regPtr0->registerAllKeys(); +regPtr1->registerAllKeys(); +``` + +The following example shows a code sample for unregistering interest in all keys. + +``` pre +regPtr0->unregisterAllKeys(); +regPtr1->unregisterAllKeys(); +``` + +## <a id="registering-interest-for-entries__section_BD50B80FCE9F429C8F6A9FEA818D5A91" class="no-quick-link"></a>Registering Interest Using Regular Expressions + +The `registerRegex` function registers interest in a regular expression pattern. The server automatically sends the client changes for entries whose keys match the specified pattern. + +*Keys must be strings in order to register interest using regular expressions.* + +The following example shows interest registration for all keys whose first four characters are `Key-`, followed by any string of characters. The characters `.*` represent a wildcard that matches any string. + +``` pre +regPtr1->registerRegex("Key-.*"); +``` + +To unregister interest using regular expressions, you use the `unregisterRegex` function. The next example shows how to unregister interest in all keys whose first four characters are `Key-`, followed by any string (represented by the `.*` wildcard). + +``` pre +regPtr1->unregisterRegex("Key-.*"); +``` + +## <a id="registering-interest-for-entries__section_2D71A423B185493489129AAC30DC6733" class="no-quick-link"></a>Register Interest Scenario + +In this register interest scenario, a cache listener is used with a cacheless region that has `subscription-enabled` set to `true`. The client region is configured with caching disabled; client notification is enabled; and a cache listener is established. The client has not registered interest in any keys. + +When a value changes in another client, it sends the event to the server. The server will not send the event to the cacheless client, even though `client-notification` is set to `true`. + +To activate the cache listener so the cacheless region receives updates, the client should explicitly register interest in some or all keys by using one of the API calls for registering interest. This way, the client receives all events for the keys to which it has registered interest. This applies to Java-based clients as well as native clients. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/requirements-for-distrib.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/requirements-for-distrib.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/requirements-for-distrib.html.md.erb new file mode 100644 index 0000000..a69ab3b --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/requirements-for-distrib.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Entry Distribution Requirements +--- + +Entry data distributed among members of the distributed system must be serializable. Entry keys and values are serialized for distribution. + +If a native client defines a region, it must register any serializable types for all classes of objects stored in the region. This includes entries that the application gets or puts, as well as entries that are pushed to the client's cache automatically through distribution. The types must be registered before the native client connects to the distributed system. + +See [Serializing Data](../cpp-caching-api/serialization_overview.html#concept_2A8DC49D93394392BA34B17AA3452B14) for more information about these requirements. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/specify-region-attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/specify-region-attributes.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/specify-region-attributes.html.md.erb new file mode 100644 index 0000000..5cbc1ad --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/specify-region-attributes.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Specifying Region Attributes +--- + +Region attributes govern the automated management of a region and its entries. + +Specify region attributes before creating the region. You can do this either through the declarative XML file or through the API. The API includes classes for defining a region's attributes before creation and for modifying some of them after creation. For details, see the API for `RegionShortcut`, `RegionAttributes`, `AttributesFactory`, and `AttributesMutator` at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/troubleshooting.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/troubleshooting.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/troubleshooting.html.md.erb new file mode 100644 index 0000000..8d7dacb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/troubleshooting.html.md.erb @@ -0,0 +1,41 @@ +--- +title: Troubleshooting +--- + +This section provides troubleshooting information for the native client. + +## <a id="troubleshooting__section_32E817A073B8408F8FEDB5599C5CCEF6" class="no-quick-link"></a>Cannot Acquire Windows Performance Data + +When you attempt to run performance measurements for the native client on Windows, you may encounter the following error message in the run logs: + +``` pre +Can't get Windows performance data. RegQueryValueEx returned 5 +``` + +This can occur because incorrect information is returned when a Win32 application calls the ANSI version of `RegQueryValueEx` Win32 API with `HKEY_PERFORMANCE_DATA`. This error is described in Microsoft KB article ID 226371 at [http://support.microsoft.com/kb/226371/en-us](http://support.microsoft.com/kb/226371/en-us). +To successfully acquire Windows performance data, you need to verify that you have the proper registry key access permissions in the system registry. In particular, make sure that `Perflib` in the following registry path is readable (`KEY_READ` access) by the Geode process: + +``` pre +HKEY_LOCAL_MACHINE\ + SOFTWARE\ + Microsoft\ + Windows NT\ + CurrentVersion\ + Perflib +``` + +An example of reasonable security on the performance data would be to grant administrators `KEY_ALL_ACCESS` and interactive users `KEY_READ` access. This particular configuration prevents non-administrator remote users from querying performance data. + +See [http://support.microsoft.com/kb/310426](http://support.microsoft.com/kb/310426) and [http://support.microsoft.com/kb/146906](http://support.microsoft.com/kb/146906) for instructions about how to ensure that Geode processes have access to the registry keys associated with performance. + +## <a id="troubleshooting__section_65EC3B1EAC55421BB734E72E7BFEBFFC" class="no-quick-link"></a>Generating a Process Memory Dump Image for Fatal Errors + +You can generate a process memory dump image (core files in Unix systems and minidumps in Windows). The image is produced when a fatal error occurs that normally terminates the program. + +When the system property `crash-dump-enabled` is set to `true`, a dump image is generated (the default is `true`). The dump file is generated in the same location as the `log-file` directory, and has the same prefix as the log file. The name is `<prefix>-<time>.core.<pid>` in Unix, and `<prefix>-<time>-<pid>.dmp` in Windows). + +Unix systems generate core files automatically for such errors, but this option is useful for providing a custom location and name, as well as for systems where core dump generation is disabled. For Unix, when system core dump generation is turned on (`ulimit -c`) this property can be set to `false`. + +For .NET clients, when this property is set then `AccessViolation` exceptions are trapped and a crash dump is created to assist with further analysis. Applications receive a `FatalInternalException` for this case, with the `InnerException` set to the originating `AccessViolationException`. + +This requires the availability of `dbghelp.dll` on Windows, either in the same directory as `gfcppcache.dll` or in the system `PATH`. The file is installed by default, though for Windows 2000 a newer version may be required for minidumps. For Unix systems, the `gcore` command should be available (gdb > 5.2 on Linux; available by default in Solaris). http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/updating-entries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/updating-entries.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/updating-entries.html.md.erb new file mode 100644 index 0000000..1b91550 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/updating-entries.html.md.erb @@ -0,0 +1,16 @@ +--- +title: Updating Entries +--- + +<a id="updating-entries__section_720D480EDB8D4578BCAB5A368D6D5512"></a> +A cached entry can be updated using these methods: + +- Explicitly, when a client invokes a `put` operation on an existing entry. +- Implicitly, when a `get` is performed on an entry that has an invalid value in the cache. An entry can become invalid through an explicit API call, through an automated expiration action, or by being created with a value of null. +- Automatically, when a new entry value is distributed from another cache. + +Similar to entry creation, all of these operations can be aborted by a cache writer. + +The `get` function returns a direct reference to the entry value object. A change made using that reference is called an in-place change because it directly modifies the contents of the value in the local cache. For details on safe cache access, see [Managing the Lifetime of a Cached Object](managing-lifetime-cached-object.html). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/using-serverkeys-to-retrieve.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/using-serverkeys-to-retrieve.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/using-serverkeys-to-retrieve.html.md.erb new file mode 100644 index 0000000..c4c45bf --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/using-serverkeys-to-retrieve.html.md.erb @@ -0,0 +1,32 @@ +--- +title: Using serverKeys to Retrieve a Set of Region Keys +--- + +<a id="using-serverkeys-to-retrieve__section_8D2276A2D70E4F80998D26BB74F9681C"></a> +You can retrieve the set of keys defined in the cache server process that are associated with the client region by using the `Region::serverKeys` API function. If the server region is defined as a replicate, the keys returned consist of the entire set of keys for the region. + +The following example shows how the client can programmatically call `serverKeys`. + +``` pre +VectorOfCacheableKey keysVec; +region->serverKeys( keysVec ); +size_t vlen = keysVec.size(); +bool foundKey1 = false; +bool foundKey2 = false; +for( size_t i = 0; i < vlen; i++ ) { + CacheableStringPtr strPtr = dynCast<CacheableStringPtr> keysVec.at( i ); + std::string veckey = strPtr->asChar(); + if ( veckey == "skey1" ) { + printf( "found skey1" ); + foundKey1 = true; + } + if ( veckey == "skey2" ) { + printf( "found skey2" ); + foundKey2 = true; + } +} +``` + +An `UnsupportedOperationException` occurs if the client region is not a native client region. A `MessageException` occurs if the message received from the server could not be handled, which can occur if an unregistered `typeId` is received in the reply. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/client-cache/using-thread-safety.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/client-cache/using-thread-safety.html.md.erb b/geode-docs/docs/geode-native-docs/client-cache/using-thread-safety.html.md.erb new file mode 100644 index 0000000..0b763f4 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/client-cache/using-thread-safety.html.md.erb @@ -0,0 +1,13 @@ +--- +title: Using Thread Safety in Cache Management +--- + +When you perform structural changes on your cache, such as creating or closing a `Cache`, `Pool`, or `Region`, synchronize your operations or do them in a single thread. + +Other non-structural operations, like region gets, puts, and queries, are thread safe, and you can perform them in a multithreaded way. There are caveats to this, for example, when two threads update the same key simultaneously, there is no way to determine which thread's operation will prevail. + +You may need to protect cached objects from concurrent usage and modification. The native client does not guard cached objects themselves from concurrent access. + +Always catch and handle exceptions that may be thrown, for problems like trying to create a `Pool` with the same name more than once. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-1.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-1.gif b/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-1.gif new file mode 100644 index 0000000..ca78bc9 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-1.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-3.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-3.gif b/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-3.gif new file mode 100644 index 0000000..716aabc Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/10-Continuous_Querying-3.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/6-DotNet_API-1.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/6-DotNet_API-1.gif b/geode-docs/docs/geode-native-docs/common/images/6-DotNet_API-1.gif new file mode 100644 index 0000000..0ac6fa0 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/6-DotNet_API-1.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/7-Preserving_Data-2.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/7-Preserving_Data-2.gif b/geode-docs/docs/geode-native-docs/common/images/7-Preserving_Data-2.gif new file mode 100644 index 0000000..9f4fde9 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/7-Preserving_Data-2.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/client-cache-data-flow.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/client-cache-data-flow.gif b/geode-docs/docs/geode-native-docs/common/images/client-cache-data-flow.gif new file mode 100644 index 0000000..b69ad60 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/client-cache-data-flow.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/client-cache-plugins-run.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/client-cache-plugins-run.gif b/geode-docs/docs/geode-native-docs/common/images/client-cache-plugins-run.gif new file mode 100644 index 0000000..f255b33 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/client-cache-plugins-run.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/client-server-arch.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/client-server-arch.gif b/geode-docs/docs/geode-native-docs/common/images/client-server-arch.gif new file mode 100644 index 0000000..5a1c5c6 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/client-server-arch.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/data-dep-func-from-client.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/data-dep-func-from-client.gif b/geode-docs/docs/geode-native-docs/common/images/data-dep-func-from-client.gif new file mode 100644 index 0000000..a0c4488 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/data-dep-func-from-client.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/data-dep-func-with-filter.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/data-dep-func-with-filter.gif b/geode-docs/docs/geode-native-docs/common/images/data-dep-func-with-filter.gif new file mode 100644 index 0000000..f5bb9d9 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/data-dep-func-with-filter.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/data-indep-func-from-client.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/data-indep-func-from-client.gif b/geode-docs/docs/geode-native-docs/common/images/data-indep-func-from-client.gif new file mode 100644 index 0000000..1ab8a96 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/data-indep-func-from-client.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/delta-propagation-in-client-server.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/delta-propagation-in-client-server.gif b/geode-docs/docs/geode-native-docs/common/images/delta-propagation-in-client-server.gif new file mode 100644 index 0000000..e662062 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/delta-propagation-in-client-server.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/delta-propagation.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/delta-propagation.gif b/geode-docs/docs/geode-native-docs/common/images/delta-propagation.gif new file mode 100644 index 0000000..aa6c27e Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/delta-propagation.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/ha-data-dep-func.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/ha-data-dep-func.gif b/geode-docs/docs/geode-native-docs/common/images/ha-data-dep-func.gif new file mode 100644 index 0000000..519dd6b Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/ha-data-dep-func.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/native-client-overview.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/native-client-overview.gif b/geode-docs/docs/geode-native-docs/common/images/native-client-overview.gif new file mode 100644 index 0000000..a71a23a Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/native-client-overview.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/security-client-connections.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/security-client-connections.gif b/geode-docs/docs/geode-native-docs/common/images/security-client-connections.gif new file mode 100644 index 0000000..af8fd27 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/security-client-connections.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/common/images/xact-run-from-client.gif ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/common/images/xact-run-from-client.gif b/geode-docs/docs/geode-native-docs/common/images/xact-run-from-client.gif new file mode 100644 index 0000000..4fe2d26 Binary files /dev/null and b/geode-docs/docs/geode-native-docs/common/images/xact-run-from-client.gif differ http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/about-connection-pools.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/about-connection-pools.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/about-connection-pools.html.md.erb new file mode 100644 index 0000000..a8e90ac --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/about-connection-pools.html.md.erb @@ -0,0 +1,20 @@ +--- +title: Connection Pools +--- + +Clients contain connection pools. Each region is associated with a connection pool using a region attribute, and operations on the region use connections from the respective pools. + +The server connectivity options are specified in the connection pool configuration. Each pool has a minimum and maximum number of connections. + +Each cache operation that requires server connectivity obtains a connection from the pool for the server group that the operation affects, performs the operation using the connection, and returns the connection to the pool. If the pool size is less than the maximum number of connections and all connections are in use, the connection pool creates a new connection and returns it. If the pool is at the maximum number of connections, that thread blocks until a connection becomes available or a `free-connection-timeout` occurs. If a `free-connection-timeout` occurs, an `AllConnectionsInUse` exception is thrown. + +The connection pool has a configurable timeout period that is used to expire idle connections. The idle connections are expired until the pool has the minimum number of connections. A monitoring thread expires idle connections, adds sufficient connections to bring up the count to minimum, and closes connections whose lifetime has been exceeded. See the `load-conditioning-interval` and `idle-timeout` attributes of the [<pool>](../../reference/topics/client-cache.html#cc-pool) element. A separate thread (ping) tests each connected endpoint for its status and if the endpoint is not reachable, the thread closes all connections that have been made to the endpoint. See the `ping-interval` attribute of the <pool> element>. + +<a id="client-load-balancing__fig_226964BAA1464DBA9F5CEDC2CB7B3585"></a> +<span class="figtitleprefix">Figure: </span>Logical Architecture of Client/Server Connections + +<img src="../common/images/client-server-arch.gif" id="client-load-balancing__image_1E8316666E1B4CC2ADE4D927B629E49F" class="image" /> + +When a connection receives an exception, the operation is failed over to another connection from the pool. The failover mechanism obtains the endpoint to failover to from the locator or from the specified endpoint list in the pool. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/about-server-locators.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/about-server-locators.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/about-server-locators.html.md.erb new file mode 100644 index 0000000..69bc6c5 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/about-server-locators.html.md.erb @@ -0,0 +1,17 @@ +--- +title: Server Locators +--- + +Server locators continuously monitor server availability and server load information. The client is configured with a list of server locators and consults a server locator to request a connection to a server in the distributed system. + +Locators provide clients with dynamic server discovery and server load balancing. They give clients connection information for the server with the least load at any given time. + +Server locators provide these main features: + +- **Automated discovery of servers and locators**. Adding and removing servers or locators is made easy as each client does not require a list of servers to be configured at the time of pool creation. +- **Client load rebalancing**. Server locators give clients dynamic server information and provide server load rebalancing after servers depart or join the system. +- **High availability**. When a client/server connection receives an exception, the connection is automatically failed over to another available connection in the pool. Redundancy is also provided for client subscriptions. + +Alternatively, you can configure a pool statically with a list of endpoints. When the pools are statically configured, a round-robin load balancing policy is used to distribute connections across the servers. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/client-load-balancing.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/client-load-balancing.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/client-load-balancing.html.md.erb new file mode 100644 index 0000000..c8ed29e --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/client-load-balancing.html.md.erb @@ -0,0 +1,21 @@ +--- +title: How Client Load Balancing Works +--- + +In a distributed system, servers can be added or removed and their capacity to service new client connections may vary. The server connectivity options are specified in the connection pool configuration. + +The Geode connection pool API supports connecting to servers through server locators or directly connecting to servers. + +- **[Server Locators](about-server-locators.html)** + + Server locators continuously monitor server availability and server load information. The client is configured with a list of server locators and consults a server locator to request a connection to a server in the distributed system. + +- **[Connection Pools](about-connection-pools.html)** + + Clients contain connection pools. Each region is associated with a connection pool using a region attribute, and operations on the region use connections from the respective pools. + +- **[Discovering Locators Dynamically](discovering-locators-dynamically.html)** + + A background thread periodically queries the locator for any other locators joining the distributed system. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools-attributes-example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools-attributes-example.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools-attributes-example.html.md.erb new file mode 100644 index 0000000..1ceced3 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools-attributes-example.html.md.erb @@ -0,0 +1,156 @@ +--- +title: Pool Configuration Example and Settings +--- + +Connection pools require standard client/server distributed system and cache configuration settings. You must also configure settings for the locator, server, and pool elements. + +- Locator. Host and port where a server locator is listening. +- Server. Host and port where a server is listening. +- Pool. Client/server connection pool. + +The example shows a declarative pool configuration. Following the example is a table that describes the attributes that can be configured. + +## ExampleâDeclarative Pool Configuration + +This example shows a declarative pool configuration. + +**Note:** +You create an instance of `PoolFactory` through `PoolManager`. + +``` pre +<pool free-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"> + <locator host="localhost" port="34756"/> +</pool> +``` + +## <a id="configuring-pools__section_E7AA69F3BB6C4FEA8094E2BC5278A349" class="no-quick-link"></a>Pool Attributes + +<table> +<colgroup> +<col width="25%" /> +<col width="50%" /> +<col width="25%" /> +</colgroup> +<thead> +<tr class="header"> +<th>Attribute Name</th> +<th>Description</th> +<th>Default</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td><code class="ph codeph">free-connection-timeout</code></td> +<td><p>Number of milliseconds (ms) that the client waits for a free connection if <code class="ph codeph"> max-connections</code> limit is configured and all connections are in use.</p></td> +<td><p>10000 ms</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">idle-timeout</code></p></td> +<td><p>Number of milliseconds to wait for a connection to become idle for load balancing</p></td> +<td><p>5000 ms</p></td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">load-conditioning-interval</code></td> +<td><p>Interval in which the pool checks to see if a connection to a specific server should be moved to a different server to improve the load balance.</p></td> +<td><p>300000 ms (5 minutes)</p></td> +</tr> +<tr class="even"> +<td><code class="ph codeph">max-connections</code></td> +<td><p>Maximum number of connections that the pool can create. If all connections are in use, an operation requiring a client-to server-connection is blocked until a connection is available or the <code class="ph codeph"> free-connection-timeout</code> is reached. If set to -1, there is no maximum. The setting must indicate a cap greater than <code class="ph codeph"> min-connections</code>.</p> +<div class="note note"> +<b>Note:</b> +<p>If you use this setting to cap your pool connections, disable the pool attribute <code class="ph codeph"> pr-single-hop-enabled</code>. Leaving single hop enabled can increase thrashing and lower performance.</p> +</div></td> +<td><p>-1</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">min-connections</code></p></td> +<td><p>Number of connections that must be created initially.</p></td> +<td><p>5</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">name</code></p></td> +<td><p>Pool name.</p></td> +<td><p></p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">ping-interval</code></p></td> +<td><p>Interval between pinging the server to show the client is alive, set in milliseconds. Pings are only sent when the <code class="ph codeph">ping-interval</code> elapses between normal client messages. This must be set lower than the serverâs <code class="ph codeph">maximum-time-between-pings</code>.</p></td> +<td><p>10000 ms</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">pr-single-hop-enabled</code></p></td> +<td><p>Setting used for single-hop access to partitioned region data in the servers for some data operations. See <a href="../client-cache/application-plugins.html#application-plugins__section_348E00A84F274D4B9DBA9ECFEB2F012E">PartitionResolver</a>. See note in <code class="ph codeph">thread-local-connections</code> below.</p></td> +<td><p>True</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">read-timeout</code></p></td> +<td><p>Number of milliseconds to wait for a response from a server before the connection times out.</p></td> +<td><p>10000</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">retry-attempts</code></p></td> +<td><p>Number of times to retry an operation after a time-out or exception for high availability. If set to -1, the pool tries every available server once until it succeeds or has tried all servers.</p></td> +<td><p>-1</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">server-group</code></p></td> +<td><p>Server group from which to select connections. If not specified, the global group of all connected servers is used.</p></td> +<td><p>empty</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">socket-buffer-size</code></p></td> +<td><p>Size of the socket buffer, in bytes, on each connection established.</p></td> +<td><p>32768</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">statistic-interval</code></p></td> +<td><p>Default frequency, in milliseconds, with which the client statistics are sent to the server. A value of <code class="ph codeph">-1</code> indicates that the statistics are not sent to the server.</p></td> +<td><p>-1</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">subscription-ack-interval</code></p></td> +<td><p>Number of milliseconds to wait before sending an acknowledgment to the server about events received from the subscriptions.</p></td> +<td><p>100</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">subscription-enabled</code></p></td> +<td><p>Whether to establish a server to client subscription.</p></td> +<td><p>False</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">subscription-message-tracking-timeout</code></p></td> +<td><p>Number of milliseconds for which messages sent from a server to a client are tracked. The tracking is done to minimize duplicate events.</p></td> +<td><p>90000</p></td> +</tr> +<tr class="odd"> +<td><p><code class="ph codeph">subscription-redundancy</code></p></td> +<td><p>Redundancy for servers that contain subscriptions established by the client. A value of <code class="ph codeph">-1</code> causes all available servers in the specified group to be made redundant.</p></td> +<td><p>0</p></td> +</tr> +<tr class="even"> +<td><p><code class="ph codeph">thread-local-connections</code></p></td> +<td><p>Whether the connections must have affinity to the thread that last used them.</p> +<div class="note note"> +<b>Note:</b> +<p>To set this to <code class="ph codeph">true</code>, also set <code class="ph codeph">pr-single-hop-enabled</code> to <code class="ph codeph">false</code>. A <code class="ph codeph">true</code> value in <code class="ph codeph">pr-single-hop-enabled</code> automatically assigns a <code class="ph codeph">false</code> value to <code class="ph codeph">thread-local-connections</code>...</p> +</div></td> +<td><p>False</p></td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">update-locator-list-interval</code></td> +<td>An integer number of milliseconds defining the interval between locator list updates. If the value is less than or equal to 0, the update will be disabled.</td> +<td>5000</td> +</tr> +</tbody> +</table> + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools.html.md.erb new file mode 100644 index 0000000..89a0333 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/configuring-pools.html.md.erb @@ -0,0 +1,25 @@ +--- +title: Configuring Pools +--- + +A pool can be configured as locators or as a list of servers. + +You configure locator, server, and pool settings declaratively in the client's `cache.xml` file or programmatically through the `PoolFactory` method. You create an instance of `PoolFactory` through `PoolManager`. + +- **[Native Client Pool API](native-client-pool-api.html)** + + The Geode native client API allows your clients to create and manage connection pools. The server side does not have an API. + +- **[Pool Configuration Example and Settings](configuring-pools-attributes-example.html)** + + Connection pools require standard client/server distributed system and cache configuration settings. You must also configure settings for the locator, server, and pool elements. + +- **[Subscription Properties](subscription-properties.html)** + + Each connection pool has a single subscription connection that can be to any server that matches the requirements of the connection pool. + +- **[Running the Connection Pool Code](running-connection-pool-code.html)** + + Examples demonstrate a simple procedure to create a pool factory and then create a pool instance in C++ and C\#. They also help you to execute a query. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/connection-pools.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/connection-pools.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/connection-pools.html.md.erb new file mode 100644 index 0000000..72fa97f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/connection-pools.html.md.erb @@ -0,0 +1,15 @@ +--- +title: Using Connection Pools +--- + +*Using Connection Pools* describes how connection pools achieve load balancing for the client and describes how to configure connection pools as server locators or as a list of servers. + +- **[How Client Load Balancing Works](client-load-balancing.html)** + + In a distributed system, servers can be added or removed and their capacity to service new client connections may vary. The server connectivity options are specified in the connection pool configuration. + +- **[Configuring Pools](configuring-pools.html)** + + A pool can be configured as locators or as a list of servers. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/discovering-locators-dynamically.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/discovering-locators-dynamically.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/discovering-locators-dynamically.html.md.erb new file mode 100644 index 0000000..ed9ee6a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/discovering-locators-dynamically.html.md.erb @@ -0,0 +1,17 @@ +--- +title: Discovering Locators Dynamically +--- + +A background thread periodically queries the locator for any other locators joining the distributed system. + +However, if locator A (to which the client is connected) goes down before it discovers locator B, locator B is never discovered even though it is alive and the client receives a `NoLocatorsAvailable` exception. + +One connection is attached to every application thread that is `local` to the respective thread. This is known as a thread local connection. + +In this case, to perform any cache operation the client is not required to obtain a connection from pool. Instead the thread local connection of the client is used. + +A thread local connection can be released by invoking the `Pool::releaseThreadLocalConnection()` method. The released connection is returned to the pool. If the number of threads is larger than the number of `max-connections`, the client throws an `AllConnectionsInUseException` after the `free-connection-timeout` lapses, unless the `Pool::releaseThreadLocalConnection()` method is used judiciously. + +If a connection expires or the server goes down on which the connection was established, a thread local connection is immediately replaced with a good connection obtained from the pool. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/native-client-pool-api.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/native-client-pool-api.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/native-client-pool-api.html.md.erb new file mode 100644 index 0000000..afd8f43 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/native-client-pool-api.html.md.erb @@ -0,0 +1,22 @@ +--- +title: Native Client Pool API +--- + +The Geode native client API allows your clients to create and manage connection pools. The server side does not have an API. + +This section lists the primary native client API for pool management. For complete information on the classes and interfaces described here, see the API documentation. + +**Note:** +Only C\# versions of Pool API interfaces, classes, and methods are shown throughout the text in this section (example: `Pool.GetQueryService()`) . The code examples demonstrate both C++ and C\# versions. + +**Gemstone::GemFire::Cache** + +- `Pool` interface. API to retrieve pool attributes. +- `PoolFactory` interface. API to configure pool attributes. +- `PoolManager` interface. API to create a `PoolFactory` object and to find the pool objects. +- `AttributesFactory` class. Has a new method `setPoolname` which assigns a pool to a region. Operations performed on the configured region use connections from the pool. + +**Note:** +A region can have a pool attached to it. A pool may have multiple regions attached to it. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/running-connection-pool-code.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/running-connection-pool-code.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/running-connection-pool-code.html.md.erb new file mode 100644 index 0000000..8ae4fcb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/running-connection-pool-code.html.md.erb @@ -0,0 +1,59 @@ +--- +title: Running the Connection Pool Code +--- + +Examples demonstrate a simple procedure to create a pool factory and then create a pool instance in C++ and C\#. They also help you to execute a query. + +The examples create a pool with locators. Ensure that you create a pool with locators or endpoints, but not both. The first example demonstrates creating a pool by adding locators. The second example demonstrates creating a pool by adding servers. For more information, see the example in the QuickStart Guide. + +## Connection Pool Creation and Execution Using C++ + +``` pre +PropertiesPtr prptr = Properties::create(); +systemPtr = CacheFactory::createCacheFactory(prptr); + +cachePtr = systemPtr->create(); +PoolFactoryPtr poolFacPtr = PoolManager::createFactory(); +//to create pool add either endpoints or add locators or servers +//pool with endpoint, adding to pool factory +//poolFacPtr->addServer("localhost", 12345 /*port number*/); +//pool with locator, adding to pool factory +poolFacPtr->addLocator("localhost", 34756 /*port number*/); +PoolPtr pptr = NULLPTR; +if ((PoolManager::find("examplePool")) == NULLPTR) { + // Pool with this name does not exist + pptr = poolFacPtr->create("examplePool"); +} +RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(CACHING_PROXY); +regionPtr = regionFactory + ->setPoolName("examplePool") + ->create("regionName"); +QueryServicePtr qs = cachePtr->getQueryService("examplePool"); +``` + +## Connection Pool Creation and Execution Using C\# .NET + +``` pre +Properties prop = Properties.Create(); +CacheFactory cacheFactory = CacheFactory.CreateCacheFactory(prop); +Cache cache = cacheFactory.Create(); + +PoolFactory poolFact = PoolManager.CreateFactory(); +//to create pool add either endpoints or add locators +//pool with endpoint, adding to pool factory. +poolFact.AddServer("localhost", 40404 /*port number*/); +//pool with locator, adding to pool factory +//poolFact.AddLocator("hostname", 15000 /*port number*/); +Pool pool = null; +if (PoolManager.Find("poolName") == null) { + pool = poolFact.Create("poolName"); +} +int loadConditInterval = pool.LoadConditioningInterval; +RegionFactory regionFactory = + cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY); +IRegion<string, string> region = + regionFactory.SetPoolName(poolName).Create<string, string>(regionName); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/connection-pools/subscription-properties.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/connection-pools/subscription-properties.html.md.erb b/geode-docs/docs/geode-native-docs/connection-pools/subscription-properties.html.md.erb new file mode 100644 index 0000000..0e175ab --- /dev/null +++ b/geode-docs/docs/geode-native-docs/connection-pools/subscription-properties.html.md.erb @@ -0,0 +1,24 @@ +--- +title: Subscription Properties +--- + +Each connection pool has a single subscription connection that can be to any server that matches the requirements of the connection pool. + +When a client registers interest for a region, if the connection pool does not already have a subscription channel, the connection pool sends a message to the server locator, and the server locator chooses servers to host the queue and return those server names to the client. The client then contacts the chosen servers and asks them to create the queue. + +The client maintains at least one connection with each server hosting a queue. If the server does not detect any connections from a non-durable client, it drops the client queue and closes all artifacts for the client. For information about durable client subscriptions, see [Durable Client Messaging](../preserving-data/durable-client-messaging.html#concept_F88B659FB4324F599924F3F2933452B4). + +## <a id="subscription-properties__section_294BD33FBDC6454FAD9C5118829EBBA4" class="no-quick-link"></a>Requesting a Subscription Region Queue + +The client-to-server locator request is a short lived TCP request. The client sends a message with: + +- The client ID. +- (Optional) target server group. +- Number of redundant copies. +- Servers to exclude from the results. This list is used if the client cannot connect to a server and needs to request a new one. + +The server locator responds with a list of servers. The client is responsible for contacting the primary and secondaries and asking them to host the queue. + +For durable subscriptions, the server locator must be able to locate the servers that host the queues for the durable client. When a durable client sends a request, the server locator queries all the available servers to see if they are hosting the subscription region queue for the durable client. If the server is located, the client is connected to the server hosting the subscription region queue. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/1-how-cont-query-works.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/1-how-cont-query-works.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/1-how-cont-query-works.html.md.erb new file mode 100644 index 0000000..c62282b --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/1-how-cont-query-works.html.md.erb @@ -0,0 +1,55 @@ +--- +title: How Continuous Querying Works +--- + +C++ and .NET clients register interest in events using simple query expressions. Events are sent to client listeners that you can program to do whatever your application requires. + +## <a id="security__section_D4F0FAC4880A49A18D6E11B777C2716A" class="no-quick-link"></a>Overview of CQ Operations + +You subscribe to server-side events using SQL-type query filtering. The native client sends a query to the server side for execution and receives the events that satisfy the criteria. + +For example, in a region storing stock market trade orders, you can retrieve all orders over a certain price by running a CQ with a query like this: + +``` pre +SELECT * FROM /tradeOrder t WHERE t.price > 100.00 +``` + +When the CQ is running, the server sends the client all new events that affect the results of the query. On the native client side, listeners programmed by you receive and process incoming events. For the example query on `/tradeOrder`, you might program a listener to push events to a GUI where higher-priced orders are displayed. CQ event delivery uses the client/server subscription framework described in [Client to Server Connection Process](../client-cache/client-to-server-connection.html#client-to-server-connection). + +CQs do not update the native client region. This is in contrast to other server-to-client messaging, such as the updates sent to satisfy interest registration and responses to get requests from the client. CQs are notification tools for the CQ listeners, which can be programmed in any way your application requires. + +When a CQ is running against a server region, each entry event is evaluated against the CQ query by the thread that updates the server cache. If either the old or the new entry value satisfies the query, the thread puts a `CqEvent` in the client's queue. The `CqEvent` contains information from the original cache event, plus information specific to the CQ's execution. Once received by the client, the `CqEvent` is passed to the `onEvent` method of all `CqListeners` defined for the CQ. + +## <a id="security__section_9FEA0CFD3DA64BF5B42B37F5CE05C993" class="no-quick-link"></a>Logical Architecture and Data Flow + +Clients can execute any number of CQs, with each CQ given any number of listeners. This figure shows the logical architecture of continuous querying. + +<img src="../common/images/10-Continuous_Querying-1.gif" id="security__image_7B1C48755BE541BDBCD7DCD442728754" class="image" /> + +The next figure shows the typical CQ data flow when entries are updated in the server cache. A description of the data flow follows, along with a description of CQ state and life cycle. + +<img src="../common/images/10-Continuous_Querying-3.gif" id="security__image_F5E03A24E29C41B683EC6E85B3B64977" class="image" /> + +1. Entry events come to the server's cache from any source: the server or its peers, distribution from remote sites, or updates from a client. +2. For each event, the server's CQ executor framework checks for a match with the CQs it has running. +3. If the old or new entry value satisfies a CQ query, a CQ event is sent to the CQ's listeners on the client side. Each listener for the CQ gets the event. In the preceding figure: + - Both new and old prices for entry X satisfy the CQ query, so that event is sent indicating an update to the query results. + - The old price for entry Y satisfied the query, so it was part of the query results. The invalidation of entry Y means that it does not satisfy the query. Because of this, the event is sent indicating that it is destroyed in the query results. + - The price for the newly created entry Z does not satisfy the query, so no event is sent. + +The region operations do not translate directly to specific query operations, and the query operations do not specifically describe the region events. Instead, each query operation describes how its corresponding region event affects the query results. For more information, see [CqEvent Object](5c-cq-event-object.html#security). + +## <a id="security__section_677EB38AB60E4410A8A60980CD3BAACB" class="no-quick-link"></a>State and Life Cycle + +A CQ has three possible states that can be accessed from the client by calling `CqQuery.getState`. + +- `STOPPED`. The CQ has been created but not yet executed, or it has been explicitly stopped from executing. The stopped CQ uses system resources. You start or restart the CQ by calling the execute method on `CqQuery`. +- `RUNNING`. The CQ is being executed on the server for all events in the region referenced by the query. Results are sent to all client listeners associated with the `CqQuery`. +- `CLOSED`. The CQ is closed and is not using system resources. Invoking an `execute` or `stop` method on closed `CqQuery` throws an exception. + +**Typical CQ life cycle** + +1. The client creates the CQ. This sets up everything for running the query and provides the client with a `CqQuery` object, but does not execute the CQ. At this point, the query is in a `STOPPED `state, ready to be closed or run. +2. The client runs the CQ with an API call to one of the `CqQuery execute*` methods. This puts the query into a `RUNNING` state on the client and on the server. +3. The CQ is closed by a client call to `CqQuery.close`. This de-allocates all resources in use for the CQ on the client and server. At this point, the cycle could begin again with the creation of a new `CqQuery` instance. + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/2-config-for-continuous-querying.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/2-config-for-continuous-querying.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/2-config-for-continuous-querying.html.md.erb new file mode 100644 index 0000000..26a999d --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/2-config-for-continuous-querying.html.md.erb @@ -0,0 +1,13 @@ +--- +title: Configuring Your System for Continuous Querying +--- + +The continuous query (CQ) functionality requires standard client/server distributed system and cache configuration settings. + +- The client region must use a pool with subscription-enabled set to true . +- If you want your CQs to be highly available, configure your servers for high availability as described in [Configuring Highly Available Servers](geodeman/developing/events/configuring_highly_available_servers.html) in the *User's Guide*. When your servers are highly available, CQs are registered on primary and secondary servers, and server failover is performed without any interruption to CQ messaging. CQ events messaging uses the same queues used for server-to-client messaging. + **Note:** + When CQ is used with high availability, the overhead for CQs is higher than for the key-based interest list registration. CQs are executed on the primary and all secondary servers, so they require more overall server processing. + +- To obtain a list of all durable CQs registered on the server, use the `QueryService.getAllDurableCqsFromServer` API. +- If you want your CQs to be durable, configure your native clients for durable messaging. When your clients are durable, you can create durable CQs whose events are maintained during client disconnects and replayed for the client when it reconnects. The process and data flow particular to durable CQs is described in [Durable Client Messaging](../preserving-data/durable-client-messaging.html).
