QuickStart Examples

The QuickStart examples demonstrate the capabilities of the client, and they provide source code so you can examine how each example is designed. C++ and C# examples demonstrate how the 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 gc-dir/SampleCode/quickstart directory, where gc-dir is the location in which you installed the 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.

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. Set the GEODE environment variable to point to the same location:

   % export GEMFIRE=gemfire-install-dir
% export GEODE=$GEMFIRE

2. Set the JAVA_HOME environment variable to point to your installed JRE or JDK. Set the GFCPP environment variable to point to the directory in which you installed the native client, denoted here by nc-dir:

   % export JAVA_HOME=installed-jre-path
% export GFCPP=nc-dir

3. Add $GEMFIRE/bin,$JAVA_HOME/bin, and $GFCPP/bin to the start of your PATH:

   % export PATH=$GEMFIRE/bin:$JAVA_HOME/bin:$GFCPP/bin:$PATH


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

5. Run cmake twice, once to configure the build, then again to build the examples. On the first cmake command line, which configures the build environment, specify the path to the cmake instructions located in the quickstart example directory (in this case, we’re building the cpp examples), and specify pivotal-gemfire as the PRODUCT_LIB_NAME:

   % cmake -DPRODUCT_LIB_NAME=pivotal-gemfire $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 Running the 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 point to your GemFire product installation directory. Set the GEODE environment variable to point to the same location.

   > set GEMFIRE=gemfire-install-dir
> set GEODE=%GEMFIRE%


2. Set the JAVA_HOME environment variable to point to your installed JRE or JDK: Set the GFCPP environment variable to point to the directory in which you installed the native client, denoted here by nc-dir.

   > set JAVA_HOME=installed-jre-path
> set GFCPP=nc-dir


3. Add %GEMFIRE%\bin, %JAVA_HOME%\bin, and %GFCPP%\bin to the start of your PATH:

   > set PATH=%GEMFIRE%\bin;%JAVA_HOME%\bin;%GFCPP%\bin;%PATH%

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

5. Run cmake twice, once to configure the build, then again to build the examples. On the first cmake command line, which configures the build environment, specify the path to the cmake instructions located in the quickstart example directory. For the Windows environment, you should also specify the cmake generator, -G "Visual Studio 12 2013 Win64" in the configuration step, and --config Release in the build command.

   > cmake -G "Visual Studio 12 2013 Win64" -DPRODUCT_DLL_NAME=Pivotal.Gemfire %GFCPP%\SampleCode\quickstart\csharp
... creates a makefile and other supporting files
> cmake --build . --config Release
... builds the examples

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

   For C++ quickstarts, use “cpp” and “PRODUCT_LIB_NAME=pivotal-gemfire” and point to the cpp quickstart directory:

   > cmake -G "Visual Studio 12 2013 Win64" -DPRODUCT_LIB_NAME=pivotal-gemfire %GFCPP%\SampleCode\quickstart\cpp
... creates a makefile and other supporting files
> cmake --build . --config Release
... builds the examples

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

See Running the Examples for instructions on running the examples.

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

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

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.

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