GemFire Enterprise Native Client
QuickStart Guide

March, 2008

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 NativeClient_xxxx\quickstart directory, where xxxx represents the four-digit product version. The C++ examples are in the cpp directory, and the C# examples are in the csharp directory. The Interop example is in its own interop 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. Additional support files are stored in the lib directory.

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 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. For Linux and Solaris: Start a terminal session from the GemFire Enterprise product installation directory, then run the bin/setenv.sh script.
   
   For Windows: Run the Visual Studio 2005 Command Prompt to create a session with preset compiler environment configurations. Change to the GemFire Enterprise product installation directory, then run the bin/setenv script.
   See the environment configuration list below for system-specific instructions for the following steps.
   
   
2. Install OpenSSL (optional):
   

   To enable security in GemFire, the security plugin securityImpl needs to be compiled. The security plugin optionally depends on OpenSSL for its PKCS sample template, so OpenSSL needs to be compiled or installed first.
   
   For Linux and Solaris, you can download the latest tarball archive for OpenSSL. For Windows users, you can get the OpenSSL installer here.

   To compile OpenSSL (Linux and Solaris):

   Copy the downloaded OpenSSL tarball to your appropriate Linux or SunOS folder at NativeClient_xxxx/templates/security/openssl, then execute buildit.sh from the shell.

   To install OpenSSL (Windows):

   Run the downloaded OpenSSL installer and accept the default installation path (C:\OpenSSL).

3. Set the JAVA_HOME and GF_JAVA_HOME environment variables to your installed 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 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.
   
   
4. Add $JAVA_HOME/bin to the start of your PATH.
   Set the GFCPP environment variable to point to NativeClient_xxxx.
   Set the OPENSSL environment variable. For Linux and Solaris, point it to the parent folder for the OpenSSL binaries created from the tarball. For Windows, if you accept the default installation path in step 2, it will be set OPENSSL=C:\OpenSSL\.
   
   
5. For Solaris and Linux only:
   Set the LD_LIBRARY_PATH environment variable to point to the NativeClient_xxxx/lib directory and $OPENSSL/lib directory for running the Security example.
   
   
6. For Windows only:
   Set the PATH environment variable to point to the NativeClient_xxxx\bin directory and %OPENSSL%\bin directory for running the Security example.
   

   The following environment configuration list is a summary of the commands described in steps 1 through 6 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=<installed JRE PATH> export JAVA_HOME
% GF_JAVA_HOME=$JAVA_HOME; export GF_JAVA_HOME
% PATH=$JAVA_HOME/bin:$PATH; export PATH
% GFCPP=<full path to NativeClient_xxxx>; export GFCPP
% OPENSSL=<parent folder for OpenSSL binaries>; export OPENSSL
% LD_LIBRARY_PATH=$GFCPP/bin:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH
% LD_LIBRARY_PATH=$OPENSSL/bin:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH

   Windows

   > cd GemFireInstallDirectory
> bin\setenv.bat
> set JAVA_HOME=<installed JRE PATH>
> set GF_JAVA_HOME=%JAVA_HOME%
> set GFCPP=C:\NativeClient_xxxx
> set OPENSSL=C:\OpenSSL
> set PATH=%JAVA_HOME%\bin;%GFCPP%\bin;%OPENSSL%\bin;%PATH%

7. Compile the security plugin:
   

   To compile the securityImpl security plugin on Linux and Solaris:

   Execute the buildit.bat script in the NativeClient_xxxx/templates/security directory.

   To compile the securityImpl security plugin on Windows:

   Execute the buildit.bat script in the NativeClient_xxxx/templates/security directory.

8. Change the working directory to the quickstart directory for the native client:
   

cd NativeClient_xxxx\quickstart

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

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.

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

Security

The Security example demonstrates how native client credentials are authenticated when the client connects to a cache server. Authorization for client cache operations is also shown.

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 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 C++ menu.

   runcpp

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

For Linux or Solaris:

1. Start the C++ menu.

   ./runcpp.sh

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

Running a C# Example From the Menu

1. Start the C# 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 Interop 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

For Linux or Solaris:

1. Start the Interop 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. Run the Visual Studio 2005 Command Prompt tool to open a command prompt shell.
2. In the command shell, enter the following environment configurations:
   

   set GEMFIRE=<full path to the GemFire Enterprise directory>
set GFCPP=NativeClient_xxxx
set JAVA_HOME=<installed JDK PATH>
set PATH=%PATH%;%JAVE_HOME%/bin;%GFCPP%\bin

3. In the command shell, change to the quickstart directory:
   

   cd %GFCPP%\quickstart

4. In the command shell, run the appropriate build script for your system. The build script uses the quickstart_cpp.sln and quickstart_csharp.sln Visual Studio solution files in the quickstart directory.

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