GemFire Enterprise Native Client
QuickStart Guide

September, 2007

The GemFire Enterprise Native Client QuickStart Guide provides a set of examples that demonstrate the capabilities of the GemFire Enterprise Native Client product. Reviewing the operation of these QuickStart examples, along with studying the source files for the examples, can help you quickly get started with C++ and Microsoft .NET code development for the GemFire Enterprise Native 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 native_client\quickstart directory for the GemFire Enterprise installation. The C++ examples are in the cpp directory, and the C# examples are in the csharp directory. Note that the C# examples are only available for Windows.

Each example has a pair of companion XML files in the XMLs directory that it uses to configure the server and the client. For example, BasicOperations uses serverBasicOperations.xml to configure the cache server and clientBasicOperations.xml to configure the client.

The C++ and C# example files are packaged as Microsoft Visual Studio 2005 solutions (quickstart_cpp.sln and quickstart_csharp.sln), and can be accessed through the IDE or through any editor.

About the GemFire Enterprise Native Client

The GemFire Enterprise Native Client provides access for C++ and Microsoft .NET clients to the GemFire Enterprise distributed system. GemFire Enterprise native clients in C++ and .NET communicate only with the cache server and do not communicate with each other. C++ and .NET native clients provide access to the full region API, including support for application plugins. All of this is transparent to the end user.

This figure provides a conceptual overview of how .NET and C++ applications access the GemFire Enterprise cache server:

Configuring the QuickStart Environment

Follow these steps to prepare your system environment to run the QuickStart examples. Throughout this QuickStart guide, text that you type is shown in bold.

1. Start a terminal session from the GemFire product installation directory, then run the appropriate bin/setenv script for your system. See the environment configuration list below for system-specific instructions.
   
   
2. Set the JAVA_HOME and GF_JAVA_HOME environment variables to the $GEMFIRE/jre directory. The JAVA_HOME setting is for your applications, and GF_JAVA_HOME is for the GemFire scripts. The $GEMFIRE/jre directory contains the Java runtime environment that was used when the QuickStart examples were compiled, so that version of Java or newer is required to run them. If you have the $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 the latest version of the Java JRE or JDK installed and you must set JAVA_HOME and GF_JAVA_HOME to point to it. See the Sun Java web site at http://java.sun.com for the latest Java version for your operating system.
   
   
3. Add $JAVA_HOME/bin to the start of your PATH.
   
   
4. Change the working directory to the quickstart directory for the native client:
   

   cd native_client\quickstart
   

The following list is a summary of the environment configuration commands that you need to run for the QuickStart Guide. Choose the set of commands that are appropriate for your operating system. The text that you type is shown in bold.

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%

About the QuickStart Examples

The examples are briefly described in this section. Each example performs the following steps:

1. Starts the Java cache server with the example's server XML.
2. Connects to the GemFire distributed system.
3. Creates a GemFire cache.
4. Performs operations specific to the example.
5. Closes the GemFire cache.
6. Disconnects from the GemFire distributed system.
7. Shuts down the Java 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:

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 the GemFire Enterprise Native Client Guide 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:

• Sets the SimpleCacheListener plugin on a region
• Puts three entries into the region
• Gets the entry idle timeout setting from the region
• Counts the keys in the region before the timeout duration elapses
• Waits for the timeout expiration action to be reported by the SimpleCacheListener
• Counts the remaining keys in the region after the timeout duration elapses

Multiple eviction action options are available, including overflow. For detailed information, see the GemFire Enterprise Native Client Guide.

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.

Interop

The Interop example is a simple demonstration that starts a Java cache server with a C++ client, a C# client, and a Java client to demonstrate their interoperability. The C# client is not started on Linux or Solaris.

Each client populates a single entry on a region, then waits for the other clients to populate their entries. Each client then gets and prints out every entry populated on the server. You might see multiple lines output every second with the message Checking server for keys... displayed while the clients wait for the others to complete their puts. You should eventually see the output from each client printing its own entry and the entries from the other clients.

Note that the Interop example is not included on the QuickStart menu, so it can only be started from the command line. See Running the Interop Example for more information.

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.

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.

Note that the C# examples are only available 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 BasicOperations)

C# examples

runcs ExampleName (for example, runcs RemoteQuery)

Running a C++ Example From the Menu

For Windows:

1. Start the menu.

runcpp

2. Enter a number from the list to start that example.

1. Start the menu.

./runcpp.sh

2. Enter a number from the list to start that example.

Running a C# Example From the Menu

1. Start the menu.

runcs

2. Enter a number from the list to start that example.

Running the Interop Example

The Interop example can only be run from the command line, so it's not listed on the QuickStart menu. Follow these steps to run Interop.

For Windows:

1. Start the example.

runinterop

2. When the example has finished, stop the Java cache server by entering this command in the cache server's open terminal session:

   cacheserver stop -dir=gfecs

1. Start the example.

./runinterop.sh

2. When the example has finished, stop the Java cache server by entering this command in the cache server's open terminal session:
   

   cacheserver stop -dir=gfecs

   
   

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 GemStone Technical Support:

Web: http://support.gemstone.com
E-mail: support@gemstone.com
Phone: (800) 243-4772 or (503) 533-3503

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 setenv script with a leading dot (.) on Linux and Solaris so that the environment settings are made for the current shell. You must also run the example from the quickstart directory with the runcpp or runcs scripts 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 scripts 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.

Building the Examples

If you want to build the QuickStart examples yourself from the source files provided, follow these steps:

1. Verify that your compiler environment is set up to build from the command line.
2. Create a session, then change to the quickstart examples directory:
   

   cd GemFireInstallDirectory\native_client\quickstart

3. Run the appropriate build script for your system.

   For Windows: buildit.bat

   For Linux and Solaris: ./buildit.sh

GemStone Systems, Inc.
1260 NW Waterhouse Ave.
Suite 200
Beaverton, OR 97006

Phone: (503) 533-3000 , Fax: (503) 533-3220 , info@gemstone.com , www.gemstone.com

Top

Copyright 2006-2007 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.