You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by db...@apache.org on 2018/08/28 23:37:33 UTC
[geode-native] branch develop updated: GEODE-5648: Native client
user guide - add a page describing Continuous Queries (#340)
This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode-native.git
The following commit(s) were added to refs/heads/develop by this push:
new 232e5ca GEODE-5648: Native client user guide - add a page describing Continuous Queries (#340)
232e5ca is described below
commit 232e5caf4913dd0e33a59124bfea267327513ae4
Author: Dave Barnes <db...@pivotal.io>
AuthorDate: Tue Aug 28 16:37:31 2018 -0700
GEODE-5648: Native client user guide - add a page describing Continuous Queries (#340)
---
.../source/subnavs/geode-nc-nav.erb | 14 +--
.../about-client-users-guide.html.md.erb | 2 +-
.../registering-interest-for-entries.html.md.erb | 110 +++++++++++++++++++++
.../continuous-queries.html.md.erb | 54 ++++++++++
.../getting-started-nc-client.html.md.erb | 2 +-
5 files changed, 171 insertions(+), 11 deletions(-)
diff --git a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
index c83b9a6..7b8acef 100644
--- a/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
+++ b/docs/geode-native-book/master_middleman/source/subnavs/geode-nc-nav.erb
@@ -67,16 +67,12 @@ limitations under the License.
</ul>
</li>
- <li class="has_submenu">
+ <li>
<a href="/docs/guide-native/<%=vars.product_version_nodot%>/remote-querying/remote-queries.html">Remote Queries</a>
- <ul>
- <li>
- <a href="/docs/guide-native/<%=vars.product_version_nodot%>/remote-querying/remote-queries.html#RemoteQueryBasics">Remote Query Basics</a>
- </li>
- <li>
- <a href="/docs/guide-native/<%=vars.product_version_nodot%>/remote-querying/remote-queries.html#RemoteQueryAPI">Remote Query API</a>
- </li>
- </ul>
+ </li>
+
+ <li>
+ <a href="/docs/guide-native/<%=vars.product_version_nodot%>/continuous-querying/continuous-queries.html">Continuous Queries</a>
</li>
<li class="has_submenu">
diff --git a/docs/geode-native-docs/about-client-users-guide.html.md.erb b/docs/geode-native-docs/about-client-users-guide.html.md.erb
index 43e0084..6ac7512 100644
--- a/docs/geode-native-docs/about-client-users-guide.html.md.erb
+++ b/docs/geode-native-docs/about-client-users-guide.html.md.erb
@@ -17,7 +17,7 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-Published August 10, 2018
+Published August 27, 2018
This documentation describes the <%=vars.product_name_long%> Native Client.
diff --git a/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb b/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb
new file mode 100644
index 0000000..dfc570b
--- /dev/null
+++ b/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb
@@ -0,0 +1,110 @@
+---
+title: Registering Interest for Entries
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+For 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">
+ ...
+```
+
+All 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 non-Java clients.
diff --git a/docs/geode-native-docs/continuous-querying/continuous-queries.html.md.erb b/docs/geode-native-docs/continuous-querying/continuous-queries.html.md.erb
new file mode 100644
index 0000000..6e7ac10
--- /dev/null
+++ b/docs/geode-native-docs/continuous-querying/continuous-queries.html.md.erb
@@ -0,0 +1,54 @@
+---
+title: Continuous Queries
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+The C++ and .NET clients can run queries that continuously monitor events in the <%=vars.product_name%> cache server and return results
+when triggered.
+For details on the server-side setup for continuouse queries,
+see [How Continuous Querying Works](/serverman/developing/continuous_querying/how_continuous_querying_works.html) in the *<%=vars.product_name%> User Guide*.
+
+## <a id="cq_main_features" ></a>Main Features of Continuous Querying
+
+Continuous querying in the native client has the following features:
+
+- **Standard <%=vars.product_name%> native client query syntax and semantics**. CQ queries are expressed in the same language used for other native client queries. See [Remote Querying](../remote-querying/remote-queries.html).
+
+- **Standard <%=vars.product_name%> events-based management of CQ events**. The event handling used
+to process CQ events is based on the standard <%=vars.product_name%> event handling framework.
+
+- **Complete integration with the client/server architecture**. CQ functionality uses existing
+server-to-client messaging mechanisms to send events. All tuning of your server-to-client
+messaging also tunes the messaging of your CQ events. If your system is configured for high
+availability then your CQs are highly available, with seamless failover provided in case of
+server failure (see [High Availability for Client-to-Server Communication](../preserving-data/high-availability-client-server.html)).
+If your clients are durable, you can also define any of your CQs as durable (see [Durable Client Messaging](../preserving-data/durable-client-messaging.html)).
+
+- **Interest criteria based on data values**. CQ queries are run against the region's entry values.
+Compare this to register interest by reviewing [Registering Interest for Entries](../client-cache/registering-interest-for-entries.html).
+
+- **Active query execution**. Once initialized, the queries only operate on new events instead of on the entire region data set.
+Events that change the query result are sent to the client immediately.
+
+## <a id="typical_cq_lifecycle"></a>Typical CQ Lifecycle
+
+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.
+
diff --git a/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb b/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb
index 6326680..ca1d263 100644
--- a/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb
+++ b/docs/geode-native-docs/getting-started/getting-started-nc-client.html.md.erb
@@ -25,7 +25,7 @@ Refer to the [_<%=vars.product_name%> User's Guide_](/serverman/about_<%=vars.p
Whether you are developing a C++ or .NET application, you will need some essential tools, such as a compiler and a dynamic linker.
Your compiler must have access to the Native Client header files, and the dynamic loader must have access to the Native Client libraries.
-The header files and libraries are located in *native-client-dir*.
+The header files and libraries are located in the Native Client installation directory (referred to as *native-client-dir* elsewhere in this guide).
### <a id="app_dev_walkthroughs"></a>Application Development Walkthroughs