CacheRunner

GemFire Enterprise Native Client

C# Programming Example

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

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, 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. 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=<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
> bin\setenv.bat
> 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:

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.

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

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

  3. cd NativeClient_xxxx/examples/cli_CacheRunner

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

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

  2. Stop both C# clients:

    quit

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

  2. set CLASSPATH=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.

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

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

  5. Cacheserver pid: 2120 status: running

  6. 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:
  2. chrgn Portfolios

  3. This query returns the status of the cache entries for the /root/Portfolios region on the cache server. Enter the following command:
  4. 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 ||

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

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

In the CacheRunner client:

  1. Run this query shortcut, which returns the Portfolios objects with an ID of 1:
  2. 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.

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

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

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

  2. cd NativeClient_xxxx/examples/cli_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 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 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


Top

 

Copyright © 2005-2008 by GemStone Systems, Inc. All rights reserved. GemStone®, GemFire®, and the GemStone logo are trademarks or registered trademarks of GemStone Systems, Inc. All other trade names or trademarks are the property of their respective owners. Information in this document is subject to change without notice.