LATEST VERSION: 9.0.6 - CHANGELOG
Pivotal GemFire® Native Client v9.0

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 nc-dir/SampleCode/quickstart 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.

Configuring the QuickStart Environment

The following components must be in place to run the QuickStart 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.

  • Java: You must have a compatible JRE or JDK installed. See the Sun Java website 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 QuickStart 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. Follow the instructions in the README and INSTALL files to install OpenSSL on your system.

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:

    % GEMFIRE=gemfire-install-dir; export GEMFIRE
    % CLASSPATH=$GEMFIRE/lib/gemfire.jar:$GEMFIRE/lib/antlr.jar:$GEMFIRE/lib/gfSecurityImpl.jar:$CLASSPATH
    % export CLASSPATH
    % CLASSPATH=$GEMFIRE/lib/geode-dependencies.jar:$GEMFIRE/lib/antlr-2.7.7.jar:$CLASSPATH
    % export CLASSPATH

  2. Set the JAVA_HOME environment variable to point to your installed JRE or JDK. Add $JAVA_HOME/bin to the start of your PATH.

    % JAVA_HOME=installed-jre-path; export JAVA_HOME
    % PATH=$JAVA_HOME/bin:$GEMFIRE/bin:$PATH; export PATH

  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. % GFCPP=nc-dir; export GFCPP
    % LD_LIBRARY_PATH=$GFCPP/lib:${LD_LIBRARY_PATH}
    % export LD_LIBRARY_PATH

  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: % OPENSSL_ROOT_DIR=parent-folder-for-openssl-binaries
    % export OPENSSL_ROOT_DIR
    % LD_LIBRARY_PATH=$OPENSSL_ROOT_DIR/lib:${LD_LIBRARY_PATH}
    % export LD_LIBRARY_PATH

  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:

    % mkdir /home/user/build-sec
    % cd /home/user/build-sec

  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:

    % cmake ~/nc/templates/security -DGFCPP=~/nc
    ... creates a makefile and other supporting files
    % cmake --build .
    ... builds securityImpl plug-in
    % cmake --build . --target install
    ... installs securityImpl in the nc installation directory tree ($GFCPP)

  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:

    % mkdir /home/user/quickstart-examples-cpp
    % cd /home/user/quickstart-examples-cpp

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

    % cmake $GFCPP/SampleCode/quickstart/cpp
    ... creates a makefile and other supporting files
    % cmake --build .
    ... builds the examples

    This creates the examples in your working directory, plus supporting files such as the runcpp.sh shell script.

See About the QuickStart Examples for instructions on running the examples.

Configuring QuickStarts - Windows

Follow these steps to prepare your Windows environment to run the QuickStart examples.

  1. Run the Visual Studio Command Prompt to create a session with preset compiler environment configurations. Set the GEMFIRE environment variable to your GemFire installation directory. Add the %GEMFIRE%\bin directory to your PATH. Add the GemFire libraries shown here to your CLASSPATH:

    > GEMFIRE=gemfire-install-dir
    > set PATH=%GEMFIRE%\bin;%PATH%
    > set CLASSPATH=%GEMFIRE%\lib\gemfire.jar;%GEMFIRE%\lib\antlr.jar;%GEMFIRE%\lib\gfSecurityImpl.jar;%CLASSPATH%

  2. Set the JAVA_HOME environment variable to point to your installed JRE or JDK. Add %JAVA_HOME%\bin to the start of your PATH.

    > set JAVA_HOME=installed-jre-path
    > set PATH=%JAVA_HOME%\bin;%PATH%

  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%\bin to PATH. Add %GFCPP%\lib to LD_LIBRARY_PATH.

    > set GFCPP=nc-dir
    > set PATH=%GFCPP%\bin;%PATH%
    > set LD_LIBRARY_PATH=%GFCPP%\lib;%LD_LIBRARY_PATH%

  4. Set the OPENSSL_ROOT_DIR environment variable, pointing it to the parent folder for the OpenSSL binaries created from the tarball. Add %OPENSSL_ROOT_DIR%\bin to PATH and %OPENSSL_ROOT_DIR%\lib to LD_LIBRARY_PATH:

    > set OPENSSL_ROOT_DIR=c:\OpenSSL
    > set PATH=%OPENSSL_ROOT_DIR%\bin;%PATH%
    > set LD_LIBRARY_PATH=%OPENSSL%\bin;%LD_LIBRARY_PATH%

  5. Create a directory in which to build the securityImpl plug-in. This directory (shown here as c:\build-sec) should be created outside the native client directory hierarchy. After creating the directory, set it as your current working directory:

    > mkdir c:\build-sec
    > cd c:\build-sec

  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:

    > cmake c:\nc\templates\security -DGFCPP=c:\nc
    ... creates a makefile and other supporting files
    > cmake --build .
    ... builds securityImpl plug-in
    > cmake --build . --target install
    ... installs securityImpl in the nc installation directory tree ($GFCPP)

  7. Create a directory to hold the quickstart examples. This directory (shown here as c:\quickstart-examples-csharp) should be created outside the native client directory hierarchy. After creating the directory, set it as your current working directory:

    > mkdir c:\quickstart-examples-csharp
    > cd c:\quickstart-examples-csharp

  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 csharp examples):

    > cmake %GFCPP%\SampleCode\quickstart\csharp
    ... creates a makefile and other supporting files
    > cmake --build .
    ... builds the examples

    This creates the examples in your working directory, plus supporting files such as the runcs.bat script.

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

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:

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.

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.

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

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

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

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:

set GEMFIRE=full-path-to-gemfire-directory
set GFCPP=nc-dir
set JAVA_HOME=installed-jdk-path
set PATH=%PATH%;%JAVA_HOME%/bin;%GFCPP%\bin

  1. In the command shell, change to the quickstart directory:
cd SampleCode\quickstart
  1. 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