Pivotal GemFire in 15 Minutes or Less

Need a quick introduction to Pivotal GemFire? Take this brief tour to try out basic features and functionality.

About Pivotal GemFire briefly describes some components and concepts you will explore here.

Step 1: Download and install Pivotal GemFire.

Visit the GemFire product page, and download the latest GemFire 7.0 distribution:


Locate the Downloads link, and download the GemFire ZIP file. Use any graphical unzip utility or the command line to install GemFire from the ZIP file. For example:
unzip Pivotal_GemFire_702_b45714.zip -d /home/your_userid/pivotal-gemfire
Note: If you have not done so already, download and install Java for your system. See Pivotal GemFire Supported Configurations for a list of supported Java versions. GemFire requires the JDK (and not just a JRE) to run gfsh commands and to launch servers and locators using the ServerLauncher or LocatorLauncher APIs.

Step 2: Set GemFire, Java, and OS environment variables.

Configure GemFire and Java environment variables. For example, on Linux:
GEMFIRE=/home/your_userid/pivotal-gemfire/Pivotal_GemFire_702_b45714;export GEMFIRE
GF_JAVA=$JAVA_HOME/bin/java;export GF_JAVA 
$JAVA_HOME/lib/tools.jar;export CLASSPATH
See Windows/Unix/Linux: Install Pivotal GemFire from a ZIP File if you need additional guidance on setting environment variables for your platform.

Step 3: Use gfsh to start a Locator.

Use the gfsh command line interface to start up a Locator.
  1. Create a scratch working directory (for example, my_gemfire) and change directories into it. gfsh will add Locator and server working directories and log files in this location.
  2. Start gfsh by typing gfsh at the command line (or gfsh.bat if you are using Windows).
        _________________________     __
       / _____/ ______/ ______/ /____/ /
      / /  __/ /___  /_____  / _____  /
     / /__/ / ____/  _____/ / /    / /
    /______/_/      /______/_/    /_/    v7.0.2
    Monitor and Manage GemFire
  3. At the gfsh prompt, type:
    gfsh>start locator --name=locator1

By default, gfsh starts the locator using port 10334. In addition, because no JMX Manager exists yet, gfsh starts a JMX Manager within the Locator using port 1099.

Step 4. Start GemFire Pulse.

Start up the browser-based GemFire Pulse monitoring tool.
gfsh>start pulse
This command launches Pulse and automatically connects you to the JMX Manager running in the Locator. At the Pulse login screen, type in the default username admin and password admin.

Step 5: Start two cache server nodes.

Start a cache server:
gfsh>start server --name=server1 --server-port=40405
This commands starts a cache server named "server1" on the specified port of 40405. Next, start a second cache server. Note that this time you must specify a different --server-port argument because you are starting a cache server process on the same host machine.
gfsh>start server --name=server2 --server-port=40406
Observe the changes (new members and servers) in Pulse. Try expanding the distributed system icon to see the Locator and two cache servers graphically.
List the members of your distributed system. The locator and cache servers you just started should appear in the list.
gfsh>list members

Step 6: Create regions.

In this step you will try out creating different types of regions with the gfsh command line utility. Regions are the core building blocks of the GemFire distributed system and provide the means for organizing your data.
  1. Create a replicated region:
    gfsh>create region --name=region1 --type=REPLICATE
  2. Create a partitioned region:
    gfsh>create region --name=region2 --type=PARTITION
  3. Create a partitioned persistent region.
    gfsh>create region --name=region3 --type=PARTITION_PERSISTENT
  4. Use the gfsh command line to view a list of the regions that you just created.
    gfsh>list regions
  5. To view specifics about a region, type something like the following:
    gfsh>describe region --name=region1
  6. In Pulse, click the green cluster icon to see all the new members and new regions that you just added to your distributed system.
Note: Keep this gfsh prompt open for the next steps.

Step 7: Begin executing the Server Managed Caching QuickStart example.

Note: The following steps use QuickStart examples from the product_install_dir/SampleCode/quickstart folder.
  1. Keep the gfsh prompt open and start two operating system terminal sessions. Make sure each terminal session has the proper GemFire, Java and OS environment variables set (see Step 2 as a reference.)
  2. In the gfsh prompt, start the QuickStart example's cache server:
    gfsh>start server --name=server_mc --cache-xml-file=${SYS_GEMFIRE_DIR}/SampleCode/quickstart/xml/Server.xml
  3. In the first terminal session, change to the product_install_dir/SampleCode/quickstart directory. Start the consumer client:
    prompt# java quickstart.ClientConsumer all-keys
  4. In the second terminal session, change to the product_install_dir/SampleCode/quickstart directory.Start the worker client.
    prompt# java quickstart.ClientWorker
    The application in this second terminal adds actual data into the region. After the client runs, do not select Enter yet!
  5. Observe the changes in Pulse. For example, note that in the Subscriptions area there are now "2" subscriptions.

Step 8: Examine the distribution of data in the region and run queries on the data.

Return to the gfsh terminal.

Use gfsh to examine the exampleRegion.
gfsh>describe region --name=/exampleRegion
The command returns the following information about the region:
Name            : exampleRegion
Data Policy     : replicate
Hosting Members : server_mc

Non-Default Attributes Shared By Hosting Members  

 Type  |     Name     | Value
------ | ------------ | ----------------------------
Region | cache-loader | quickstart.SimpleCacheLoader
       | size         | 2
Use the locate entry command to see where a particular key is located:
gfsh>locate entry --key=key0 --region=exampleRegion
The command returns the following information about the entry:
Result          : true
Key Class       : java.lang.String
Key             : key0
Locations Found : 1

MemberName | MemberId
---------- | -----------------------------------------
server_mc  |<v5>:38030
Execute a query against the region:
gfsh>query --query="SELECT entry.value FROM /exampleRegion.entries entry WHERE entry.key='key0'"
The query returns the following results:
Result     : true
startCount : 0
endCount   : 20
Rows       : 1



Step 9: Stop individual members and shut down the system.

To exit the QuickStart application and shut down your distributed system, do the following:
  1. In the ClientWorker terminal session, select the Enter key to close the cache and exit the application.
  2. In the second terminal, select the Enter key. The ClientConsumer application in the other terminal session will also close its cache and exit.
  3. In the current gfsh session, stop the QuickStart cache server process:
    gfsh>stop server --name=server_mc
    You can use stop server and stop locator commands to shut down individual processes.
  4. Shut down the rest of the cache servers by entering the following at the gfsh prompt:
    When prompted, type 'Y' to confirm the shutdown of the distributed system.
  5. Shut down the locator by entering the following command at the gfsh prompt:
    gfsh>stop locator --name=locator1
    Wait for the locator to stop.
  6. To exit the gfsh prompt, type:

Step 10: What to do next...

Here are some suggestions on what to explore next with Pivotal GemFire: