http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/install_opensource.md ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/install_opensource.md b/geode-docs/docs/geode-native-docs/introduction/install_opensource.md new file mode 100644 index 0000000..d0cdb56 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/install_opensource.md @@ -0,0 +1,22 @@ +Cmake is required to build the native client and its quickstart examples. To download and install cmake, follow the instructions on [cmake.org] (https://cmake.org). + +Installation on Mac: + +- Checkout Geode sources + +- Checkout NC branch + +- cd geode. NC sources are in 'src' subdir. + +- create build dir (e.g. build-nc) at same level as 'src'. + +- cmake config: `cmake ../src -DCMAKE_INSTALL_PREFIX=/Users/dbarnes/Repo/geode/build-nc` (if prefix not specified, will be installed to `/usr/local`) + +- cmake build: `cmake --build .` + +- cmake build: `cmake --build . --target docs` + +- cmake install: `cmake --build . --target install` + + +
http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/native-client-intro.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/native-client-intro.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/native-client-intro.html.md.erb new file mode 100644 index 0000000..3aba0c9 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/native-client-intro.html.md.erb @@ -0,0 +1,25 @@ +--- +title: Getting Started with a Native Client +--- + +This section gives you a conceptual overview of the native client. It shows you how to install the product, build native client applications on various platforms, and run the product examples. + +The native client provides access for C++ and Microsoft<sup>®</sup> .NET⢠clients to a Geode distributed system. + +- **[About the Native Client](native-client-overview.html)** + + The native client delivers the full set of capabilities supplied by Java clients communicating with a Geode server. + +- **[Installing the Native Client](install-overview.html)** + + Procedures for installing the native client will be here, once they are written. They will vary according to your operating system. + +- **[Running Native Client Applications](running-client-apps.html)** + + Set up the environment for the native client on multiple platforms. Compile and run client programs. + +- **[QuickStart Examples](quickstart.html)** + + Run the native client QuickStart examples to understand native client functionality. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/native-client-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/native-client-overview.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/native-client-overview.html.md.erb new file mode 100644 index 0000000..467aa81 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/native-client-overview.html.md.erb @@ -0,0 +1,20 @@ +--- +title: About the Native Client +--- + +The native client delivers the full set of capabilities supplied by Java clients communicating with a Geode server. + +The native client is written entirely in C++, so its initialization process does not involve the creation of a Java virtual machine. The .NET native client provides native operations for the .NET Framework application developer who writes in .NET languages and needs to access the Geode server. + +Native clients in C++, Java, and .NET languages communicate only with the cache server and do not communicate with each other. The native clients interface with the server at the sockets level and implement the same wire protocol to the server. These capabilities produce extremely high performance and system scalability. + +C++ and .NET native clients provide access to the full region API, including support for application plug-ins, managed connectivity, highly available data, and reliable failover to a specified server list. All of this is transparent to the end user. + +You can configure native clients to cache data locally, or they can act in a cacheless mode where they retrieve data from a cache server and directly pass it to other system members without incurring the caching overhead. They can be configured as read only caches, or be configured to receive notifications from the server whenever a key of interest to the client changes on the server. + +This figure diagrams how .NET and C++ applications access the cache server. <a id="concept_BCE696D352144690ADF786A0E3D2BD98__fig_C19B4B30942D4F1BA59DBDCC6146241A"></a> + + +<img src="../common/images/native-client-overview.gif" alt="Native Client Overview" id="concept_BCE696D352144690ADF786A0E3D2BD98__image_A0805B5079C64B0E8F2E9DA2A8A5A7A6" class="image" /> + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/product-examples.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/product-examples.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/product-examples.html.md.erb new file mode 100644 index 0000000..60c131c --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/product-examples.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Running the QuickStart Examples +--- + +The QuickStart examples demonstrate the capabilities of the native client, and they provide source code so you can examine how each example is designed. C++ and C\# examples demonstrate how the native client performs as a C++ or C\# client. + +Read the QuickStart Guide first (the `README.HTML` file included with the QuickStart examples) to learn more about running the QuickStart examples. + +QuickStart examples are packaged as part of the native client product download. Product examples are installed into the following directory when you install the Geode native client: + +``` pre +<native_client_installdir>/SampleCode/quickstart +``` + +where *native\_client\_installdir* is the location where you installed the Geode native client. + +**Note:** The C\# examples have a `.config` file that should not be modified or deleted. The file provides references to support files for running the example. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/quickstart.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/quickstart.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/quickstart.html.md.erb new file mode 100644 index 0000000..cc66408 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/quickstart.html.md.erb @@ -0,0 +1,570 @@ +--- +title: QuickStart Examples +--- + +The QuickStart examples demonstrate the capabilities of the native client, and they provide source +code so you can examine how each example is designed. C++ and C\# examples demonstrate how the +native client performs as a C++ or C\# client. + +The examples can be invoked individually from the command line or by using the QuickStart menu. + +The examples and their source files are located in the <code>_nc-dir_/SampleCode/quickstart</code> directory, +where *nc-dir* is the location in which you installed the native client. + +The C++ examples are in the `cpp` directory, and the C# examples are in the `csharp` directory. +Note that the C# examples are available only for Windows. + +In each example, client and server are configured either using a pair of companion XML files in the +`XMLs` directory or programatically. For example, `LoaderListenerWriter` uses +`serverLoaderListenerWriter.xml` to configure the cache server and `clientLoaderListenerWriter.xml` to +configure the client, while `BasicOperations` uses `serverBasicOperations.xml` to configure the cache +server and initialize the client programmatically. Additional support files are stored in the `lib` +directory. + +# <a id="ConfiguringQSE" class="no-quick-link"></a> Configuring the QuickStart Environment + +The following components must be in place to run the Quick Start examples on any system. System-specific configurations follow. + +**For all systems:** + +- **GemFire**: Install and configure GemFire. See the GemFire User's Guide for instructions. + +- **Cmake** is required to build the quickstart examples. If you have not already done so, download and install cmake, following the instructions on [cmake.org] (https://cmake.org). + +- **Java**: You must have a compatible JRE or JDK installed. See the [Sun Java website](http://java.sun.com) +for the latest Java version for your operating system. See the installation information in the +GemFire User's Guide for the versions of Java that are compatible with GemFire. + +- **Security Toolkit** (optional): The Quick Start security examples rely on a security plugin, `securityImpl`, which is based on the OpenSSL toolkit. +If you plan to run the security examples, download the latest version of release 1.0.1 (must be 1.0.1) from the [OpenSSL website] (http://www.openssl.org/source/). +Follow the instructions in the README and INSTALL files to install OpenSSL on your system. + +## <a id="ConfiguringQSE_Linux" class="no-quick-link"></a> Configuring QuickStarts - Linux and Solaris + +Follow these steps to prepare your Linux or Solaris environment to run the QuickStart examples. + +1. Start a terminal session. Set the `GEMFIRE` environment variable to point to your GemFire product +installation directory. Add the GemFire libraries shown here to your `CLASSPATH`: + + <code> + % GEMFIRE=_gemfire-install-dir_; export GEMFIRE <br /> + % CLASSPATH=$GEMFIRE/lib/gemfire.jar:$GEMFIRE/lib/antlr.jar:$GEMFIRE/lib/gfSecurityImpl.jar:$CLASSPATH; export CLASSPATH <br /> + % CLASSPATH=$GEMFIRE/lib/geode-dependencies.jar:$GEMFIRE/lib/antlr-2.7.7.jar:$CLASSPATH; export CLASSPATH <br /> + </code> + +2. Set the `JAVA_HOME` and `GF_JAVA_HOME` environment variables to point to your installed JRE or +JDK. The `JAVA_HOME` setting is for your applications, and `GF_JAVA_HOME` is for the GemFire +scripts. Add `$JAVA_HOME/bin` to the start of your `PATH`. + + <code> + % JAVA\_HOME=_installed-jre-path_; export JAVA\_HOME<br /> + % GF\_JAVA\_HOME=$JAVA\_HOME; export GF\_JAVA\_HOME<br /> + % PATH=$JAVA\_HOME/bin:$GEMFIRE/bin:$PATH; export PATH<br /> + </code> + +3. Set the `GFCPP` environment variable to point to the directory in which you installed the native client, denoted here by _nc-dir_. Add `$GFCPP/lib` to `LD_LIBRARY_PATH`. + <code> + % GFCPP=_nc-dir_; export GFCPP<br /> + % LD\_LIBRARY\_PATH=$GFCPP/lib:${LD\_LIBRARY\_PATH}; export LD\_LIBRARY\_PATH + </code> + +4. Set the `OPENSSL_ROOT_DIR` environment variable, pointing it to the parent folder for the OpenSSL binaries created from the tarball. Add `OPENSSL/lib` to `LD_LIBRARY_PATH`: + <code> + % OPENSSL_ROOT_DIR=_parent-folder-for-openssl-binaries_; export OPENSSL <br /> + % LD\_LIBRARY\_PATH=$OPENSSL_ROOT_DIR/lib:${LD\_LIBRARY\_PATH}; export LD\_LIBRARY\_PATH + </code> + +5. Create a directory in which to build the `securityImpl` plug-in. This directory (shown here as +`/home/user/build-sec`) should be created outside the native client directory +hierarchy. After creating the directory, set it as your current working directory: + + <code> + % mkdir /home/user/build-sec<br /> + % cd /home/user/build-sec + </code> + +6. Run `cmake` three times, once to configure the build, specifying the path to the `cmake` +instructions in the native client security template directory, a second time to perform the build, +and a third time to install the resulting library into the native client installation directory +tree: + + <code> + % cmake ~/nc/templates/security -DGFCPP=~/nc<br /> + ... creates a makefile and other supporting files<br /> + % cmake --build .<br /> + ... builds securityImpl plug-in<br /> + % cmake --build . --target install<br /> + ... installs securityImpl in the nc installation directory tree ($GFCPP) + </code> + + +7. Create a directory to hold the quickstart examples. This directory (shown here as +`/home/user/quickstart-examples`) should be created outside the native client directory +hierarchy. After creating the directory, set it as your current working directory: + + <code> + % mkdir /home/user/quickstart-examples-cpp<br /> + % cd /home/user/quickstart-examples-cpp + </code> + +8. Run `cmake` twice, once to configure the build, then again to build the examples, specifying the +path to the `cmake` instructions located in the quickstart example directory (in this case, we're building the the `cpp` examples): + + <code> + % cmake $GFCPP/SampleCode/quickstart/cpp<br /> + ... creates a makefile and other supporting files<br /> + % cmake --build .<br /> + ... builds the examples + </code> + + This creates the examples in your working directory, plus supporting files such as the `runcpp.sh` shell script. + +9. Modify permissions on the example script to make it executable: + + <code> + % chmod +x runcpp.sh + </code> + +See <a href="#AboutQSE">About the QuickStart Examples</a> for instructions on running the examples. + +## <a id="ConfiguringQSE_Windows" class="no-quick-link"></a> Configuring the QuickStart Environment - Windows + +Follow these steps to prepare your Windows environment to run the QuickStart examples. + +1. Cmake is required to build the quickstart examples. If you have not already done so, download and install cmake, following the instructions on [cmake.org] (https://cmake.org). + +2. Run the Visual Studio 2010 Command Prompt to create a session with preset compiler environment configurations. Change to the GemFire product installation directory, then configure the environment settings by following these steps. + + See the environment configuration list below for system-specific instructions for the following steps. + +2. Install OpenSSL (optional): + To enable security, the security plugin `securityImpl` needs to be compiled. The security plugin optionally depends on OpenSSL for its PKCS sample template, so OpenSSL needs to be compiled or installed first. You can get the OpenSSL installer [here](http://www.openssl.org/related/binaries.html). + + +``` +cd SampleCode/quickstart +mkdir build-cpp-quickstart +cd build-cpp-quickstart + +``` + + **To install OpenSSL:** + + Run the downloaded OpenSSL installer and accept the default installation path (C:\OpenSSL). + +3. Set the `JAVA_HOME` and `GF_JAVA_HOME` environment variables to your installed JRE or JDK. See +the installation information in the GemFire User's Guide for the versions of Java that are +compatible with GemFire. The `JAVA_HOME` setting is for your applications, and `GF_JAVA_HOME` is for the +GemFire scripts. You must have a compatible JRE or JDK installed and you must set `JAVA_HOME` and +`GF_JAVA_HOME` to point to it. See the [Sun Java website](http://java.sun.com) for the latest Java +version for your operating system. + +4. Add `$JAVA_HOME/bin` to the start of your `PATH`. + + Set the `GFCPP` environment variable to point to _nc-dir_. + + Set the `OPENSSL` environment variable. If you accept the default installation path in step 2, it will be set to `OPENSSL=C:\OpenSSL`. + +5. Set the `PATH` environment variable to point to the <code>_nc-dir_\bin</code> directory and the `%OPENSSL%\bin` directory for running the Security example. + + + + The following environment configuration list is a summary of the commands described in steps 1 through 6 that you need to run for the quickstart examples. Choose the set of commands that are appropriate for your operating system. + + + + <code> + \> cd _gemfire-install-dir_<br /> + \> set GEMFIRE=_gemfire-install-dir_<br /> + \> set CLASSPATH=%GEMFIRE%\lib\gemfire.jar;%GEMFIRE%\lib\antlr.jar;%GEMFIRE%\lib\gfSecurityImpl.jar%CLASSPATH%<br /> + \> set JAVA\_HOME=_installed-jre-path_<br /> + \> set GF\_JAVA\_HOME=%JAVA\_HOME%<br /> + \> set GFCPP=C:\NativeClient\\_nc-dir_<br /> + \> set OPENSSL=C:\OpenSSL<br /> + \> set PATH=%JAVA\_HOME%\bin;%GFCPP%\bin;%OPENSSL%\bin;%GEMFIRE%\bin;%PATH% + </code> + +7. To compile the securityImpl security plugin: + + Execute the `buildit.bat` script in the <code>_nc-dir_/templates/security</code> directory. + +8. Create a directory to hold the quickstart examples. This directory (shown here as `/home/user/quickstart-examples`) should be created outside the native client directory hierarchy. After creating the directory, set it as your current working directory: + + ``` pre + mkdir /home/user/quickstart-examples + cd /home/user/quickstart-examples + ``` + +9. Run `cmake` to build the examples, specifying the path to the quickstart example code: + + ``` pre + cmake $GFCPP/SampleCode/quickstart/cpp + ``` + + The `cmake` utility creates a Makefile and some other supporting files in your working directory. + +10. Run `make` to build the quickstart examples: + + ``` pre + make + ``` + + This creates the examples in your working directory, plus supporting files such as the `runcpp.sh` shell script. + +# <a id="AboutQSE" class="no-quick-link"></a>About the QuickStart Examples + +The examples are briefly described in this section. Each example performs the following steps: + +1. Starts the cache server with the example's server XML. + +2. Creates a GemFire cache. + +3. Performs operations specific to the example. + +4. Closes the GemFire cache. + +5. Shuts down the cache server. + +Note the messages that appear in the example's session as it runs and performs the steps in the list. + + +## Basic Operations + +The BasicOperations example puts entries (key and value pairs) into a region, gets entries from the region, invalidates an entry in the region, and destroys an entry in the region. + +The BasicOperations example uses the built-in serializable types `CacheableInt32` and +`CacheableString`. There are other built-in types which can be used for an entry. Some types can be +used as keys or values, while others can only be used as values. The types are listed in the +following table: + +**Built-In Serializable Types** + +| Cacheable Types For Keys or Values | Cacheable Types Only For Values | +|------------------------------------|---------------------------------| +| CacheableInt32 | CacheableBytes | +| CacheableString | CacheableDoubleArray | +| CacheableBoolean | CacheableFloatArray | +| CacheableByte | CacheableInt16Array | +| CacheableDouble | CacheableInt32Array | +| CacheableFloat | CacheableInt64Array | +| CacheableInt16 | CacheableStringArray | +| CacheableInt64 | CacheableObjectArray | +| CacheableWideChar | CacheableVector | +| CacheableDate | CacheableHashMap | +| CacheableFileName | CacheableHashSet | + +You can also provide your own serializable objects. Examples of custom serializable objects are +`Position` and `Portfolio` in the RemoteQuery example. For more information regarding serialization, +refer to [Serializing Data](../cpp-caching-api/serialization_overview.html) and the online API documentation for the native client. + +## Data Expiration + +The DataExpiration example is configured with an expiration action of destroy that has a 10-second timeout. It performs the following operations: + +1. Sets the `SimpleCacheListener` plugin on a region +2. Puts three entries into the region +3. Gets the entry idle timeout setting from the region +4. Counts the keys in the region before the timeout duration elapses +5. Waits for the timeout expiration action to be reported by the `SimpleCacheListener` +6. Counts the remaining keys in the region after the timeout duration elapses + +Multiple eviction action options are available, including overflow. For detailed information, see [Specifying Expiration Attributes](../client-cache/expiration-attributes.html). + + +## Loader Listener Writer + +The LoaderListenerWriter example sets the SimpleCacheLoader, SimpleCacheListener, and SimpleCacheWriter plugins on a region. These plugins report the events that occur during the following region operations: + +Put three entries into the region +Update an entry in the region +Destroy an entry in the region +Invalidate an entry in the region +Get a new entry from the region +Get the destroyed entry from the region + +## Register Interest + +The RegisterInterest example calls the interest API on a region. These are the functions that are called: + +``` pre +registerAllKeys +unregisterAllKeys +registerKeys +unregisterKeys +registerRegex +unregisterRegex +``` + +## Remote Query + +The RemoteQuery example populates some query objects on a region, executes a query that returns a +`ResultSet`, executes a query that returns a `StructSet`, and executes the region shortcut query +methods. + +## Continuous Query + +The CqQuery example demonstrate the continuous query APIs. + +## Function Execution + +The ExecuteFunctions example demonstrates the function execution APIs. + +## HA Cache + +The HA Cache example uses client and server XMLs configured to provide high availability functionality for client queues. The example calls the interest API on a region and does simple puts. + + +## Exceptions + +The Exceptions example performs some operations in incorrect ways, then logs the exceptions thrown by GemFire to demonstrate error handling. + + +## Durable Client + +The DurableClient example demonstrates durable client messaging. If the client loses its connection with a cache server, the primary server and any redundant servers maintain an event queue until the client reconnects. The queued messages are then sent to the client. This example demonstrates the following functionality: + +* Durable client properties (`durable-client-id`, `durable-timeout`) +* `readyForEvents` cache API +* Register interest APIs with the `isDurable` option +* Cache close API with the `keepalive` option +* `CacheListener` with the `afterRegionLive` API + +## Security + +The Security example demonstrates how native client credentials are authenticated when the client connects to a cache server. Authorization for client cache operations is also shown. + + +## PutAll And GetAll Operations + +The PutAllGetAllOperations example demonstrates `PutAll` and `GetAll` operations + +1. The Client is initialized programmatically rather than declaratively +2. PutAll is called with 100 entries into the region +3. GetAll is called with 100 entries from the region + +## DistributedSystem + +The DistributedSystem example demonstrates how client can connect to two distributed systems. + +1. Client creates the instance of cache. +2. Client creates two different regions in two different distributed systems. +3. Client creates basic put-get operations on those regions and closes the instance of cache. + +## PoolWithEndpoints + +This example demonstrates how client can create programatically pool with endpoints. + +1. Client creates the instance of cache. +2. Client creates poolfactory with endpoints. +3. Client creates pool using this poolfactory. +4. Client creates region with pool and does put-get operations on this region. + +## PoolRemoteQuery + +This example demonstrates how client can create a pool with a locator using XML. It then +demonstrates how it can execute a query on a region (attached with pool). + +1. Client creates the instance of cache using XML. +2. Client gets region from the cache. +3. Client puts some data in the cache. +4. Client gets `queryService` from cache and executes some queries. + +## Pool Continuous Query + +The PoolCqQuery example demonstrates the continuous query with Pool APIs. + + +## Delta Propagation + +The Delta example shows how a change in a value stored in a client can be propagated to the server. In the example, a single field of an existing value in a region is modified, and the delta for the value (which is the new value for the updated field) is propagated to the server in a put operation. + + +## Multiuser Security + +The Multiuser Security example shows per user authenticated cache usage. + + +## RefIDExample + +The RefIDExample example shows how to declaratively intialize the Region using `refid`. + + +## Transactions + +The Transactions example shows the use of the client-server transactions API. + + +## PdxRemoteQuery + +The PdxRemoteQuery example shows the use of PDX serialized objects with GemFire querying. + + +## PdxSerializer + +The PdxSerializer example shows the use of an external PDX serializer for user domain classes that aren't modified to implement the `IPdxSerializable` interface. + + +## PdxInstance + +The PdxInstance example shows the ability of clients to work with PDX serialized objects without having the actual domain classes available. + + + +# <a id="RunningQSE" class="no-quick=link"></a>Running the Examples + +You can run the quickstart examples by starting each C++ or C# example individually from the command line or by starting the examples from a menu. +The menu provides a numbered list of the example names, so you just enter the example number to start it. + +The C# examples are available only for Windows. + + +## Running an Example From the Command Line + +**C++ examples** + +**For Windows:** `runcpp ExampleName` (for example, `runcpp DataExpiration`) + +**For Linux or Solaris:** `./runcpp.sh ExampleName` (for example, `./runcpp.sh DataExpiration`) + +**C# examples** + +`runcs ExampleName` (for example, `runcs RemoteQuery`) + + +## Running a C++ Example From the Menu + +**For Windows:** + +Start the C++ menu. + +``` pre +> runcpp +Please select a GemFire C++ QuickStart example to run. + +1. BasicOperations +2. DataExpiration +3. LoaderListenerWriter +. +. +. +26.Quit + +Enter option: +``` + +Enter a number from the list to start that example. + +**For Linux or Solaris:** + +Start the C++ menu. + +``` pre +$ ./runcpp.sh +Please select a GemFire C++ QuickStart example to run. + +1. BasicOperations +2. DataExpiration +3. LoaderListenerWriter +. +. +. +26.Quit + +Enter option: +``` + +Enter a number from the list to start that example + +**Running a C# Example From the Menu** + +Start the C# menu. + +``` pre +> runcs +Please select a GemFire C# QuickStart example to run. + +1. BasicOperations +2. DataExpiration +3. LoaderListenerWriter +. +. +. +26.Quit + +Enter option: +``` + +Enter a number from the list to start that example. + + +## If you have problems running the examples + +This section discusses problems you might encounter when you run the examples, and suggests corrective actions. If your problems aren't covered or resolved here, please contact Pivotal Technical Support. For instructions, see the Pivotal page How to File a Support Request. + + +## Error Messages + +`Exception ... Region:put not connected to GemFire` + +Verify that the cache server has successfully started by reviewing the cacheserver.log file in the gfecs directory. The log may indicate why the cache server failed to start. + +`Exception ... NoClassDefFoundError` + +This error may appear in the `cacheserver.log` file in the `gfecs` directory. Verify that you have +followed all the steps in the [Configuring the QuickStart Environment section](#ConfiguringQSE). You must run the +example from the quickstart directory with the `runcpp` or `runcs` script for the `CLASSPATH` setting to +work, and so the example can find its XML files. + +`Exception ... XML file/resource does not exist or not found` + +This error might appear in the `cacheserver.log` file in the `gfecs` directory, or in the example's +screen output. Verify that you have followed all the steps in the [Configuring the QuickStart +Environment section](#ConfiguringQSE). You must run the example from the quickstart directory with the `runcpp` or `runcs` +script so the example can find its XML files. + + +## Connection Problems + +GemFire is a network-centric distributed system, so if you have a firewall running it could cause +connection problems. For example, your connections may fail if your firewall places restrictions on +inbound or outbound permissions for sockets. You may need to modify your firewall configuration to +permit traffic to applications running on your machine. The specific configuration depends on the +firewall you're using. + +If you experience port conflicts with other distributed systems, change the `localhost` and +`bridge-server` port numbers for each of the XML files in the `quickstart/XMLs` directory. If you need +to specify a non-default multicast port setting for the Java cache server, place a copy of the +GemFire `gemfire.properties` file in the `quickstart/gfecs` directory, then change the `mcast-port=` +setting to a unique value for your network. + + +# <a id="BuildingQSE" class="no-quick-link"></a>Building the Examples + +If you want to build the QuickStart examples yourself from the source files provided, follow these steps: + +1. Run the Visual Studio 2010 Command Prompt tool to open a command prompt shell. +2. In the command shell, enter the following environment configurations: + +<code> +set GEMFIRE=_full-path-to-gemfire-directory_<br /> +set GFCPP=_nc-dir_<br /> +set JAVA\_HOME=_installed-jdk-path_<br /> +set PATH=%PATH%;%JAVA\_HOME%/bin;%GFCPP%\bin<br /> +</code> + +3. In the command shell, change to the quickstart directory: + +``` pre +cd SampleCode\quickstart +``` + +4. In the command shell, run the appropriate build script for your system. The build script uses the +`quickstart_cpp_10.sln` and `quickstart_csharp_10.sln` Visual Studio solution files in the quickstart +directory. + +**For Windows:** `. buildit_10.bat` + +**For Linux and Solaris:** `./buildit.sh` + + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/running-client-apps.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/running-client-apps.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/running-client-apps.html.md.erb new file mode 100644 index 0000000..e281b75 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/running-client-apps.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Running Native Client Applications +--- + +Set up the environment for the native client on multiple platforms. Compile and run client programs. + +- **[Developing C++ Programs on Linux](developing-linux.html)** + + This section describes how to build and run a native client application on Linux. + +- **[Developing C++ Programs on Solaris](developing-solaris.html)** + + This section describes how to build and run a native client application on Solaris. + +- **[Developing C++ Programs on Windows](developing-windows.html)** + + Geode uses the Visual Studio 2010 Service Pack 1 compiler for C++ programs on Windows, which invokes Microsoft<sup>®</sup> `cl.exe` from the command line at compile time. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/runnng-client-apps.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/runnng-client-apps.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/runnng-client-apps.html.md.erb new file mode 100644 index 0000000..db40094 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/runnng-client-apps.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Running Native Client Applications +--- + +Set up the environment for the native client on multiple platforms. Compile and run client programs. + +- **[Developing C++ Programs on Linux](../../nativeclient/introduction/developing-linux.html)** + + This section describes how to build and run a native client application on Linux. + +- **[Developing C++ Programs on Solaris](../../nativeclient/introduction/developing-solaris.html)** + + This section describes how to build and run a native client application on Solaris. + +- **[Developing C++ Programs on Windows](../../nativeclient/introduction/developing-windows.html)** + + Geode uses the Visual Studio 2010 Service Pack 1 compiler for C++ programs on Windows, which invokes Microsoft<sup>®</sup> `cl.exe` from the command line at compile time. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/introduction/uninstall.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/introduction/uninstall.html.md.erb b/geode-docs/docs/geode-native-docs/introduction/uninstall.html.md.erb new file mode 100644 index 0000000..84552f0 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/introduction/uninstall.html.md.erb @@ -0,0 +1,38 @@ +--- +title: Uninstalling the Native Client +--- + +Uninstalling the native client varies based on operating system. + +## <a id="uninstall__section_D82AE460FF1D4D26896DBC21BFEAEF75" class="no-quick-link"></a>Uninstall on Linux and Solaris + +To uninstall on Linux and Solaris platforms, delete the product directory and all of its subdirectories. + +## <a id="uninstall__section_196B18FE0EC6475096B95C07FA6A18B1" class="no-quick-link"></a>Uninstall on Windows + +To uninstall on Windows platforms, use the MSI installer graphical interface, its command-line interface, or the Windows Control Panel. + +**Uninstall from MSI Installer Graphical Interface** + +1. Double-click the MSI file, then click Next in the Setup Wizard screen. +2. In the following screen, click the Remove button. +3. In the next screen, click the Remove button and then click Finish. + +**Uninstall from MSI Installer Command-Line** + +Follow this MSI command-line syntax for a quiet uninstall: + +``` pre +msiexec /q /x pivotal-gemfire-nativeclient-64bit-XXX.msi ^ +DEFAULT_INSTALLDIR=<path> +``` + +[MSI Command-Line Options](install-windows.html#install-windows__tbl-msi-options) lists common `msiexec` command-line options, along with an explanation of their usage. `msiexec/?` lists all command-line options. +The `/x` option uninstalls the product. + +**Uninstall from the Control Panel** + +1. From the Control Panel, open Add or Remove Programs. +2. Select the appropriate native client installation. +3. Click the Remove button. + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/app-ops-during-int-reg.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/app-ops-during-int-reg.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/app-ops-during-int-reg.html.md.erb new file mode 100644 index 0000000..dcf5717 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/app-ops-during-int-reg.html.md.erb @@ -0,0 +1,17 @@ +--- +title: Application Operations During Interest Registration +--- + +As soon as the client creates its regions, the application hosting the client can start cache operations, even while the client is still receiving its interest registration responses. + +In that case, application operations take precedence over interest registration responses. + +When adding register interest responses to the cache, the following rules are applied: + +- If the entry already exists in the cache with a valid value, it is not updated. +- If the entry is invalid and the register interest response is valid, the valid value is put into the cache. +- If an entry is marked destroyed, it is not updated. Destroyed entries are removed from the system after the register interest response is completed. + +If the interest response does not contain any results because all of those keys are absent from the serverâs cache, the clientâs cache can start out empty. If the queue contains old messages related to those keys, the events are still replayed in the clientâs cache. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/client-side-config.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/client-side-config.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/client-side-config.html.md.erb new file mode 100644 index 0000000..ef52830 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/client-side-config.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Client-Side Configuration +--- + +All durable messaging configurations are performed on the client. + +- **[Configuring a Durable Native Client](configuring-durable-nc.html)** + + The durable native client can be configured in the `gfcpp.properties` file, or in the `CacheFactory::set(name, value)` call. + +- **[Configuring Durable Interest in Keys](config-durable-interest-keys.html)** + + When a durable client disconnects, its servers keep queuing messages for selected keys. The client indicates which keys by registering durable interest for those keys. + +- **[Configuring Durable Client Reconnection](config-durable-reconnect.html)** + + You can configure the durable native client to obtain an approximate count of pending events upon durable client reconnection. Based on the returned number, you can determine whether to proceed and receive the pending events or to close the cache. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/config-durable-interest-keys.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/config-durable-interest-keys.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/config-durable-interest-keys.html.md.erb new file mode 100644 index 0000000..e0395e2 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/config-durable-interest-keys.html.md.erb @@ -0,0 +1,33 @@ +--- +title: Configuring Durable Interest in Keys +--- + +When a durable client disconnects, its servers keep queuing messages for selected keys. The client indicates which keys by registering durable interest for those keys. + +This fine-grained control handles the constraints of queue size and memory by saving only the critical messages. + +You still register interest for other keys, but not durable interest. When the client is connected to its servers, it receives messages for those non-durable keys. When the client is disconnected, its non-durable interest registrations are deleted but messages that are already in the queue remain there. + +For durable clients, all interest registration is done immediately after the regions are created. This is required whether interest registration is durable or not durable. An extra `registerInterest` parameter specified for durable clients indicates whether the registration is durable (true) or not (false). + +## API Client Durable Interest List Registration (C++) + +The following programmatic example registers durable interest in Key-1. The interest registration happens immediately after region creation and before anything else. + +``` pre +// Durable client interest registration can be +// durable (true) or nondurable(default). +VectorOfCacheableKey keys; +keys.push_back( CacheableString::create("Key-1") ); +regionPtr->registerKeys(keys,true); +``` + +<a id="concept_6456354A9AD945C780A5AA864B41B564__section_3DE5872B0888410EB42D52CFB28C79E5"></a> +You use the typical methods for interest registration and configure notification by subscription on the server as usual. For details, see [Registering Interest for Entries](../client-cache/registering-interest-for-entries.html#registering-interest-for-entries). + +**Note:** +Changing interest registration after the durable client connects the first time can cause data inconsistency and is not recommended. + +At restart, if the client doesn't register durable interest for exactly the same keys as before then the entries in the interest list are not copied from the server during the registration. Instead, the client cache starts out empty and entries are added during updates. If no updates come in for an entry, it never shows up in the client cache. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/config-durable-reconnect.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/config-durable-reconnect.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/config-durable-reconnect.html.md.erb new file mode 100644 index 0000000..20c2359 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/config-durable-reconnect.html.md.erb @@ -0,0 +1,42 @@ +--- +title: Configuring Durable Client Reconnection +--- + +You can configure the durable native client to obtain an approximate count of pending events upon durable client reconnection. Based on the returned number, you can determine whether to proceed and receive the pending events or to close the cache. + +Use the `getPendingEventCount` (C++ API) and the `PendingEventCount` (C\# .NET API) property to detect whether the previously registered subscription queue is available upon durable client reconnection and the count of pending events in the queue. Based on the returned results, you can then decide whether to receive the remaining events or close the cache if the number is too large. + +For example, consider this code fragment for a client with only the default pool created: + +``` pre +Pool pool = PoolManager.Find("PoolName"); +int pendingEvents = pool.PendingEventCount; +if (pendingEvents == -2) { // client connected for the first time + ⦠// continue +} else if (pendingEvents == -1) { // client reconnected but after the timeout period + ⦠// handle possible data loss +} else { // pendingEvents >= 0 + // decide to invoke readyForEvents() or Cache.close(false)/Pool.destroy() +} +``` + +For a client with multiple pools: + +``` pre +int pendingEvents = 0; +int pendingEvents1 = PoolManager.Find(âpool1â).PendingEventCount; +pendingEvents += (pendingEvents1 > 0) ? pendingEvents1 : 0; +int pendingEvents2 = PoolManager.Find(âpool2â).PendingEventCount; +pendingEvents += (pendingEvents2 > 0) ? pendingEvents2 : 0; +// process individual pool counts separately +``` + +The `getPendingEventCount` method and PendingEventCount property can return the following possible values: + +- A value representing a count of events pending at the server. Note that this count is an approximate value based on the time the durable client pool connected or reconnected to the server. Any number of invocations will return the same value. +- A zero value if there are no events pending at server for this client pool +- A negative value indicates that no queue is available at the server for the client pool. + - A value of -1 indicates that the client pool has reconnected to the server after its durable-client-timeout period has elapsed. The pool's subscription queue has been removed possibly causing data loss. + - A value of -2 indicates that this client pool has connected to server for the first time. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/configuring-durable-nc.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/configuring-durable-nc.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/configuring-durable-nc.html.md.erb new file mode 100644 index 0000000..8914be1 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/configuring-durable-nc.html.md.erb @@ -0,0 +1,36 @@ +--- +title: Configuring a Durable Native Client +--- + +The durable native client can be configured in the `gfcpp.properties` file, or in the `CacheFactory::set(name, value)` call. + +- **Durable client ID**âYou indicate that the client is durable by giving it a `durable-client-ID`. The servers use this ID to identify the client. For a non-durable client, the `durable-client-ID` is an empty string. The ID can be any number that is unique among the clients attached to servers in the same distributed system. + +- **Durable timeout**âThe `durable-timeout` setting specifies how long this clientâs servers should wait after the client disconnects before terminating its message queue. During that time, the servers consider the client alive and continue to accumulate messages for it. The default is 300 seconds. + +The `durable-timeout` setting is a tuning parameter. When setting the timeout, take into account the normal activity of your application, the average size of your messages, and the level of risk you can handle. Assuming that no messages are being removed from the queue, how long can the application run before the queue reaches the maximum message count? In addition, how long can it run before the queued messages consume all the memory on the client host? How serious is each of those failures to your operation? + +To assist with tuning, Geode provides statistics that track message queues for durable clients through the disconnect and reconnect cycles. For statistics documentation, see [Statistics](geodeman/managing/statistics/chapter_overview.html). + +When the queue is full, it blocks further operations that add messages until the queue size drops to an acceptable level. The action to take is specified on the server. For details on configuring the queue, see [Implementing Durable Client/Server Messaging](geodeman/developing/events/implementing_durable_client_server_messaging.html). + +## Configuring a Durable Native Client Using gfcpp.properties + +The following example shows `gfcpp.properties` settings to make the client durable and set the durable timeout to 200seconds. + +``` pre +durable-client-id=31 +durable-timeout=200 +``` + +## Configuring a Durable Client Through the API (C++) + +This programmatic example creates a durable client using the `CacheFactory::set(name, value)`. + +``` pre +// Create durable client's properties using the C++ api +PropertiesPtr pp = Properties::create(); +pp->insert("durable-client-id", "DurableClientId"); +pp->insert("durable-timeout", 200); +cacheFactoryPtr = CacheFactory::createCacheFactory(pp); +``` http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/configuring-nc-ha.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/configuring-nc-ha.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/configuring-nc-ha.html.md.erb new file mode 100644 index 0000000..6e55991 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/configuring-nc-ha.html.md.erb @@ -0,0 +1,49 @@ +--- +title: Configuring Native Clients for High Availability +--- + +Configure high availability by setting the pool attribute `subscription-redundancy` to the number of copies you want maintained. + +A client maintains its queue redundancy level at the time of a primary server failure by connecting to additional secondary servers. + +<a id="concept_7CEFF513CED14397A385ED88F3287AF1__section_BC1693F33FA1448296C00220962EDDEE"></a> +Native clients can specify the number of secondary servers where the client registers interest and maintains subscription channels, in addition to the subscription channel with the primary server. The secondary servers maintain redundant update queues for the client. If the primary server fails, a secondary becomes a primary to provide uninterrupted messaging to the client. If possible, another secondary is then initialized so the total number of secondaries is not reduced by the failover. + +## Setting the Server Redundancy Level in cache.xml + +This example sets one redundant server as failover backup to the primary server: + +``` pre +<cache> + <pool name="examplePool" + subscription-enabled="true" subscription-redundancy="1"> + <server host="java_servername1" port="java_port1" /> + <server host="java_servername2" port="java_port2" /> + </pool> + <region name = "ThinClientRegion1" > + <region-attributes refid="CACHING_PROXY" pool-name="examplePool"/> + </region> +</cache> +``` + +## Setting the Server Redundancy Level Programmatically + +You can set the redundancy level programmatically. This example creates a client cache with two redundant cache servers configured in addition to the primary server. + +The server redundancy level can be configured using the pool API. For more information about the pool API, see [Using Connection Pools](../connection-pools/connection-pools.html#using-connection-pools). + +``` pre +PropertiesPtr pp = Properties::create( ); +systemPtr = CacheFactory::createCacheFactory(pp); +// Create a cache. +cachePtr = systemPtr->setSubscriptionEnabled(true) + ->addServer("localhost", 24680) + ->addServer("localhost", 24681) + ->addServer("localhost", 24682) + ->setSubscriptionRedundancy(2) + ->create(); +``` + +When failover to a secondary server occurs, a new secondary is added to the redundancy set. If no new secondary server is found, the redundancy level is not satisfied but the failover procedure completes successfully. Any new live server is added as a secondary and interest is registered on it. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/disconnecting-from-server.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/disconnecting-from-server.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/disconnecting-from-server.html.md.erb new file mode 100644 index 0000000..d311e08 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/disconnecting-from-server.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Disconnecting from the Server +--- + +When a durable client closes its cache and disconnects, it tells the servers whether to maintain its queues. + +For this purpose, use the version of `Cache::close` with the boolean `keepalive` parameter set, as shown in the following example. If the setting is true, the servers keep the durable clientâs queues and durable subscriptions alive for the timeout period. In addition to in-memory queue retention, the servers can evict the most recent durable client queue updates to disk to reduce memory consumption. + +Only the resources and data related to the session are removed, such as port numbers and non-durable subscriptions. If the setting is false, the servers do the same cleanup that they would do for a nondurable client. + +## Durable Client Disconnect With Queues Maintained + +``` pre +// Close the Cache and disconnect with keepalive=true. +// Server will queue events for durable registrations and CQs +// When the client reconnects (within a timeout period) and sends +// "readyForEvents()", the server will deliver all stored events +cachePtr->close(true); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/disconnection.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/disconnection.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/disconnection.html.md.erb new file mode 100644 index 0000000..ac653ba --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/disconnection.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Disconnection +--- + +While the client and servers are disconnected, their operation varies depending on the circumstances. + +## <a id="concept_915EAD135DD942F28A38513097ACB1F1__section_6AB8F4B8993F4EF9B32A93A100F07BEC" class="no-quick-link"></a>Normal disconnect + +When a durable client disconnects normally, the `Cache.close` request states whether to maintain the client's message queue and durable subscriptions. The servers stop sending messages to the client and release its connection. See[Disconnecting From the Server](disconnecting-from-server.html#concept_3A9AC62F96FA44DBBB5CCBFD3EA19B56) for more information. + +If requested, the servers maintain the queues and durable interest list until the client reconnects or times out. The non-durable interest list is discarded. The servers continue to queue up incoming messages for entries on the durable interest list. All messages that were in the queue when the client disconnected remain in the queue, including messages for entries on the non-durable list. + +If the client requests to not have its subscriptions maintained, or if there are no durable subscriptions, the servers unregister the client and perform the same cleanup as for a non-durable client. + +## Abnormal disconnect + +If the client crashes or loses its connections to all servers, the servers automatically maintain its message queue and durable subscriptions until the client reconnects or times out. + +## Client disconnected but operational + +If the client operates while it is disconnected, it gets what data it can from the local cache. Since updates are not allowed, the data can become stale. An `UnconnectedException` occurs if an update is attempted. + +## Timing out while disconnected + +The servers track how long to keep a durable client queue alive based on the `durable-client-timeout` setting. If the client remains disconnected longer than the timeout, the servers unregister the client and do the same cleanup that is performed for a non-durable client. The servers also log an alert. When a timed-out client reconnects, the servers treat it as a new client making its initial connection. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/durable-client-life-cycle.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/durable-client-life-cycle.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-life-cycle.html.md.erb new file mode 100644 index 0000000..6994bd5 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-life-cycle.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Life Cycle of a Durable Client +--- + +This section discusses the high-level operation of a durable client through initial startup, disconnection, and reconnection. + +- **[Initial Operation](initial-operation.html)** + + The initial startup of a durable client is similar to the startup of any other client, except that it specifically calls the `Cache.readyForEvents` method when all regions and listeners on the client are ready to process messages from the server. + +- **[Disconnection](disconnection.html)** + + While the client and servers are disconnected, their operation varies depending on the circumstances. + +- **[Reconnection](reconnection.html)** + + During initialization, operations on the client cache can come from multiple sources. + +- **[Durable Message Replay](durable-message-replay.html)** + + When the primary server receives the cache ready message, the servers and client execute a procedure to update the queue and replay the events from the stored messages. + +- **[Application Operations During Interest Registration](app-ops-during-int-reg.html)** + + As soon as the client creates its regions, the application hosting the client can start cache operations, even while the client is still receiving its interest registration responses. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging-req.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging-req.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging-req.html.md.erb new file mode 100644 index 0000000..2cb9547 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging-req.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Durable Client Messaging Requirements +--- + +The messaging queues used for durable messaging are the same regular messaging queues used for basic server-to-client messaging, with additional requirements. + +See [Implementing Durable Client/Server Messaging](geodeman/developing/events/implementing_durable_client_server_messaging.html) for requirements, options, and functionality of messaging queues. If you are using highly available servers, see [High Availability for Client-Server Communication](high-availability-client-server.html#concept_F7A143F51EEA46B28AC612DEB7849D99)for additional requirements. + +For durable client messaging, you also need the following: + +- **Durable clients**. If the client is durable, the server continues to maintain the client queues when the client disconnects. + **Note:** + Redundancy management is handled by the client, so when the client is disconnected from the server the redundancy of client events is not maintained. Even if the servers fail one at a time, so that running clients have time to fail over and pick new secondary servers, an offline durable client cannot fail over. As a result, the client loses its queued messages. + +- **Durable interest registration**. A durable clientâs interest registrations specify whether its interest in a key is durable. If it is, the servers continue queuing messages for that key while the client is disconnected. +- **Reconnection conditions.** You can program the durable client to detect whether the previously registered subscription queue is available upon reconnection and determine an approximate count of pending events in the queue. Based on the results, you can then decide whether to receive the remaining events (`Cache.readyForEvents`) or close the cache if the number is too large. +- **Cache ready message**. When it is ready to receive the stored messages, a durable client must call `Cache.readyForEvents` to send a cache ready message to the server. +- **Disconnect keepalive specification**. When a durable client disconnects normally it must tell the server whether to maintain the message queue or delete it. +- **Durable client callback method**. If you use cache listeners on the durable clients, you have the option to implement the `afterRegionLive` callback method. This callback is invoked after the durable client connects to its servers, when it has received all of its stored messages and replayed the events. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging.html.md.erb new file mode 100644 index 0000000..b6a21b9 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/durable-client-messaging.html.md.erb @@ -0,0 +1,31 @@ +--- +title: Durable Client Messaging +--- + +You can configure the redundancy level for client queues that are stored on cache servers. This ensures that the client will not lose messages if it loses the connection to its primary server. + +Durable messaging allows a disconnected client application to recover its subscribed data when it reconnects to the cache server because the server continues to queue messages for which the client has registered interest. + +- **[Durable Client Messaging Requirements](durable-client-messaging-req.html)** + + The messaging queues used for durable messaging are the same regular messaging queues used for basic server-to-client messaging, with additional requirements. + +- **[Client-Side Configuration](client-side-config.html)** + +- **[Sending Cache Ready Messages to the Server](sending-cache-ready-message.html)** + + After a durable client connects and initializes its cache, regions, cache listeners, and any interest registration, it invokes `readyForEvents` to indicate to the servers that the client is ready to receive any messages accumulated for it. + +- **[Disconnecting from the Server](disconnecting-from-server.html)** + + When a durable client closes its cache and disconnects, it tells the servers whether to maintain its queues. + +- **[Life Cycle of a Durable Client](durable-client-life-cycle.html)** + + This section discusses the high-level operation of a durable client through initial startup, disconnection, and reconnection. + +- **[Implementing Cache Listeners for Durable Clients](impl-cache-listeners-durable-clients.html)** + + A cache listener for durable clients requires all callback methods to behave properly when stored events are replayed. A cache listener has a callback method, `afterRegionLive`, specifically for durable clients aspects. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/durable-message-replay.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/durable-message-replay.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/durable-message-replay.html.md.erb new file mode 100644 index 0000000..c4274ca --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/durable-message-replay.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Durable Message Replay +--- + +When the primary server receives the cache ready message, the servers and client execute a procedure to update the queue and replay the events from the stored messages. + +Durable message replay proceeds as follows. To avoid overwriting current entries with old data, the client does not apply the updates to its cache. + +1. The server finds the queue for this durable client ID and updates its information, including the clientâs socket and remote ports. + + If the client has timed out while it was disconnected, its queues are gone and the server then treats it as a new client. See [Initial Operation](initial-operation.html). + +2. All servers that have a queue for this client place a marker in the queue. + + Messages in the queue before the marker are considered to have come while the client was disconnected. Messages after the marker are handled normally. + +3. The cache server sends the queued messages to the client. This includes any messages that were evicted to disk. +4. The client receives the messages but does not apply the updates to its cache. If cache listeners are installed, they handle the events. For implications, see [Implementing Cache Listeners for Durable Clients](impl-cache-listeners-durable-clients.html#concept_3BD651087FC4470C8BAB6AFD97AEA689). +5. The client receives the marker message indicating that all past events have been played back. +6. The cache server sends the current list of live regions. +7. In each live region on the client, the marker event triggers the `afterRegionLive` callback. + + After the callback, the client begins normal processing of events from the server and applies the updates to its cache. + +Even when a new client starts up for the first time, the cache ready markers are inserted in the queues. If messages start coming into the new queues before the servers insert the marker, those messages are considered as having happened while the client was disconnected, and their events are replayed the same as in the reconnect case. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/high-availability-client-server.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/high-availability-client-server.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/high-availability-client-server.html.md.erb new file mode 100644 index 0000000..e69ce8d --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/high-availability-client-server.html.md.erb @@ -0,0 +1,18 @@ +--- +title: High Availability for Client-Server Communication +--- + +The Geode native client provides reliable event messaging from cache server to client to prevent data loss during server failover operations. High availability is implemented in the cache server and is configured in the native client. + +See [Configuring Highly Available Servers](geodeman/developing/events/configuring_highly_available_servers.html) for details about configuring a Java cache server for high availability. + +**Note:** +High availability functions the same whether the region is partitioned or not. See [Partitioned Regions](geodeman/developing/partitioned_regions/chapter_overview.html) for information about partitioned regions. + +- **[Configuring Native Clients for High Availability](configuring-nc-ha.html)** + + Configure high availability by setting the pool attribute `subscription-redundancy` to the number of copies you want maintained. + +- **[Sending Periodic Acknowledgment](sending-periodic-ack.html)** + + Servers use periodic acknowledgment to reduce the likelihood of duplicate notifications, and to reduce resource usage. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/impl-cache-listeners-durable-clients.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/impl-cache-listeners-durable-clients.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/impl-cache-listeners-durable-clients.html.md.erb new file mode 100644 index 0000000..283d3fd --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/impl-cache-listeners-durable-clients.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Implementing Cache Listeners for Durable Clients +--- + +A cache listener for durable clients requires all callback methods to behave properly when stored events are replayed. A cache listener has a callback method, `afterRegionLive`, specifically for durable clients aspects. + +For general instructions on implementing a cache listener, see [CacheListener](../client-cache/application-plugins.html#application-plugins__section_3F43B898CD254076B4DD777E9B4CC8F0). + +## <a id="concept_3BD651087FC4470C8BAB6AFD97AEA689__section_EC28F9769A554CA28B0E9D2F924BA4C3" class="no-quick-link"></a>Writing Callbacks for Use With Durable Messaging + +Durable clients require special attention to cache callbacks generated by the cache listener. During the initialization window when a reconnecting client has a functioning cache but is still receiving the stored messages from the queue, the client can replay events that are long past. These events are not applied to the cache, but they are sent to the cache listener. If the listenerâs callbacks invoked by these events make changes to the cache, that could conflict with current operations and create data inconsistencies. + +Consequently, you need to keep your callback implementations lightweight and not do anything in the cache that could produce incorrect results during this window. For details on implementing callbacks for Geode event handlers, see [Implementing Cache Event Handlers](geodeman/developing/events/implementing_cache_event_handlers.html). + +## <a id="concept_3BD651087FC4470C8BAB6AFD97AEA689__section_F39E695D88E94D518F3E1778F37FAF11" class="no-quick-link"></a>Implementing the afterRegionLive Method + +If you are using cache listeners, you can implement the `afterRegionLive` callback method provided for durable clients. This callback is invoked when the client has received all the old messages that were stored in its queue while it was disconnected. Implementing this method enables you to do application-specific operations when the client has replayed all of these old events. + +If you do not wish to use this callback, and your listener is an instance of `CacheListener` (not a `CacheListenerAdapter`), you must implement `afterRegionLive` as a non-operational method. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/initial-operation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/initial-operation.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/initial-operation.html.md.erb new file mode 100644 index 0000000..c77d218 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/initial-operation.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Initial Operation +--- + +The initial startup of a durable client is similar to the startup of any other client, except that it specifically calls the `Cache.readyForEvents` method when all regions and listeners on the client are ready to process messages from the server. + +See [Sending the Cache Ready Message to the Server](sending-cache-ready-message.html#concept_C28D015FA85B4EE4B2F8D2DA5FCAFBFF). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/preserving-data.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/preserving-data.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/preserving-data.html.md.erb new file mode 100644 index 0000000..c92410a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/preserving-data.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Preserving Data +--- + +A server may preserve the data queued and intended to be sent to a native client, such that the data is not discarded if communication between the server and native client is disrupted. Preservation prevents message loss, which can cause a native client to have inconsistent data. Redundant queues and a high availability server implementation may further ensure that queued data is not lost. + +There is a tradeoff between the quantity of data that a server must queue and the amount of time that the server maintains and continues to queue data intended for a native client that is not communicating with the distributed system. Client configuration specifies the amount of time that the server is to continue queueing messages. High availability permits a secondary server to assume the role of a primary server with respect to queued data in the event that the primary server no longer functions. Designation of primary and secondary servers, as well as the number of redundant copies of the queue are configurable. + +- **[High Availability for Client-Server Communication](high-availability-client-server.html)** + + The Geode native client provides reliable event messaging from cache server to client to prevent data loss during server failover operations. High availability is implemented in the cache server and is configured in the native client. + +- **[Enabling Queue Conflation to Improve Update Performance](using-queue-conflation.html)** + + Conflation of entry update messages can reduce the number of update messages a native client receives, thereby increasing performance. The native client receives only the most recent update for a particular entry key. + +- **[Durable Client Messaging](durable-client-messaging.html)** + + You can configure the redundancy level for client queues that are stored on cache servers. This ensures that the client will not lose messages if it loses the connection to its primary server. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/reconnection.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/reconnection.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/reconnection.html.md.erb new file mode 100644 index 0000000..a31f721 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/reconnection.html.md.erb @@ -0,0 +1,32 @@ +--- +title: Reconnection +--- + +During initialization, operations on the client cache can come from multiple sources. + +- Cache operations by the application. +- Results returned by the cache server in response to the clientâs interest registrations. +- Callbacks triggered by replaying old events from the queue. + +These procedures can act on the cache concurrently, and the cache is never blocked from doing operations. + +Geode handles the conflicts between the application and interest registration, but you need to prevent the callback problem. Writing callback methods that do cache operations is never recommended, but it is a particularly bad idea for durable clients, as explained in [Implementing Cache Listeners for Durable Clients](impl-cache-listeners-durable-clients.html). + +Program the durable client to perform these steps, in order, when it reconnects: + +1. Create the cache and regions. This ensures that all cache listeners are ready. At this point, the application hosting the client can begin cache operations. +2. Issue its register interest requests. This allows the client cache to be populated with the initial interest registration results. The primary server responds with the current state of those entries if they still exist in the serverâs cache. +3. Call `Cache.readyForEvents`. This tells the servers that all regions and listeners on the client are now ready to process messages from the servers. The cache ready message triggers the queued message replay process on the primary server. + +For an example that demonstrates `Cache.readyForEvents`, see [Sending the Cache Ready Message to the Server](sending-cache-ready-message.html#concept_C28D015FA85B4EE4B2F8D2DA5FCAFBFF). + +This figure shows the concurrent procedures that occur during the initialization process. The application begins operations immediately on the client (step 1), while the client's cache ready message (also step 1) triggers a series of queue operations on the cache servers (starting with step 2 on the primary server). At the same time, the client registers interest (step 2 on the client) and receives a response from the server. + +Message B2 applies to an entry in Region A, so the cache listener handles B2's event. Because B2 comes before the marker, the client does not apply the update to the cache. + +<a id="concept_38C027837216434CB5DEC84DF56B807E__fig_5A5566FB9EBE4A6D906E9D8FA687B4C5"></a> +<span class="figtitleprefix">Figure: </span> Initialization of a Reconnected Durable Client + +<img src="../common/images/7-Preserving_Data-2.gif" id="concept_38C027837216434CB5DEC84DF56B807E__image_1B3693DB90D041F193496BA24849D114" class="image" /> + +Only one region is shown for simplicity, but the messages in the queue could apply to multiple regions. Also, the figure omits the concurrent cache updates on the servers, which would normally be adding more messages to the client's message queue. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/sending-cache-ready-message.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/sending-cache-ready-message.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/sending-cache-ready-message.html.md.erb new file mode 100644 index 0000000..ed3355a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/sending-cache-ready-message.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Sending Cache Ready Messages to the Server +--- + +After a durable client connects and initializes its cache, regions, cache listeners, and any interest registration, it invokes `readyForEvents` to indicate to the servers that the client is ready to receive any messages accumulated for it. + +## Durable Client Cache Ready Notification (C++) + +The following example shows how to call `readyForEvents`. + +``` pre +//Send ready for event message to server(only for durable clients). +//Server will send queued events to client after receiving this. +cachePtr->readyForEvents(); +``` + +To keep the client from losing events, do not call this method until all regions and listeners are created. For more information, see [Reconnection](reconnection.html#concept_38C027837216434CB5DEC84DF56B807E). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/sending-periodic-ack.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/sending-periodic-ack.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/sending-periodic-ack.html.md.erb new file mode 100644 index 0000000..2b33ab0 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/sending-periodic-ack.html.md.erb @@ -0,0 +1,31 @@ +--- +title: Sending Periodic Acknowledgment +--- + +Servers use periodic acknowledgment to reduce the likelihood of duplicate notifications, and to reduce resource usage. + +<a id="concept_868B8082463846DE9F35BBEA56105C82__section_D4375BCCF8A2426BA58073B9549B6F04"></a> +When redundancy is enabled for high availability and `redundancy-level` is set to 1 or higher, clients send (and servers expect) periodic acknowledgment messages at configurable intervals for notifications they have received. A periodic ack is not sent by the client if there are no unacknowledged notifications at the time. + +Use the following system properties in the `gfcpp.properties` file to configure periodic ack. + +<table> +<colgroup> +<col width="50%" /> +<col width="50%" /> +</colgroup> +<tbody> +<tr class="odd"> +<td><code class="ph codeph">notify-ack-interval</code></td> +<td><p>Minimum period between two consecutive acknowledgment messages sent from the client to the server. The default setting (in seconds) is 10.</p></td> +</tr> +<tr class="even"> +<td><code class="ph codeph">notify-dupcheck-life</code></td> +<td><p>Minimum time a client continues to track a notification source for duplicates when no new notifications arrive before expiring it. The default setting (in seconds) is 300.</p></td> +</tr> +</tbody> +</table> + +The Pool API also provides attributes to configure periodic ack and duplicate message tracking timeout. See `subscription-message-tracking-timeout` and `subscription-ack-interval` in the list of pool attributes under [Configuring Pools for Servers or Locators](../connection-pools/configuring-pools.html#configuring-pools). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/preserving-data/using-queue-conflation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/preserving-data/using-queue-conflation.html.md.erb b/geode-docs/docs/geode-native-docs/preserving-data/using-queue-conflation.html.md.erb new file mode 100644 index 0000000..f7e5f4f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/preserving-data/using-queue-conflation.html.md.erb @@ -0,0 +1,23 @@ +--- +title: Enabling Queue Conflation to Improve Update Performance +--- + +Conflation of entry update messages can reduce the number of update messages a native client receives, thereby increasing performance. The native client receives only the most recent update for a particular entry key. + +Conflation is enabled for a cache server region, so all clients receiving updates for a particular region benefit from the conflation. To enable conflation, set the cache serverâs `enable-subscription-conflation` region attribute to `true`. This region attribute is `false` by default. + +The queue managment code conflates entry updates as part of the enqueue operation. If the previous enqueued item for that key is also an `update` operation, the queue management code removes that previously enqueued update, leaving only the latest update to be sent when event distribution occurs. For high availability, conflation also occurs for any secondary queues. + +Only entry `update` messages in a cache server region with `distributed-no-ack` scope are conflated. Region operations and entry operations other than updates are not conflated. + +For more information, see [Conflate the Server Subscription Queue](geodeman/developing/events/conflate_server_subscription_queue.html). + +## <a id="concept_AEFA04AF9ABD42C0A37ED31806596D24__section_BE506A32A8E44073B197B03AC5232C01" class="no-quick-link"></a>Overriding Queue Conflation Per-Client + +Override conflation on a per-client basis by setting the conflate-events property in the native clientâs `gfcpp.properties` file. + +Valid settings are: + +- `server`. Uses the server settings. +- `true`. Conflates everything sent to the client. +- `false`. Does not conflate anything sent to the client. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/programming-examples/cpp-example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/programming-examples/cpp-example.html.md.erb b/geode-docs/docs/geode-native-docs/programming-examples/cpp-example.html.md.erb new file mode 100644 index 0000000..697cfa3 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/programming-examples/cpp-example.html.md.erb @@ -0,0 +1,33 @@ +--- +title: API Programming Example â C++ +--- + +The next example uses the C++ API to implement a cache loader, which is generally used to retrieve data from an outside source. + +``` pre +CacheablePtr TestCacheLoader::load(const RegionPtr& region, + const CacheableKeyPtr& key, + const UserDataPtr& aCallbackArgument) +{ + m_bInvoked = true; + printf("CacheLoader.load : %s\n", printEvent(region, key, + aCallbackArgument).c_str()); + CacheablePtr value = NULLPTR; + try { + value = region->get(key, aCallbackArgument); + } catch(Exception& ex) { + fprintf(stderr, "Exception in TestCacheCallback::printEvent [%s]\n", ex.getMessage()); + } + if (value != NULLPTR) { + printf( "Loader found value: "); + std::string formatValue = printEntryValue(value); + printf( "%s\n",formatValue.c_str()); + } else { + printf( " Loader did not find a value"); + } + + return value; +} +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/programming-examples/csharp-example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/programming-examples/csharp-example.html.md.erb b/geode-docs/docs/geode-native-docs/programming-examples/csharp-example.html.md.erb new file mode 100644 index 0000000..9221f91 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/programming-examples/csharp-example.html.md.erb @@ -0,0 +1,85 @@ +--- +title: API Programming Example â C# +--- + +This C\# programming code in the next example demonstrates how to use two or more clients sharing a distributed region in a Geode cache. + +``` pre +using System; +using GemStone.GemFire.Cache; + +namespace GemStone.GemFire.Cache.QuickStart { + // The BasicOperations QuickStart example. + class BasicOperations { + static void Main(string[] args) { + try { + // Create a Cache. + CacheFactory cacheFactory = CacheFactory.CreateCacheFactory(null); + + Cache cache = cacheFactory.SetSubscriptionEnabled(true).Create(); + + Console.WriteLine("Created the Cache"); + + RegionFactory regionFactory = + cache.CreateRegionFactory(RegionShortcut.CACHING_PROXY); + + Region region = regionFactory.Create("exampleRegion"); + + Console.WriteLine("Created the Region Programmatically."); + + // Put an Entry (Key and Value pair) into the Region using the + // direct/shortcut method. + region.Put("Key1", "Value1"); + + Console.WriteLine("Put the first Entry into the Region"); + + // Put an Entry into the Region by manually creating a Key and + // a Value pair. + CacheableInt32 key = new CacheableInt32(123); + CacheableString value = new CacheableString("123"); + region.Put(key, value); + + Console.WriteLine("Put the second Entry into the Region"); + + if (IntPtr.Size == 8) { // Are we a 64 bit process? + Char ch = 'A'; + string text = new string(ch, 1024 * 1024); + for (int item = 0; item < (5 * 1024 /* 5 GB */); item++) { + region.LocalPut(item, text); + } + Console.WriteLine("Put over 4 GB data locally"); + } + // Get Entries back out of the Region. + IGFSerializable result1 = region.Get("Key1"); + + Console.WriteLine("Obtained the first Entry from the Region"); + + IGFSerializable result2 = region.Get(key); + + Console.WriteLine("Obtained the second Entry from the Region"); + + // Invalidate an Entry in the Region. + region.Invalidate("Key1"); + + Console.WriteLine("Invalidated the first Entry in the Region"); + + // Destroy an Entry in the Region. + region.Destroy(key); + + Console.WriteLine("Destroyed the second Entry in the Region"); + + // Close the GemFire Cache. + cache.Close(); + + Console.WriteLine("Closed the Cache"); + } + // An exception should not occur + catch (GemFireException gfex) { + Console.WriteLine("BasicOperations Exception: {0}", + gfex.Message); + } + } +} +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/programming-examples/native-client-region.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/programming-examples/native-client-region.html.md.erb b/geode-docs/docs/geode-native-docs/programming-examples/native-client-region.html.md.erb new file mode 100644 index 0000000..6e15afd --- /dev/null +++ b/geode-docs/docs/geode-native-docs/programming-examples/native-client-region.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Declaring a Native Client Region +--- + +The following example shows how to declare a native client region in a `cache.xml` file. + +``` pre +<cache> + <region name = "root1" > + <region-attributes refid="CACHING_PROXY" pool-name="poolName1"/> + </region> + <region name = "root2" > + <region-attributes refid="PROXY" pool-name="poolName2"/> + </region> + <pool name="poolName1" subscription-enabled="true"> + <server host="localhost" port="40404" /> + </pool> + <pool name="poolName2" subscription-enabled="true"> + <server host="localhost" port="40404" /> + </pool> +</cache> +``` + +- The pool defines a list of cache servers that the native client region can communicate with. +- The *CACHING\_PROXY* setting causes the client region to cache data and to communicate with the servers. The *PROXY* setting causes the client region to communicate with the servers, but cache no data. +- The region *subscription-enabled* property, if `true` , indicates that the client should receive data updates when server data changes. +- Native clients do not specify cache loaders or writers, which are provided by the server. + +
