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 53686e5 Feature/geode 4728 (#454)
53686e5 is described below
commit 53686e5790567f2d7a39ae39a232aef5e0032403
Author: Dave Barnes <[email protected]>
AuthorDate: Mon Mar 4 11:52:18 2019 -0800
Feature/geode 4728 (#454)
* GEODE-4728 - User Guide, Incorporate reviewer suggestions
---
.../source/subnavs/geode-nc-nav.erb | 13 +-
.../continuous-queries.html.md.erb | 51 ++--
.../function-execution.html.md.erb | 74 +++--
.../function-execution.html.md.erb-NOTOC | 300 ---------------------
.../regions/region-attributes.html.md.erb | 35 +--
docs/geode-native-docs/regions/regions.html.md.erb | 4 +-
.../registering-interest-for-entries.html.md.erb | 0
docs/geode-native-docs/remote-queries.html.md.erb | 36 ++-
.../security/authentication.html.md.erb | 2 +-
.../security/security.html.md.erb | 2 +-
.../security/sslclientserver.html.md.erb | 5 +-
.../transactions/transactions.html.md.erb | 2 +-
12 files changed, 120 insertions(+), 404 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 859b20a..c9b6e9f 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
@@ -38,13 +38,8 @@ limitations under the License.
<li class="has_submenu">
<a
href="/docs/geode-native/<%=vars.product_version_nodot%>/configuring/configuration.html">Configuring
a Client Application</a>
<ul>
- <li class="has_submenu">
+ <li>
<a
href="/docs/geode-native/<%=vars.product_version_nodot%>/configuring/system-level-configuration.html">System
Level Configuration</a>
- <ul>
- <li>
- <a
href="/docs/geode-native/<%=vars.product_version_nodot%>/configuring/sysprops.html">System
Properties</a>
- </li>
- </ul>
</li>
</ul>
</li>
@@ -56,6 +51,9 @@ limitations under the License.
<a
href="/docs/geode-native/<%=vars.product_version_nodot%>/regions/regions.html">Configuring
Regions</a>
<ul>
<li>
+ <a
href="/docs/geode-native/<%=vars.product_version_nodot%>/regions/registering-interest-for-entries.html">Registering
Interest for Entries</a>
+ </li>
+ <li>
<a
href="/docs/geode-native/<%=vars.product_version_nodot%>/regions/region-attributes.html">Region
Attributes</a>
</li>
</ul>
@@ -92,6 +90,9 @@ limitations under the License.
<li>
<a
href="/docs/geode-native/<%=vars.product_version_nodot%>/transactions/transactions.html">Transactions</a>
</li>
+ <li>
+ <a
href="/docs/geode-native/<%=vars.product_version_nodot%>/configuring/sysprops.html">System
Properties</a>
+ </li>
</ul>
</div>
</div>
diff --git a/docs/geode-native-docs/continuous-queries.html.md.erb
b/docs/geode-native-docs/continuous-queries.html.md.erb
index 4ef7510..dd9fdc2 100644
--- a/docs/geode-native-docs/continuous-queries.html.md.erb
+++ b/docs/geode-native-docs/continuous-queries.html.md.erb
@@ -28,7 +28,7 @@ in the *<%=vars.product_name%> User Guide*.
Continuous querying provides the following features:
-- **Standard <%=vars.product_name%> native client query syntax and
semantics**. Continuous queries are expressed in the same language used for
other native client queries. See [Remote Queries](remote-queries.html).
+- **Standard <%=vars.product_name%> native client query syntax and
semantics**. Continuous queries are expressed in the same language used for
other native client queries. See [Remote Queries](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.
@@ -41,16 +41,18 @@ server failure (see [High Availability for Client-to-Server
Communication](prese
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**. Continuous 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).
+Compare this to register interest by reviewing [Registering Interest for
Entries](regions/registering-interest-for-entries.html).
-- **Active query execution**. Once initialized, the queries operate only on
new events, rather than on the entire region data set.
-Events that change the query result are sent to the client immediately.
+- **Active query execution**. Once initialized, the queries operate on new
events. Events that change the query result are sent to the client immediately.
## <a id="cq_api"></a>Typical Continuous Query 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 initiates 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. The server remotely evaluates the query string, and optionally
returns the results to the client.
-1. The CqListener waits for events. When it receives events, it takes action
accordingly. Events are not result sets. If the action requires doing something
with the data, the data must first be retrieved.
+2. The client initiates 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. The server remotely evaluates the query string, and optionally
returns the results to the client. `CqQuery execute*` methods include:
+ - .NET: `CqQuery.Execute()` and `CqQuery.ExecuteWithInitialResults()`
+ - C++: `CqQuery.execute()` and `CqQuery.executeWithInitialResults()`
+
+1. A CQ Listener waits for events. When it receives events, it takes action
accordingly with the data in the CqEvent.
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.
## <a id="ExecutingACQ"></a>Executing a Continuous Query from the Client
@@ -58,15 +60,16 @@ Events that change the query result are sent to the client
immediately.
The essential steps to create and execute a continuous query are:
1. Create an instance of the `QueryService` class. If you are using the pool
API (recommended), you should obtain the `QueryService` from the pool.
-1. Create a `CqListener` to field events sent from the server.
-1. Use the `Query.execute()` method to submit the query string to the cache
server. The server
- remotely evaluates the query string, then monitors those results and
notifies the client if they change.
+1. Define a CQ Listener (in .NET, an `ICqListener`, in C++, a `CqListener`)
to field events sent from the server.
+1. Use one of the `CqQuery execute*` methods to submit the query string to
the cache server.
+1. The server remotely evaluates the query string, then monitors those
results and notifies the client if they change.
+1. The client listens for changes that match the query predicate.
1. Iterate through the returned objects.
1. When finished, close down the continuous query.
### <a id="DotNetCQExample"></a>.NET Continuous Query Example
-These C# code excerpts are from the `examples\dotnet\ContinuousQueryCs`
example included in your client
+These C# code excerpts are from the `examples\dotnet\continuousquery` example
included in your client
distribution. See the example for full context.
Following the steps listed above,
@@ -77,15 +80,17 @@ Following the steps listed above,
var queryService = pool.GetQueryService();
```
-1. Create a CQ Listener:
+1. Define an ICqListener:
```
- var cqListener = new MyCqListener<string, Order>();
+ public class MyCqListener<TKey, TResult> : ICqListener<TKey, TResult>
+ {
```
-1. Insert the CQ Listener into a CQ attributes object:
+1. Create an instance of your ICqListener and insert it into a CQ attributes
object:
```
+ var cqListener = new MyCqListener<string, Order>();
var cqAttributesFactory = new CqAttributesFactory<string, Order>();
cqAttributesFactory.AddCqListener(cqListener);
var cqAttributes = cqAttributesFactory.Create();
@@ -97,12 +102,18 @@ Following the steps listed above,
var query = queryService.NewCq("MyCq", "SELECT * FROM /example_orderobject
WHERE quantity > 30", cqAttributes, false);
```
+1. Execute the query:
+
+ ```
+ query.Execute();
+ ```
+
1. Wait for events and do something with them.
```
/* Excerpt from the CqListener */
- /* Determine OP Type */
+ /* Determine Operation Type */
switch (ev.getQueryOperation())
{
case CqOperation.OP_TYPE_CREATE:
@@ -149,13 +160,13 @@ Following the steps listed above,
auto queryService = pool->getQueryService();
```
-1. Create a CQ Listener:
+1. Define a CqListener:
```
class MyCqListener : public CqListener {
```
-1. Insert the CQ Listener into a CQ attributes object:
+1. Create an instance of your CqListener and insert it into a CQ attributes
object:
```
CqAttributesFactory cqFactory;
@@ -174,12 +185,18 @@ Following the steps listed above,
cqAttributes);
```
+1. Execute the query:
+
+ ```
+ query->execute();
+ ```
+
1. Wait for events and do something with them.
```
/* Excerpt from the CqListener */
- /* Determine OP Type */
+ /* Determine Operation Type */
switch (cqEvent.getQueryOperation()) {
case CqOperation::OP_TYPE_CREATE:
opStr = "CREATE";
diff --git a/docs/geode-native-docs/function-execution.html.md.erb
b/docs/geode-native-docs/function-execution.html.md.erb
index da7301b..c2c7f91 100644
--- a/docs/geode-native-docs/function-execution.html.md.erb
+++ b/docs/geode-native-docs/function-execution.html.md.erb
@@ -19,11 +19,15 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-A client can invoke a server-resident function, with paramaters, and can
collect and operate on the returned results.
+A client can invoke a server-resident function, with parameters, and can
collect and operate on the returned results.
## <a id="server_side_requirements"></a>Server-side Requirements
-To be callable from your client, a function must be resident on the server and
registered as available for client access.
+To be callable from your client, a function must be
+
+- resident on the server, and
+- registered as available for client access.
+
See [Executing a Function in
<%=vars.product_name_long%>](/serverman/developing/function_exec/function_execution.html)
in the <%=vars.product_name%> User Guide for details on how to write and
register server-resident functions.
@@ -34,46 +38,34 @@ The client must connect to the server through a connection
pool in order to invo
## <a id="how_functions_execute"></a>How Functions Execute
1. The calling client application runs the `execute` method on the
`Execution` object. The function must already be registered on the servers.
-2. The function is invoked on all servers where it needs to run. The
locations are determined by the `FunctionService on*`
+2. The function is invoked on the servers where it needs to run. The servers
are determined by the `FunctionService on*`
method calls, region configuration, and any filters.
3. If the function has results, the result is returned in a `ResultCollector`
object.
-4. The client collects results using the result collector `getResult`.
+4. The client collects results using the `ResultCollector.getResult()` method.
In every client where you want to execute the function and process the results:
- Use one of the `FunctionService on*` methods to create an `Execution`
object. The `on*` methods,
-`onRegion`, `onServer` and `onServers`, define the highest level where the
function is run. If
-you use `onRegion` you can further narrow your run scope by setting key
filters. The function run
-using `onRegion` is a data dependent function – the others are
data-independent functions.
-You can run a data dependent function against partitioned and colocated
partitioned regions. From the client, provide the appropriate key
+`onRegion`, `onServer` and `onServers`, define the highest level where the
function is run.
+- If you use `onRegion` you can further narrow your run scope by setting key
filters.
+- A function run using `onRegion` is a *data dependent* function – others are
*data-independent* functions.
+- You can run a data dependent function against partitioned and colocated
partitioned regions. From the client, provide the appropriate key
sets to the function call.
-- Use the `Execution` object as needed for additional function configuration.
You can:
- - Provide a set of data keys to `withFilter` to narrow the execution
scope. This works only for `onRegion` Execution objects.
- - Provide function arguments to `withArgs`.
- - Provide a custom `ResultCollector` to `withCollector`.
+- The `Execution` object allows you to customize the invocation by:
+ - Providing a set of data keys to `withFilter` to narrow the execution
scope. This works only for `onRegion` Execution objects (data-dependent
functions).
+ - Providing function arguments to `withArgs`.
+ - Defining a custom `ResultCollector` for `withCollector`.
-- Call the `Execution` object execute method to run the function.
+- Call the `Execution.execute()` method to run the function.
## <a id="processing_function_results"></a>Processing Function Results
-The client may use the default result collector. If the client needs special
results handling, code
-a custom `ResultsCollector` implementation to replace the default. Use the
-`Execution::withCollector` method to define the custom collector.
-
-For example, to program your client to get the results from a function, use
the result collector returned from the function execution, like this:
-
-```cpp
-ResultCollectorPtr rc = FunctionService::onRegion(region)
- ->withArgs(args)
- ->withFilter(keySet)
- ->withCollector(new MyCustomResultCollector())
- .execute(Function);
-CacheableVectorPtr functionResult = rc.getResult();
-```
-
+To get the results from the function in the client app, use the result
collector returned from the function execution.
The `getResult` methods of the default result collector block until all
results are received, then return the full result set.
+The client can use the default result collector. If the client needs special
results handling, code a custom `ResultsCollector` implementation to replace
the default.
+Use the `Execution::withCollector` method to specify the custom collector.
To handle the results in a custom manner:
1. Write a class that implements the `ResultCollector` interface to handle
the results in a custom manner. The methods are of two types: one handles data
and information from <%=vars.product_name%> and populates the results set,
while the other returns the compiled results to the calling application:
@@ -81,20 +73,22 @@ To handle the results in a custom manner:
- `endResults` is called to signal the end of all results from the
function execution.
- `getResult` is available to your executing application (the one that
calls `Execution.execute`) to retrieve the results. This may block until all
results are available.
- `clearResults` is called to clear partial results from the results
collector. This is used only for highly available `onRegion` functions where
the calling application waits for the results. If the call fails, before
<%=vars.product_name%> retries the execution, it calls `clearResults` to ready
the instance for a clean set of results.
-2. Use the `Execution` object in your executing member to call
`withCollector`, passing your custom collector, as shown in the example above.
+2. Use the `Execution` object in your executing member to call
`withCollector`, passing your custom collector.
# <a id="examples"></a>Examples
-The native client source release contains examples of function execution
written for .NET and
-C++. The examples are located in `../examples/dotnet/FunctionExecutionCs` and
+The native client release contains examples of function execution written for
.NET and
+C++. The examples are located in `../examples/dotnet/functionexecution` and
`../examples/cpp/function-execution`, respectively.
-Both examples begin with a server-side script that runs `gfsh` commands to
create
-a region, simply called "partition_region", which is preloaded with a JAR file
containing the
-server-side Java function code. The function, called
"ExampleMultiGetFunction", is defined in the
+The two examples share some common elements:
+
+- They begin with a server-side script that runs `gfsh` commands to create a
region, simply called "partition_region".
+- The function is preloaded with a JAR file containing the server-side Java
function code.
+- The function, called "ExampleMultiGetFunction", is defined in the
`examples/utilities` directory of your distribution. As its input parameter,
the function takes an array of keys,
then performs a `get` on each key and returns an array containing the results.
-The function does not load values into the data store. That is a separate
operation, performed in these examples by
+- The function does not load values into the data store. That is a separate
operation, performed in these examples by
the client, and does not involve the server-side function.
As prerequisites, the client code must be aware of the connection to the
server, the name of the function, and the expected type/format
@@ -103,12 +97,12 @@ of the input parameter and return value.
The client:
- creates an execution object
-- populates the execution object with input parameters
-- invokes the object's execute method to invoke the server-side function.
+- provides the execution object with a populated input parameter array
+- invokes the object's execute method to invoke the server-side function
-If the client expects results, it must create a result
-object. Optionally, the client can use a provided ResultCollector which offers
some predefined
-methods for iterating over and processing return values.
+If the client expects results, it must create a result object. The C++ example
uses a result object to hold the function results.
+Alternatively, the client can use a provided Result Collector which offers
some predefined methods for iterating over and processing return values.
+The .NET example uses a built-in result collector
(`IResultCollector.getRestults()`) to retrieve the function results.
## <a id="dotnet_example"></a>.NET Example
This section contains code snippets showing highlights of the .NET function
execution example. They are not intended for cut-and-paste execution.
diff --git a/docs/geode-native-docs/function-execution.html.md.erb-NOTOC
b/docs/geode-native-docs/function-execution.html.md.erb-NOTOC
deleted file mode 100644
index 92ef29b..0000000
--- a/docs/geode-native-docs/function-execution.html.md.erb-NOTOC
+++ /dev/null
@@ -1,300 +0,0 @@
----
-title: Function Execution
----
-
-<!--
-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.
--->
-
-A client can invoke a server-resident function, with paramaters, and can
collect and operate on the returned results.
-
-## Server-side Requirements
-
-To be callable from your client, a function must be resident on the server and
registered as available for client access.
-See [Executing a Function in
<%=vars.product_name_long%>](/serverman/developing/function_exec/function_execution.html)
-in the <%=vars.product_name%> User Guide for details on how to write and
register server-resident functions.
-
-## Client-side Requirements
-
-The client must connect to the server through a connection pool in order to
invoke a server-side function.
-
-## How Functions Execute
-
-1. The calling client application runs the `execute` method on the
`Execution` object. The object must already be registered on the servers.
-2. The function is invoked on all servers where it needs to run. The
locations are determined by the `FunctionService on*`
-method calls, region configuration, and any filters.
-3. If the function has results, the result is returned in a `ResultCollector`
object.
-4. The client collects results using the result collector `getResult`.
-
-In every client where you want to execute the function and process the results:
-
-- Use one of the `FunctionService on*` methods to create an `Execution`
object. The `on*` methods,
-`onRegion`, `onServer` and `onServers`, define the highest level where the
function is run. If
-you use `onRegion` you can further narrow your run scope by setting key
filters. The function run
-using `onRegion` is a data dependent function – the others are
data-independent functions.
-
-You can run a data dependent function against custom partitioned and colocated
partitioned regions. From the client, provide the appropriate key
- sets to the function call.
-
-- Use the `Execution` object as needed for additional function configuration.
You can:
- - Provide a set of data keys to `withFilter` to narrow the execution
scope. This works only for `onRegion` Execution objects.
- - Provide function arguments to `withArgs`.
- - Define a custom `ResultCollector` to `withCollector`.
-
-- Call the `Execution` object execute method to run the function.
-
-## Processing Function Results
-
-The client may use the default result collector. If the client needs special
results handling, code
-a custom `ResultsCollector` implementation to replace the default. Use the
-`Execution::withCollector` method to define the custom collector.
-
-For example, to program your client to get the results from a function, use
the result collector returned from the function execution, like this:
-
-```cpp
-ResultCollectorPtr rc = FunctionService::onRegion(region)
- ->withArgs(args)
- ->withFilter(keySet)
- ->withCollector(new MyCustomResultCollector())
- .execute(Function);
-CacheableVectorPtr functionResult = rc.getResult();
-```
-
-The `getResult` methods of the default result collector block until all
results are received, then return the full result set.
-
-To handle the results in a custom manner:
-
-1. Write a class that implements the `ResultCollector` interface to handle
the results in a custom manner. The methods are of two types: one handles data
and information from <%=vars.product_name%> and populates the results set,
while the other returns the compiled results to the calling application:
- - `addResult` is called when results arrive from the `Function` methods.
Use `addResult` to add a single result to the ResultCollector.
- - `endResults` is called to signal the end of all results from the
function execution.
- - `getResult` is available to your executing application (the one that
calls `Execution.execute`) to retrieve the results. This may block until all
results are available.
- - `clearResults` is called to clear partial results from the results
collector. This is used only for highly available `onRegion` functions where
the calling application waits for the results. If the call fails, before
<%=vars.product_name%> retries the execution, it calls `clearResults` to ready
the instance for a clean set of results.
-2. Use the `Execution` object in your executing member to call
`withCollector`, passing your custom collector, as shown in the example above.
-
-# Examples
-
-The native client source release contains examples of function execution
written for .NET and
-C++. The examples are located in `../examples/dotnet/FunctionExecutionCs` and
-`../examples/cpp/function-execution`, respectively.
-
-Both examples begin with a server-side script that runs `gfsh` commands to
create
-a region, simply called "partition_region", which is preloaded with a JAR file
containing the
-server-side Java function code. The function, called
"ExampleMultiGetFunction", is defined in the
-`examples/utilities` directory of your distribution. As its input parameter,
the function takes an array of keys,
-then performs a `get` on each key and returns an array containing the results.
-The function does not load values into the data store. That is a separate
operation, performed in these examples by
-the client, and does not involve the server-side function.
-
-As prerequisites, the client code must be aware of the connection to the
server, the name of the function, and the expected type/format
-of the input parameter and return value.
-
-The client:
-
-- creates an execution object
-- populates the execution object with input parameters
-- invokes the object's execute method to invoke the server-side function.
-
-If the client expects results, it must create a result
-object. Optionally, the client can use a provided result collector which
offers some predefined
-methods for iterating over and processing return values.
-
-## .NET Example
-This section contains code snippets showing highlights of the .NET function
execution example. They are not intended for cut-and-paste execution.
-For the complete source, see the example source directory.
-
-The .NET example creates a cache, then uses it to create a connection pool.
-
-```csharp
- var cacheFactory = new CacheFactory()
- .Set("log-level", "none");
- var cache = cacheFactory.Create();
-
- var poolFactory = cache.GetPoolFactory()
- .AddLocator("localhost", 10334);
- var pool = poolFactory.Create("pool");
-```
-
-The example uses the connection pool to create a region, with the same
characteristics and name as the server-side region (`partition_region`).
-
-```csharp
- var regionFactory = cache.CreateRegionFactory(RegionShortcut.PROXY)
- .SetPoolName("pool");
- var region = regionFactory.Create<object, object>("partition_region");
-```
-
-The sample client populates the server's datastore with values, using the API
and some sample key-value pairs.
-
-```csharp
- string rtimmonsKey = "rtimmons";
- string rtimmonsValue = "Robert Timmons";
- string scharlesKey = "scharles";
- string scharlesValue = "Sylvia Charles";
- region.Put(rtimmonsKey, rtimmonsValue, null);
- region.Put(scharlesKey, scharlesValue, null);
-```
-
-To confirm that the data has been stored, the client uses the API to retrieve
the values and write them to the console.
-This is done without reference to the server-side example function.
-
-```csharp
- var user1 = region.Get(rtimmonsKey, null);
- var user2 = region.Get(scharlesKey, null);
-
- Console.WriteLine(rtimmonsKey + " = " + user1);
- Console.WriteLine(scharlesKey + " = " + user2);
-```
-
-Next, the client retrieves those same values using the server-side example
function.
-The client code creates the input parameter, an array of keys whose values are
to be retrieved.
-
-```csharp
- ArrayList keyArgs = new ArrayList();
- keyArgs.Add(rtimmonsKey);
- keyArgs.Add(scharlesKey);
-```
-
-The client creates an execution object using `Client.FunctionService.OnRegion`
and specifying the region.
-
-```csharp
- var exc = Client.FunctionService<object>.OnRegion<object, object>(region);
-```
-
-The client then calls the server side function with its input arguments and
stores the results in a Client.IResultCollector.
-
-```csharp
- Client.IResultCollector<object> rc =
exc.WithArgs<object>(keyArgs).Execute("ExampleMultiGetFunction");
-```
-
-It then loops through the results and prints the retrieved values.
-
-```csharp
- ICollection<object> res = rc.GetResult();
-
- Console.WriteLine("Function Execution Results:");
- Console.WriteLine(" Count = {0}", res.Count);
-
- foreach (List<object> item in res)
- {
- foreach (object item2 in item)
- {
- Console.WriteLine(" value = {0}", item2.ToString());
- }
- }
-```
-
-## C++ Example
-This section contains code snippets showing highlights of the C++ function
execution example. They are not intended for cut-and-paste execution.
-For the complete source, see the example source directory.
-
-The C++ example creates a cache.
-
-```cpp
-Cache setupCache() {
- return CacheFactory()
- .set("log-level", "none")
- .create();
-}
-```
-
-The example client uses the cache to create a connection pool,
-
-```cpp
-void createPool(const Cache& cache) {
- auto pool = cache.getPoolManager()
- .createFactory()
- .addServer("localhost", EXAMPLE_SERVER_PORT)
- .create("pool");
-}
-```
-
-Then, using that pool, the client creates a region with the same
characteristics and name as the server-side region (`partition_region`).
-
-```cpp
-std::shared_ptr<Region> createRegion(Cache& cache) {
- auto regionFactory = cache.createRegionFactory(RegionShortcut::PROXY);
- auto region = regionFactory.setPoolName("pool").create("partition_region");
-
- return region;
-}
-```
-
-The sample client populates the server's datastore with values, using the API
and some sample key-value pairs.
-
-```cpp
-void populateRegion(const std::shared_ptr<Region>& region) {
- for (int i = 0; i < keys.size(); i++) {
- region->put(keys[i], values[i]);
- }
-}
-```
-
-As confirmation that the data has been stored, the sample client uses the API
to retrieve the values and write them to the console.
-This is done without reference to the server-side example function.
-
-```cpp
-std::shared_ptr<CacheableVector> populateArguments() {
- auto arguments = CacheableVector::create();
- for (int i = 0; i < keys.size(); i++) {
- arguments->push_back(CacheableKey::create(keys[i]));
- }
- return arguments;
-}
-```
-
-Next, the client retrieves those same values using the server-side example
function.
-The client code creates the input parameter, an array of keys whose values are
to be retrieved.
-
-```cpp
-std::vector<std::string> executeFunctionOnServer(const std::shared_ptr<Region>
region,
- const std::shared_ptr<CacheableVector> arguments) {
- std::vector<std::string> resultList;
-```
-
-The client creates an execution object using `Client.FunctionService.OnRegion`
and specifying the region.
-
-```cpp
- auto functionService = FunctionService::onServer(region->getRegionService());
-```
-
-The client then calls the server side function with its input arguments and
stores the results in a Client.IResultCollector.
-
-```cpp
- if(auto executeFunctionResult =
functionService.withArgs(arguments).execute(getFuncIName)->getResult()) {
- for (auto &arrayList: *executeFunctionResult) {
- for (auto &cachedString:
*std::dynamic_pointer_cast<CacheableArrayList>(arrayList)) {
-
resultList.push_back(std::dynamic_pointer_cast<CacheableString>(cachedString)->value());
- }
- }
- } else {
- std::cout << "get executeFunctionResult is NULL\n";
- }
-
- return resultList;
-}
-```
-
-It then loops through the results and prints the retrieved values.
-
-```cpp
-void printResults(const std::vector<std::string>& resultList) {
- std::cout << "Result count = " << resultList.size() << std::endl <<
std::endl;
- int i = 0;
- for (auto &cachedString: resultList) {
- std::cout << "\tResult[" << i << "]=" << cachedString << std::endl;
- ++i;
- }
-```
-
diff --git a/docs/geode-native-docs/regions/region-attributes.html.md.erb
b/docs/geode-native-docs/regions/region-attributes.html.md.erb
index d7eabe8..6460316 100644
--- a/docs/geode-native-docs/regions/region-attributes.html.md.erb
+++ b/docs/geode-native-docs/regions/region-attributes.html.md.erb
@@ -27,39 +27,28 @@ Region attribute settings determine where the data resides,
how the region is ma
Specify region attributes before creating the region. You can do this either
through the API or
through the declarative XML file. 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`.
+creation and for modifying some attributes after creation. For details, see
the API for
+`RegionShortcut`, `RegionAttributes`, `RegionAttributesFactory`, and
`AttributesMutator`.
## <a id="region-shortcuts"></a>Region Shortcuts
<%=vars.product_name%> provides predefined, shortcut region attributes
settings for your use in `RegionShortcut`.
-
-Shortcut attributes are a convenience only. They are named attributes that
<%=vars.product_name%>
-has already stored for you. You can override their settings by storing new
attributes with the same
-`id` as the predefined attributes.
-
-### <a id="region-shortcuts_shortcut-attribute-options"></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**
+The shortcuts are:
`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.
+> does not store data in the client cache, but connects the region to the
servers.
`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.
+> stores data in the client cache and connects the region to the servers.
+
+`CACHING_PROXY_ENTRY_LRU`
+> stores data in the client cache and connects the region to the servers.
+Limits the amount of data stored locally in the client to a default limit of
100,000 entries by ejecting the least recently used (LRU) entries.
`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**
-
-Non-PROXY regions are those that store data in the client cache.
-You can add data eviction for non-PROXY regions:
-
-`ENTRY_LRU`
-> causes least recently used data to be evicted from memory when the region
reaches the entry count limit.
+`LOCAL_ENTRY_LRU`
+> stores data in the client cache and does not connect the region to the
servers. This is a client-side-only region.
+Limits the amount of data stored locally in the client to a default limit of
100,000 entries by ejecting the least recently used (LRU) entries.
diff --git a/docs/geode-native-docs/regions/regions.html.md.erb
b/docs/geode-native-docs/regions/regions.html.md.erb
index fc719c0..662b17d 100644
--- a/docs/geode-native-docs/regions/regions.html.md.erb
+++ b/docs/geode-native-docs/regions/regions.html.md.erb
@@ -144,7 +144,7 @@ Whether carried out explicitly or through expiration
activities, invalidation an
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.
+`Cache::getRegion` returns `nullptr` 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:
@@ -163,7 +163,5 @@ A region name *cannot* contain these characters:
## <a id="getting-region-size"></a>Getting the Region Size
The `Region` API provides a `size` method (`Size` property for .NET) that gets
the size of a region.
-
For client regions, this gives the number of entries in the local cache, not
on the servers.
-
See the `Region` API documentation for details.
diff --git
a/docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb
b/docs/geode-native-docs/regions/registering-interest-for-entries.html.md.erb
similarity index 100%
rename from
docs/geode-native-docs/client-cache/registering-interest-for-entries.html.md.erb
rename to
docs/geode-native-docs/regions/registering-interest-for-entries.html.md.erb
diff --git a/docs/geode-native-docs/remote-queries.html.md.erb
b/docs/geode-native-docs/remote-queries.html.md.erb
index 565eb3d..ebf8d4f 100644
--- a/docs/geode-native-docs/remote-queries.html.md.erb
+++ b/docs/geode-native-docs/remote-queries.html.md.erb
@@ -33,7 +33,6 @@ Querying and indexing operate only on remote cache server
contents.
OQL is very similar to SQL, but OQL allows you to query complex objects,
object attributes, and methods.
In the context of a query, specify the name of a region by its full path,
starting with a slash (`/`).
-The query processor performs binary numeric promotion, method invocation
conversion, and temporal type conversion.
The query language supports drilling down into nested object structures.
Nested data collections can be explicitly referenced in the FROM clause of a
query.
@@ -55,25 +54,44 @@ This section gives a general overview of the interfaces and
classes that are pro
### <a id="Query"></a>Query
-A `Query` is obtained from a `QueryService` method, which is obtained from the
cache. The `Query`
-interface provides methods for managing the compilation and execution of
queries, and for retrieving
-an existing query string.
+You must create a `Query` object for each new query. The `Query` interface
provides methods for
+managing the compilation and execution of queries, and for retrieving an
existing query string.
+
+A `Query` is obtained from a `QueryService`, which is obtained from one of two
sources:
+
+- To create a `Query` that operates on the <%=vars.product_name%> server,
start with a `QueryService` obtained from a `Pool`.
+ - For .NET, use `Apache::Geode::Client::Pool::GetQueryService()`.
+ - For C++, use ` apache::geode::client::Pool::getQueryService()`.
+
+- To create a `Query` that operates on your application's local cache, start
with a `QueryService` obtained from a `Cache`.
+ - For .NET, use `Apache::Geode::Client::Cache::GetQueryService()`.
+ - For C++, use ` apache::geode::client::Cache::getQueryService()`.
+
+[**QUESTION**] These are also available - when are they used?
+
+.NET:
+
+- Apache::Geode::Client::IRegionService::GetQueryService()
+
+C++:
+
+- apache::geode::client::RegionService::getQueryService()
+- apache::geode::client::AuthenticatedView::getQueryService()
-You must create a `Query` object for each new query.
### <a id="ExecutingAQuery"></a>Executing a Query from the Client
The essential steps to create and execute a query are:
1. Create an instance of the `QueryService` class. If you are using the pool
API (recommended), you should obtain the `QueryService` from the pool.
-1. Create a `QueryPtr` to a query (C++) or create a query instance (.NET)
that is compatible with the OQL specification.
+1. Create a `Query` instance that is compatible with the OQL specification.
1. Use the `Query.execute()` method to submit the query string to the cache
server. The server
remotely evaluates the query string and returns the results to the client.
1. Iterate through the returned objects.
### <a id="DotNetQueryExample"></a>.NET Query Example
-These C# code excerpts are from the `examples\dotnet\RemoteQueryCs` example
included in your client
+These C# code excerpts are from the `examples\dotnet\remotequery` example
included in your client
distribution. See the example for full context.
Following the steps listed above,
@@ -108,14 +126,14 @@ distribution. See the example for full context.
Following the steps listed above,
- 1. Obtain pointer to a `QueryService` object from the connection pool:
+ 1. Obtain a `QueryService` object from the connection pool:
```
std::shared_ptr<QueryService> queryService = nullptr;
queryService = pool->getQueryService();
```
- 1. Create a pointer to a `Query` object by calling
`QueryService.newQuery()`, specifying your OQL query as a string parameter:
+ 1. Create a `Query` object by calling `QueryService.newQuery()`, specifying
your OQL query as a string parameter:
```
auto query = queryService->newQuery("SELECT * FROM /custom_orders WHERE
quantity > 30");
diff --git a/docs/geode-native-docs/security/authentication.html.md.erb
b/docs/geode-native-docs/security/authentication.html.md.erb
index 2203d6d..ac774c5 100644
--- a/docs/geode-native-docs/security/authentication.html.md.erb
+++ b/docs/geode-native-docs/security/authentication.html.md.erb
@@ -27,7 +27,7 @@ this means setting the authentication credentials when you
create the CacheFacto
### .NET Authentication Example
-The following excerpt is taken from the .NET example provided with your Native
Client distribution in the `../examples/dotnet/AuthInitialize` directory.
+The following excerpt is taken from the .NET example provided with your Native
Client distribution in the `../examples/dotnet/authinitialize` directory.
In this C# authentication example, the `CacheFactory` creation process sets
the authentication callback:
diff --git a/docs/geode-native-docs/security/security.html.md.erb
b/docs/geode-native-docs/security/security.html.md.erb
index 3bbcc61..516eaaf 100644
--- a/docs/geode-native-docs/security/security.html.md.erb
+++ b/docs/geode-native-docs/security/security.html.md.erb
@@ -34,5 +34,5 @@ A Native Client application must address two security
concerns when connecting t
- **[TLS/SSL Client/Server Communication Encryption](sslclientserver.html)**
- Communication between client and server must be encrypted so
authentication credentials and other transmissions cannot be viewed by
third-parties.
+ Communication between client and server should be encrypted so
authentication credentials and other transmissions cannot be viewed by
third-parties.
diff --git a/docs/geode-native-docs/security/sslclientserver.html.md.erb
b/docs/geode-native-docs/security/sslclientserver.html.md.erb
index a84d28c..407eee1 100644
--- a/docs/geode-native-docs/security/sslclientserver.html.md.erb
+++ b/docs/geode-native-docs/security/sslclientserver.html.md.erb
@@ -20,6 +20,7 @@ limitations under the License.
-->
This section describes how to implement TLS-based communication between your
clients and servers using the OpenSSL encryption utility.
+When configuring TLS/SSL security for your client, you may find it helpful to
refer to [The SSL section of the <%=vars.product_name%> User
Guide](serverman/managing/security/ssl_overview.html).
# Set Up OpenSSL
@@ -43,12 +44,10 @@ Download and install OpenSSL 1.1.1 for your specific
operating system.
The <%=vars.product_name%> server requires keys and keystores in the Java Key
Store (JKS) format while the native client requires them in the clear PEM
format. Thus you need to be able to generate private/public keypairs in either
format and convert between the two using the `keytool` utility and the
`openssl` command.
-There are public third party free tools and source code available to download
such as the "KeyTool IUI" tool.
-
## Step 2. Configure environment variables
-Configure your system environment to build and run OpenSSL by adding the
appropriate executable and library directories to your paths.
+Configure your system environment to run OpenSSL by adding the appropriate
executable and library directories to your paths.
For example, for Bourne and Korn shells (sh, ksh, bash), environment setup
would look something like this:
<code>
%
LD\_LIBRARY\_PATH=$LD\_LIBRARY\_PATH:_client-install-dir_/lib:_client-install-dir_/ssl\_libs:_openssl-install-dir_/lib<br
/>
diff --git a/docs/geode-native-docs/transactions/transactions.html.md.erb
b/docs/geode-native-docs/transactions/transactions.html.md.erb
index fd3b6e2..f88f950 100644
--- a/docs/geode-native-docs/transactions/transactions.html.md.erb
+++ b/docs/geode-native-docs/transactions/transactions.html.md.erb
@@ -23,7 +23,7 @@ Client transactions run on the server tier. The client uses a
server delegate
that runs the transaction as it would a local transaction.
Thus, the key to running client transactions lies in making sure the server
is properly configured and programmed.
-For complete information about transactions in the Java server,
+For complete information about transactions in the <%=vars.product_name%>
server,
see the server documentation at
[Transactions](geodeman/developing/transactions/chapter_overview.html).
It provides detailed information including server data requirements,
