cacheRunner

GemFire Enterprise Native Client

C++ Programming Example

September 2007

The cacheRunner C++ example is an interactive program for modifying and viewing GemFire Enterprise cache contents as a C++ native client interacts with a GemFire cache server. The cacheRunner program joins the distributed system, creates a cache, and then accepts command-line input for inspecting, modifying, and remotely querying the cache while working with a cache server. XML files are provided to configure cacheRunner for different functional operations or behavior.

You can review the C++ source code for this example by opening the files in the cacheRunner directory that have .cpp and .hpp file extensions.

This example is divided into three parts, with each part requiring different sets of configuration files for both cacheRunner and the cache server. The cacheRunner example can also be configured using a local gfcpp.properties file.

• Part 1: Inspecting and Modifying the Cache uses cacheRunner to look at GemFire regions, entries, directories, and files to get a feel for how the product works.


• Part 2: Remote Querying demonstrates how to perform remote querying of cache entries stored on a Java cache server. If you want to go directly to this part, then click here.


• Part 3: High Availability shows how you can set up redundant cache servers to ensure highly available data in case the primary cache server fails. If you want to go directly to this part, then click here.

The cacheRunner C++ example is located in the GemFire Enterprise Native Client installation under
GemFireInstallDirectory/native_client/examples/cacheRunner.

The instructions in this example apply to the Windows operating system. Alter them as needed for your particular operating system.

---

Part 1: Inspecting and Modifying the Cache

---

Running cacheRunner

The cacheRunner example uses a GemFire Java cache server configuration file, cacherunner.xml. When the Java cache server starts, cacherunner.xml creates a root region and two regions on the server named listenerWriterLoader and sub1. This is a description of each cache server region and how each region is configured:

• root — The root region for the cache server, local in scope and populated with an entry named entry3 that has a value of 3.0
• listenerWriterLoader — A region with distributed scope, populated with an entry named entry1 that has a value of 1.0
• sub1 — A region with local scope

The cacheRunner application comes with a set of XML configuration files that configure its local cache and demonstrate various operations with the cache server. The following XML files are used with this example. The application must be run separately for each of these XML files:

• tcr_cache.xml — Establishes local and distributed cache operations.
• tcr_cacheless.xml — Data is retrieved from the cache server but not retained in the local cache.
• csQueryPortfolios.xml — Used with the querying examples; creates a subregion named Portfolios, which is a region of stock portfolios whose keys are the portfolio ID.
• tcr_hacache.xml — Establishes cache server redundancy to demonstrate high availability if server failover occurs.

These procedures introduce a few of the cacheRunner commands. For information on the others, enter help or ? at the session prompt. In the procedures, the lines you type are shown in a boldface fixed font. System output is shown in a regular fixed font.

Configuring the Environment

Examples that interact with a Java cache server require specific environment configurations so the Java cache server will run properly. Follow the configuration steps listed below that apply to your operating system:

1. From the GemFire product installation directory, run the appropriate bin/setenv script for your system. Refer to the system configuration information in the GemFire Enterprise Developer's Guide if you need help with this step.
   
   
2. Set the JAVA_HOME and GF_JAVA_HOME environment variables to your installed Java JRE or JDK. See the installation information in the GemFire Enterprise System Administrator's Guide for the versions of Java that are compatible with GemFire Enterprise. The JAVA_HOME setting is for your applications, and GF_JAVA_HOME is for the GemFire scripts. Some downloads of GemFire include a JRE in the jre directory of the installation. If you have a $GEMFIRE/jre directory, the GemFire scripts will automatically use it and you could also use it for your JAVA_HOME setting. If you have no $GEMFIRE/jre directory (such as the .zip file download of the product), then you must have a compatible Java JRE or JDK installed and you must set JAVA_HOME and GF_JAVA_HOME to point to it.
   
   
3. Add $JAVA_HOME/bin to the start of your PATH.
   

The following is a list of the environment configuration commands for the cacheRunner example. Choose the set of commands that are appropriate for your operating system. The text that you type is shown in bold. These configurations only need to be performed for the sessions that invoke the Java cache server.

Bourne and Korn shells (sh, ksh, bash)

% cd GemFireInstallDirectory
% . bin/setenv.sh
% JAVA_HOME=$GEMFIRE/jre;export JAVA_HOME
% GF_JAVA_HOME=$GEMFIRE/jre;export GF_JAVA_HOME
% PATH=$JAVA_HOME/bin:$PATH;export PATH

C shells (csh, tcsh)

% cd GemFireInstallDirectory
% source bin/setenv.csh
% setenv JAVA_HOME $GEMFIRE/jre
% setenv GF_JAVA_HOME $GEMFIRE/jre
% setenv PATH $JAVA_HOME/bin;${PATH}

Windows

> cd GemFireInstallDirectory
> bin\setenv.bat
> set JAVA_HOME=%GEMFIRE%\jre
> set GF_JAVA_HOME=%GEMFIRE%\jre
> set PATH=%JAVA_HOME%\bin;%PATH%

Starting the Cache Server

To start the cache server, create a session and complete the following steps:

1. Configure the session environment according to the steps listed in Configuring the Environment.

2. Go to the cacheRunner directory, then start the cache server:

   cd native_client/examples/cacheRunner

   cacheserver start cache-xml-file=cacherunner.xml

   The cache server is initialized using the region settings in the cacherunner.xml file in the cacheRunner directory. A message similar to the following appears, indicating that the cache server is running:

Cacheserver pid: 2120 status: running

Starting the CacheRunner Example

Follow these steps to start the cacheRunner example using the tcr_cache.xml initialization file:

1. Create two cacheRunner sessions.

2. Go to the cacheRunner directory in both sessions:

cd native_client/examples/cacheRunner

3. Start the cacheRunner application in both sessions, specifying tcr_cache.xml:

   cacherunner.exe tcr_cache.xml

   The cacheRunner client is initialized using the region settings in the tcr_cache.xml file in the cacheRunner directory. The application creates a root region and subregions, then the /root region prompt appears. As you move from region to region, the prompt includes a path to tell you where you are, such as /root/listenerWriterLoader>.

4. Set one of the two cacheRunner sessions aside. You only need one client session for the following two Producing Data exercises.

5. In the cacheRunner client, check the contents of the root region:

   ls
Region Entries:

Subregions:
     listenerWriterLoader <Endpoint:localhost:50505, Client Notification:true>
     Portfolios (Endpoint:localhost:50505, Client Notification:true)
/root>

   The endpoint and client notification status displays for the listenerWriterLoader and Portfolios regions. To communicate with a cache server, the endpoint value for the client region must be the same as the port number defined for the cache server.

   
   

Producing Data in the root Region

In this first exercise you produce data in the root region of the cacheRunner local client cache.

In the cacherunner client:

1. Add an entry to the root region:

   put entry1 ball str

   This line creates an entry whose key is entry1 and whose value is the string ball.

2. Check the contents to see the new entry:

   ls
Region Entries:
entry1 -> String: ball

3. Invalidate the new entry in the local cache and then check the contents:

   inv -l entry1
ls
Region Entries:
entry1 -> No value in cache.

   The value for the entry has been removed from the local cache.

4. Now try to get the entry from the cache server:

   get entry1
entry1 -> No value in cache.

   The entry cannot be retrieved from the cache server because the client root cache does not have an endpoint established with the cache server, so it did not propagate the entry to the server.

Producing Data in a Distributed Region

In this exercise you produce data in a local region that is distributed to the cache server.

In the cacherunner client:

1. Go to the listenerWriterLoader region, then check the contents:

chrgn listenerWriterLoader
ls
Region Entries:
Subregions:

There are no entries in the local client cache for the listenerWriterLoader region. However, remember that the listenerWriterLoader region on the cache server was initialized with an entry named entry1 that has a value of 1.0.

2. Retrieve entry1 from the cache server:

   get entry1
entry1 -> String: 1.0

3. Create a new entry in the local cache, then check the cache contents:

   put entry2 bat str
ls
Region Entries:
entry2 -> String: bat
entry1 -> String: 1.0

4. Invalidate entry2 in the local cache and then check the contents:

   inv -l entry2
ls
Region Entries:
entry2 -> No value in cache.
entry1 -> String: 1.0

5. Now get entry2 from the cache server and then check the contents:

   get entry2
ls
Region Entries:
entry2 -> String: bat
entry1 -> String: 1.0

   The entry in the local cache is updated with the value stored in the cache server.

6. Keep the cacheRunner application and the cache server running for the next exercise.

Registering Interest Using Regular Expressions

In this exercise you learn how client regions can register interest in cache server entry keys through the use of regular expressions. By registering interest, a client region receives update notifications from the cache server for the keys of interest whose strings match the expression. Regular expressions only work with string keys.

In the first cacherunner client:

1. Make sure that the cacheRunner client session you used in the previous exercises is still set to the listenerWriterLoader region. If it isn't, then set it to that region:

chrgn listenerWriterLoader

2. Put some entries in the region:

   put key-1 val1
put key-2 val2
put key-3 val3
put key-4 val4

In the second cacherunner client:

1. Display the second cacheRunner client session that you created at the start of this example, then go to its listenerWriterLoader region:

   chrgn listenerWriterLoader

2. Retrieve the four entries that were put in the first client:

   get key-1
key-1 -> Bytes: val1
get key-2
key-2 -> Bytes: val2
get key-3
key-3 -> Bytes: val3
get key-4
key-4 -> Bytes: val4

3. Register interest using a regular expression:

   regex key-[2-3]

   This registers interest in key-2 and key-3. Remember that registering interest with regular expressions only works with string keys.

In the first client:

Update key-2 and key-3:

put key-2 newVal2
put key-3 newVal3

In the second client:

1. Check the contents of the region:

ls
Region Entries:
key-3 -> Bytes: newVal3
key-1 -> Bytes: val1
key-4 -> Bytes: val4
key-2 -> Bytes: newVal2

The updated values for key-2 and key-3 are listed.

2. Unregister interest for key-2 and key-3 regular expressions:

   unregex key-[2-3]

In the first client:

Update key-2 and key-3:

put key-2 123
put key-3 456

In the second client:

Check the contents of the region:

ls
Region Entries:
key-3 -> Bytes: newVal3
key-1 -> Bytes: val1
key-4 -> Bytes: val4
key-2 -> Bytes: newVal2

The old values for key-2 and key-3 are listed because no interest is registered for them, so no update notifications were received from the cache server.

Keep both cacheRunner applications and the cache server running for the next exercise.

Adding a Cache Listener to an Existing Region

In this exercise you add a cache listener to an existing region, then observe how the cache listener reports events that occur in the cache. A cache listener reports entry and region events both before and after they occur. Entry events are create, update, invalidate, and destroy. Region events are clear, create, invalidate, and destroy. A cache listener only receives callbacks for events occurring in the local cache. The local cache listener is not invoked when an entry is destroyed in a remote cache. However, if that destroy is distributed then the subsequent destroy in the local cache causes the cache listener's afterDestroy method to be called.

Some region attributes are immutable after they have been established, while others, such as a cache listener, can be modified after the region has been created. To see how a cache listener works, complete these steps:

In both cacherunner clients:

Make sure that the two cacheRunner client sessions you used in the previous exercise are still set to the listenerWriterLoader region. If they aren't, then set both of them to that region:

chrgn listenerWriterLoader

In the first cacherunner client:

Put some entries in the region:

put key-1 val1
put key-2 val2
put key-3 val3
put key-4 val4

In the second cacherunner client:

1. Retrieve the four entries that were put in the first client:

   get key-1
key-1 -> Bytes: val1
get key-2
key-2 -> Bytes: newVal2
get key-3
key-3 -> Bytes: newVal3
get key-4
key-4 -> Bytes: val4

2. Register interest for two of the keys:

   reg key-1 key-2

3. Add a cache listener to the existing client region:

   set listener

4. Create a new entry in the local cache:

   put key-5 val-5

   The cache listener reports the events that occur:

TestCacheListener.afterCreate :
Print Event:
Cache Event Origin Local
Region is : /root/listenerWriterLoader
Key is : key-5
Old value is : NULL
New value is : val-5

In the first client:

Update key-1 and key-2:

put key-1 newVal1
put key-2 newVal2

Look at the second client. The cache listener reports the events that occur for the updates:

TestCacheListener.afterUpdate :
Print Event:
Cache Event Origin Local
Region is : /root/listenerWriterLoader
Key is : key-1
Old value is : NULL
New value is : newVal1
TestCacheListener.afterUpdate :
Print Event:
Cache Event Origin Local
Region is : /root/listenerWriterLoader
Key is : key-2
Old value is : NULL
New value is : newVal2

In the second client:

1. Remove the cache listener from the client region by setting the listener value to null:

set listener null

2. Create a new entry in the local cache:

   put key-6 val-6

   No event reporting occurs because the cache listener was removed from the region.

In the first client:

Update key-2 and key-3:

put key-2 123
put key-3 456

Again, no event reporting occurs because the cache listener was removed.

Ending the client sessions:

You need to keep one of the cacheRunner sessions open for the next exercise, but the second session can be closed. Follow these steps:

1. End the first cacheRunner application, but leave the session open:

exit

2. End the second cacheRunner application:

exit

3. Close the second cacheRunner session:

exit

4. Keep the cache server running for the next exercise.

Using a Cacheless Region

In this exercise you learn about applications that do not perform local caching. An application can receive all events on a region without storing the data that comes with the events. Consequently, the application can pass data through to other receivers without the overhead of caching. This configuration lets you separate event processing from data management.

To see how a cacheless region works, complete these steps:

1. In the open cacheRunner session, start the cacheRunner application and specify tcr_cacheless.xml as its initialization file:

   cacherunner.exe tcr_cacheless.xml

2. Go to the listenerWriterLoader region, then check its cache contents:

chrgn listenerWriterLoader
ls
Region Entries:
Subregions:

3. There are no entries in the local client cache for the listenerWriterLoader region. However, remember that the listenerWriterLoader region on the cache server contains an entry named entry1 that has a value of 1.0.

4. Retrieve entry1 from the cache server:

   get entry1
entry1 -> String: 1.0

   The local cache acknowledges that the entry was received.

5. Check the contents again:

   ls
Region Entries:
Subregions:

   The entry is not retained in the local client cache.

6. Close the cacheRunner application:

   exit

7. Close the cacheRunner session:

   exit

8. Stop the cache server:

   cacheserver stop

9. Close the cache server session:

   exit

---

Part 2: Remote Querying

---

Running cacheRunner for Querying

In this example, cacheRunner accepts query strings in input and runs them against the cached data stored on a Java cache server. The cacheRunner example uses a GemFire Java cache server configuration file, csQueryPortfolios.xml. When the cache server starts, csQueryPortfolios.xml creates a root region on the server. It also creates a subregion named Portfolios, which is a region of stock portfolios whose keys are the portfolio ID.

These procedures introduce a few of the querying commands. For information on others, enter help or ? at the cacheRunner client session prompt.

In the procedures, the lines you type are shown in a boldface fixed font. System output is shown in a regular fixed font.

Starting the Cache Server

To start the cache server, create a session and complete the following steps:

1. Configure the session environment according to the steps listed in Configuring the Environment.

2. Add the classes for javaobject.jar to your CLASSPATH by entering the following in a single line:

set CLASSPATH=%GEMFIRE%\native_client\examples\cacheRunner\javaobject.jar;%CLASSPATH%

The file javaobject.jar is required for registering the portfolio and position object on the Java cache server.

3. Go to the cacheRunner directory, then start the cache server:

   cd native_client/examples/cacheRunner

   cacheserver start cache-xml-file=csQueryPortfolios.xml

   The csQueryPortfolios.xml file configures the server with a root region and a subregion named Portfolios with five portfolio objects. A message similar to the following appears, indicating that the cache server is running:

Cacheserver pid: 2120 status: running

Starting the cacheRunner Client

Follow these steps to start the cacheRunner client using the tcr_cacheless.xml initialization file:

1. From the GemFire product installation directory, create a cacheRunner session.

2. Go to the cacheRunner directory in the session:

cd native_client/examples/cacheRunner

3. Start the cacheRunner application, specifying tcr_cacheless.xml:

   cacherunner.exe tcr_cacheless.xml

   The cacheRunner client is initialized using the region settings in the tcr_cacheless.xml file in the cacheRunner directory. The application creates a root region and two subregions, then the /root region prompt appears. As you move from region to region, the prompt includes a path to tell you where you are, such as /root/Portfolios>.

4. In the cacheRunner client, go to the Portfolios region:

   chrgn Portfolios

Executing Remote Queries

In these exercises you invoke the execute method to submit several queries that are run on the cache server, then the results are returned to the local client cache.

In the cacherunner client:

1. This query returns the status of the cache entries for the root/Portfolios region on the cache server. Enter the following command:

exec select distinct ID, status from /root/Portfolios

This is the query output:

Query results : Found 5 row
Struct with 2 fields
ID : 4
status : inactive
Struct with 2 fields
ID : 5
status : active
Struct with 2 fields
ID : 2
status : inactive
Struct with 2 fields
ID : 3
status : active
Struct with 2 fields
ID : 1
status : active

2. Run a second query. This query returns the row IDs on the cache server:

   exec select distinct ID from /root/Portfolios

   Query results : Found 5 row
2
4
1
3
5

3. Run a third query. This query returns the object types for the root/Portfolios region on the cache server:

   exec select distinct ID, pkid, getType from /root/Portfolios where 1=1

   Query results : Found 5 row
Struct with 3 fields
ID : 2
pkid : 2
getType : type2
Struct with 3 fields
ID : 1
pkid : 1
getType : type1
Struct with 3 fields
ID : 3
pkid : 3
getType : type3
Struct with 3 fields
ID : 5
pkid : 5
getType : type2
Struct with 3 fields
ID : 4
pkid : 4
getType : type1

Executing Region Query Shortcuts

In these exercises you use region query shortcut methods to submit queries to the cache server, then the results are returned to the local client cache. Query shortcuts take the query "predicate" as a parameter (the part after the WHERE clause), or they can take a normal full query. The three query shortcut methods are described below:

• query — Executes a query and returns the results.
• existsValue —Executes a query and returns TRUE or FALSE based on whether any results (rows) are obtained.
• selectValue —Executes a query and returns only a single result (row). If no results are obtained then it returns NULL. If more than one result (row) is obtained then a QueryException occurs.

In the cacherunner client:

1. Run this query shortcut, which returns the Portfolios objects with an ID of 1:

query ID=1

Query result:

query predicate is ID=1
Query results : Found 1 row
PortfolioObject: [ ID=1 status=active type=type1 pkid=1
                          P1: NULL P2: NULL ]

The query shortcut takes the predicate string ID=1, constructs the full query statement, then executes the query.

2. Run this existsValue shortcut. The query returns either TRUE or FALSE, depending on whether the result is obtained.

   existsvalue ID=1

   Query result:

   query predicate is ID=1
Query result is TRUE

3. Run this selectValue shortcut. The query returns the object types for the root/Portfolios region on the cache server:

   selectValue ID=2

   Query result:

   query predicate is ID=2
PortfolioObject: [ ID=2 status=inactive type=type2 pkid=2
                          P1: NULL P2: NULL ]

4. Close the cacheRunner application:

   exit

5. Close the cacheRunner session:

   exit

6. Stop the cache server:

   cacheserver stop

7. Close the cache server session:

   exit

---

Part 3: High Availability

---

Running cacheRunner for High Availability

In this example, cacheRunner demonstrates server failover to highly available client queue backups by failing over to a secondary cache server when the primary server becomes unavailable. The secondary server continues to provide the latest entry updates to the client when the primary server fails.

In the procedures, the lines you type are shown in a boldface fixed font. System output is shown in a regular fixed font.

Starting the Primary and Secondary Cache Servers

To start the primary and secondary cache servers, create a session and complete the following steps:

1. Configure the session environment according to the steps listed in Configuring the Environment.

2. Go to the cacheRunner directory:

   cd native_client/examples/cacheRunner

3. Start the first (primary) cache server by running this command:

   cacheserver start cache-xml-file=cacherunner.xml -dir=gfecs1

   The gfecs1 directory contains a copy of cacherunner.xml, which specifies 50505 for the BridgeServer port for the primary cache server.

4. Start the second (secondary) cache server by running this command:

   cacheserver start cache-xml-file=cacherunner2.xml -dir=gfecs2

   The gfecs2 directory contains a copy of cacherunner2.xml, which specifies 50506 for the BridgeServer port for the secondary cache server.

Starting the cacheRunner Client

To start the cacheRunner client, complete the following steps:

1. From the GemFire product installation directory, create a session.

2. Go to the cacheRunner directory in the session:

cd native_client/examples/cacheRunner

3. Start the cacheRunner client, specifying tcr_hacache.xml:

   cacherunner.exe tcr_hacache.xml

   The cacheRunner client is initialized using the settings in tcr_hacache.xml in the cacheRunner directory. The XML specifies two cache-level server endpoints that the client connects to (50505 for the primary, and 50506 for the secondary). The redundancy-level=1 attribute specifies the number of redundant, or secondary, servers to maintain in addition to the primary server.
   

Performing Cache Operations

In these steps you produce data in the cacheRunner local client cache. The primary and secondary cache servers receive the updated values.

1. In the cacheRunner client, go to the listenerWriterLoader region:

   chrgn listenerWriterLoader

2. Add an entry to the region:

   put entry1 ball str

   This line creates an entry whose key is entry1 and whose value is the string ball.

3. Check the contents to see the new entry:

   ls
Region Entries:
entry1 -> String: ball

4. Invalidate the new entry in the local cache and then check the contents:

   inv -l entry1
ls
Region Entries:
entry1 -> No value in cache.

   The value for the entry has been removed from the local cache.

5. Get the entry from the primary cache server:

   get entry1
entry1 -> String: ball

Initiating Server Failover

In this procedure you stop and start the primary and secondary servers to initiate a server failover condition.

1. Stop the primary cache server by running this command in the cache server session:

   cacheserver stop -dir=gfecs1

   The following message displays in the server session:

CacheServer stopped.

A redundancy level warning continuously displays in the client session as a result of the stopped server:

Requested redundancy level 1 is not satisfiable with 1 servers available

2. The secondary server is now the primary. In the client session, get an entry from the new primary server:

   get entry1
entry1 -> String: ball

   The updated entry is retrieved from the server.

3. Put a new entry in the client session, then get the entry from the server:

   put entry2 bat str
get entry2
entry2 -> String: bat

4. Start the first cache server again by running this command in the cache server session:

   cacheserver start cache-xml-file=cacherunner.xml -dir=gfecs1

5. In the cache server session, stop the second (primary) cache server:

   cacheserver stop -dir=gfecs2

6. In the client session, get the new entry from the new primary server:

   get entry2
entry2 -> String: bat

   Both the primary and secondary servers maintain client cache updates in case a server failover occurs.

Closing the Cache Server and Client

1. Close the cacheRunner application:

   exit

2. Close the cacheRunner session:

   exit

3. Stop the remaining cache server:

   cacheserver stop -dir=gfecs1

4. Close the cache server session:

   exit

Changing System Parameters

This product ships configured to run with default system properties. If you need to run in a non-default configuration, GemFire also takes a system-level configuration file. Copy the gfcpp.properties file into your cacheRunner directory from the defaultSystem directory and edit it as needed. For example, to change the name of the cache.xml file, uncomment this line and change the file name:

#cache-xml-file=cache.xml