CacheRunner

GemFire Enterprise Native Client

C# Programming Example

September 2008

The CacheRunner C# example is an interactive program for modifying and viewing GemFire cache contents as a C# client interacts with a Java 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 cli_CacheRunner directory that have a .cs file extension.

This example is divided into three parts, with each part requiring a different XML configuration file for the Java cache server. CacheRunner is also configured using a local gfcpp.properties file.

• Part 1: Inspecting and Modifying the Cache demonstrates cache operations using two C# native clients with a GemFire Java cache server. It shows how to put and get data between clients, and how to derive a complex number as a user-defined class for use as a key or value. You start two C# client instances and see how a put value in one can be gotten in another as the cache server is updated with the new values. This part uses server configuration file cacherunner.xml. The procedures describing non-cacheable and cacheable values use client configuration files tcr_cacheless.xml and tcr_cache.xml.


• Part 2: Remote Querying demonstrates how to initiate a query from a C# client that is executed on data stored on a Java cache server. The query results are returned to the C# client. This part uses server configuration file csQueryPortfolios.xml. If no XML file is specified when CacheRunner is started, it's configured using tcr_cache.xml by default.


• Part 3: High Availability shows how you can set up redundant cache servers in case 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.

Configuring the Environment

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

1. From the GemFire Enterprise product installation directory, configure your environment settings by following the steps in examples/EnvSetup.html. 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. 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
% JAVA_HOME=<installed JRE PATH>; export JAVA_HOME
% GF_JAVA_HOME=$JAVA_HOME; export GF_JAVA_HOME
% PATH=$JAVA_HOME/bin:$PATH; export PATH

Windows

> cd GemFireInstallDirectory
> set JAVA_HOME=<installed JRE PATH>
> set GF_JAVA_HOME=%JAVA_HOME%
> set PATH=%JAVA_HOME%\bin;%PATH%

---

Part 1: Inspecting and Modifying the Cache

---

CacheRunner Configuration Files

The CacheRunner C# example uses a GemFire cache server configuration file called cacherunner.xml. When the Java cache server starts, cacherunner.xml creates a root region on the server and two subregions named listenerWriterLoader and sub1. This is a description of each cache server region and how they are configured:

• root — The root region for the cache server. The region's scope is distributed-no-ack, and notify-by-subscription is set to true.
• listenerWriterLoader — A region with distributed-ack scope and mirror-type set to keys-values.
• sub1 — A region with local scope. This region isn't used in these exercises.

The CacheRunner application comes with XML configuration files that configure the cache server and the local client cache to demonstrate various operations with the cache server. This example does not use tcr_hacacheless.xml.

• tcr_cache.xml — The listenerWriterLoader region establishes an endpoint connection with the server and performs distributed caching operations by receiving updates from the cache server. If CacheRunner.exe is run without specifying an XML file, it is automatically configured using tcr_cache.xml.
• tcr_hacache.xml — Configures the client for high availability by specifying multiple servers for storing data and setting a server redundancy level.
• tcr_cacheless.xml — The listenerWriterLoader region establishes an endpoint connection with the server and receives data from the cache server. Entries retrieved from the cache server are not retained in the client's local cache because the caching-enabled region attribute is set to false. The Portfolios region is used for remote querying.

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.

Starting the Cache Server

To start the cache server, create a session from the GemFire Enterprise product installation directory and complete the following steps. Throughout this example, when you're prompted to enter the native client directory, replace the xxxx in NativeClient_xxxx with the actual four-digit product version number.

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

2. Go to the cli_CacheRunner directory, then start the cache server with the local cacherunner.xml file:

   cd \NativeClient_xxxx\examples\cli_CacheRunner

   cacheserver start cache-xml-file=cacherunner.xml

   The cache server is initialized using the configurations in cacherunner.xml. A message similar to the following appears, indicating that the cache server is running:

Cacheserver pid: 2120 status: running

Starting Two CacheRunner Clients Using tcr_cache.xml

Start two CacheRunner clients and configure their caches using tcr_cache.xml by following these steps:

1. Create two sessions for two CacheRunner clients.

2. In each session, go to the cli_CacheRunner directory:

cd \NativeClient_xxxx\examples\cli_CacheRunner

3. In each session, start the CacheRunner client with tcr_cache.xml:

   CacheRunner.exe tcr_cache.xml

   CacheRunner is configured using the settings in tcr_cache.xml. The following command prompt appears for both C# clients:

/root: chrgn, lsrgn, get, put, exec, query, existsvalue, selectvalue, quit:

This is a brief description of the prompts and commands you can uses with CacheRunner. See the GemFire Enterprise product documentation for more information about these commands:

• /root: — A prompt that indicates the current region.
• chrgn — Navigate to a different region.
• lsrgn — Display the current region and its subregions.
• get — Get a value from the cache server and add it to the local cache.
• put — Put a value into the local cache and propagate the value to the cache server.
• exec — Execute a query.
• query — Run a query shortcut method.
• existsvalue —Run a query shortcut method.
• selectvalue —Run a query shortcut method.
• quit — Quit the CacheRunner application.

Entering and Receiving Data in the Clients

In this exercise, you put data in one client and the client updates the cache server region with the new data. Next, the second client does a get to retrieve the updated values from the cache server and update its local cache. The cache listeners for the clients report the cache events that occur for each put and get.

In both CacheRunner clients

In both clients, go to the listenerWriterLoader region:

chrgn listenerWriterLoader

In the first CacheRunner client:

1. Add an entry:

   put key1 first

   The cache listener reports the events related to the put command. The entry is identified as a string, and the cache server is updated with the new entry.

   --- Received afterCreate event of: key1
Put string -- key: key1 value: first

   The second CacheRunner client also receives an afterCreate event message from the server for the put:

   --- Received afterCreate event of: key1

2. Add another entry in the first client:

   put key2 7.2+3i

   The cache listener reports the events related to the put command. The entry is identified as a complex number, and the cache server is updated with the new entry.

   --- Received afterCreate event of: key2
Put complex -- key: key2 value: 7.2+3i

   The second CacheRunner client also receives an afterCreate event message from the server for the put:

   --- Received afterCreate event of: key2

In the second CacheRunner client

1. Get the key1 entry from the cache server that was added by the first client:

   get key1

   The key name and value are retrieved from the cache server and displayed:

   Get [CacheableString] -- key: key1 value: first

2. Enter a new value for key1:

   put key1 second

   The cache listener reports the events related to the put command, identifying the entry as a string. The cache server is updated with the new value for key1.

   --- Received afterUpdate event of: key1
Put string -- key: key1 value: second

In the first CacheRunner client

Get the new key1 entry from the cache server that was added by the second client:

get key1

The key name and new value are retrieved from the cache server:

Get [CacheableString] -- key: key1 value: second

Stopping the Cache Server and Clients

To complete the procedures in Part 1 and prepare for Part 2, the Java cache server and the two C# clients must be stopped. However, their sessions need to remain open so the cache server and clients can be started again from those sessions using a different XML configuration file.

1. Stop the cache server, but leave its session open:

   cacheserver stop

   Stop both C# clients:

   quit

   Close one of the C# client sessions. Only one client is needed for Part 2: Remote Querying and Part 3: High Availability.

   exit

---

Part 2: Remote Querying

---

These procedures introduce some of the querying commands available for the native client. The CacheRunner C# client accepts query strings in input, runs them against the cached data stored on the cache server, then returns the query results to the C# client.

Starting the Cache Server and Client

To start the cache server, complete the following steps using the open cache server and client sessions:

1. In the cache server session, add the classes for javaobject.jar to your CLASSPATH by entering the following in a single line:

set CLASSPATH=<full path to NativeClient_xxxx>\examples\cli_CacheRunner\javaobject.jar;%CLASSPATH%

The file javaobject.jar is required for registering the Portfolio and Position objects on the cache server for remote querying.

2. Make sure the cli_CacheRunner directory is still the current working directory. If it isn't, then set it.

   cd \NativeClient_xxxx\examples\cli_CacheRunner

3. Start the cache server with csQueryPortfolios.xml:

   cacheserver start cache-xml-file=csQueryPortfolios.xml

   The cache server is initialized using the configurations in csQueryPortfolios.xml. The XML file sets up a root region on the server named DistRegionAck with scope set to distributed-ack. It also creates a Portfolio data object on the server for querying, along with five stock portfolio objects whose keys are the portfolio ID. A message similar to the following appears, indicating that the cache server is running:

Cacheserver pid: 2120 status: running

4. In the client session, start the CacheRunner client with tcr_cacheless.xml to create a Portfolios client region for the querying exercises.

   cacherunner.exe tcr_cacheless.xml

Executing Queries

You invoke the execute method on the client to submit several queries that are run on the cache server, then the results are returned to the local client cache. You only need to use one of the CacheRunner clients for querying; the other client can be set aside for now.

In the CacheRunner client:

1. Go to the client's Portfolios region:

chrgn Portfolios

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

Query output:

Columns:       ID        status
        Result (0): 4 || inactive ||
        Result (0): 5 || active ||
        Result (0): 2 || inactive ||
        Result (0): 3 || active ||
        Result (0): 1 || active ||

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

   exec select distinct ID from /root/Portfolios

   Query output:

   Result 1: 1
Result 2: 2
Result 3: 3
Result 4: 4
Result 5: 5

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

   Columns:       ID       pkid    getType
        Result (0): 2 || 2 || type2 ||
        Result (0): 1 || 1 || type1 ||
        Result (0): 3 || 3 || type3 ||
        Result (0): 5 || 5 || type2 ||
        Result (0): 4 || 4 || 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:

Result 1: Portfolio [ID=1 status=active type=type1 pkid=1]
P1:
P2:

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:

   Result is True

3. Run this selectValue shortcut. The query returns the object types on the cache server for the specified ID:

   selectValue ID=2

   Query result:

   Result : Portfolio [ID=2 status=inactive type=type2 pkid=2]
P1:
P2:

   
   

Stopping the Cache Server and Client

To complete the procedures in Part 2 and prepare for Part 3: High Availability , the Java cache server and the C# client must be stopped. However, their sessions need to remain open so the cache server and client can be started again using a different XML configuration file.

1. Stop the cache server, but leave its session open:

   cacheserver stop

   Stop the CacheRunner client and leave its session open:

   quit

---

Part 3: High Availability

---

Running CacheRunner for Failover and High Availability

The CacheRunner C# example demonstrates server failover to highly available client queue backups by failing over to a secondary cache server when the primary server becomes unavailable.

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 server, complete the following steps in the open cache server session:

1. Make sure the cli_CacheRunner directory is still the current working directory. If it isn't, then set it.

   cd \NativeClient_xxxx\examples\cli_CacheRunner

2. Start the first 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.

3. Start the second 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 in the open client session:

1. Make sure the cli_CacheRunner directory is still the current working directory. If it isn't, then set it.

cd \NativeClient_xxxx\examples\cli_CacheRunner

2. 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 cli_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 servers to use in addition to the primary server.
   

Performing Cache Operations to Update the Server

In these steps you produce data in the CacheRunner local client cache. The cache servers receive the updated values.

1. In the CacheRunner client, change it to the listenerWriterLoader region:

   chrgn listenerWriterLoader

2. Add an entry to the region:

   put entry1 ball str

   This creates an entry whose key is entry1 and whose value is the string ball. The cache servers are updated with the new entry.
   

Stopping the Primary Cache Server to Initiate Failover

In this procedure you stop the primary cache server to initiate a server failover condition.

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

   cacheserver stop -dir=gfecs1

   Failover sets the secondary server as the new primary server:

2. In the client session, add an entry to the region:

   put entry2 bat str

   This creates an entry whose key is entry2 and whose value is the string bat. The cache server is updated with the new entry.

Restarting the Stopped Cache Server and Initiating Another Failover

Now restart the cache server that was previously stopped so both servers are running, then stop the other server to produce another failover condition.

1. Restart the stopped cache server by running this command in the server session:

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

   Now both cache servers are running.

2. Stop the other cache server by running this command in the server session:

   cacheserver stop -dir=gfecs2

   Failover occurs, and the restarted server is now the only server running.

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

   get entry2

   The key name and value are retrieved from the cache server and displayed:

   Get [CacheableString] -- key: entry2 value: bat

Closing the Client and the Cache Server

1. In the client session, quit the CacheRunner application and then exit the session:

   quit
exit

2. In the server session, stop the remaining cache server and then exit the session:

   cacheserver stop -dir=gfecs1
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 cli_CacheRunner directory from the native client 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

When you are finished with the example, delete the copied gfcpp.properties file from the cli_CacheRunner directory so it can run with the default configuration.