Hello World Example

In this topic, you run a simple GemFire data distribution example and then take a look at the example's configuration and application files.

What This Example Does

This example shows data distribution between two GemFire Java applications.

  • Both applications create a GemFire cache with a GemFire data region in it. Data regions hold and manage data entries, written in key/value pairs.
  • The data region in both applications is configured to receive all data written to the region from anywhere in the GemFire system.
  • One application is a producer, writing data to the cache, and the other is a consumer, receiving what the producer writes.
  • Both applications report their caching activities to your screen. The producer reports on its writing activities. Both applications run a listener that reports on events in the application's cache.

Setting Up the Environment

If you have not already done so, install and configure GemFire Enterprise and the product examples:

Running the Example

  1. Start two terminal sessions with their environments set up for GemFire and the product examples.
  2. In both sessions, change directory (cd) to the helloworld directory under your examples installation.
  3. In one terminal session, start the Consumer application:
    java helloworld.HelloWorldConsumer

    The application starts, creates the cache and region and then asks you to start the producer:

        This example shows how a distributed region works with replication 
        enabled. I'll create a replicate region, then the producer will 
        create the same region and put entries into it. Because my region 
        is a replicate, all of the producer's puts are automatically 
        pushed into my region.
    
        Connecting to the distributed system and creating the cache.
        Example region, /exampleRegion, created in cache.
    
        Please start the HelloWorldProducer.
    
  4. In the other terminal session, start the Producer application:
    java helloworld.HelloWorldProducer

    The application starts, creates the cache and region, puts data entry key/values pairs into its cache, and then exits:

        Connecting to the distributed system and creating the cache.
        Example region, /exampleRegion, created in cache.
        Putting entry: Hello, World
            Received afterCreate event for entry: Hello, World
        Putting entry: Hello, Moon!
            Received afterUpdate event for entry: Hello, Moon!
    
        Closing the cache and disconnecting.
    
        Please press Enter in the HelloWorldConsumer.
    
    
    The entry key is "Hello" for both puts, but the value changes. For each entry the producer puts, its listener receives the event and reports to your screen. The first put results in an entry creation. The second put results in an entry update, since the key, "Hello", is already in the cache.
  5. Look at the consumer session:
         Received afterCreate event for entry: Hello, World
         Received afterUpdate event for entry: Hello, Moon!
    
    Only the producer makes changes to its cache, but because of how the data region is configured, GemFire automatically distributes the changes to the consumer, so both caches receive the same events and end up with the same data in their region.
  6. Press Enter in the Consumer session, and it exits.

Walkthrough of the Example Files

The Hello World example use standard GemFire configuration and application files.
These are the files, which you can find under the helloworld directory in your examples installation:

  • gemfire.properties
  • xml/HelloWorld.xml
  • helloworld/HelloWorldProducer.java and helloworld/HelloWorldConsumer.java
  • helloworld/SimpleCacheListener.java

gemfire.properties

Purpose

GemFire system configuration file. Use this file to define how the processes in a GemFire system (in this example, two Java applications) find each other and communicate. Also use the file to configure logging, security, statistics gathering, and more. Each member has its own gemfire.properties file.

Non-default values in gemfire.properties

This example file sets non-default values for:

  • Multicast port location used by the applications to establish communication. In this example:
    mcast-port=10334
  • Level of logging the system should provide. In this example:
    log-level=warning

xml/HelloWorld.xml

Purpose

Declarative XML configuration for the GemFire cache. Use this file to set up general cache facilities and behavior and to create and initialize cached data regions. Although it can have any name, this file is generally referred to as cache.xml.

Contents of xml/HelloWorld.xml
  • XML version and DOCTYPE declarations (required).
  • <cache> element. Highest level element for peer and server caches. These are peer caches. (Client caches are defined by <client-cache>.)
  • <region> element. Defines the data region used for the example and specifies all non-default region configuration settings.
    • This region is configured as a replicate, meaning that any data either application writes into it is sent automatically to the other application's cache.
    • The region also has a listener installed named SimpleCacheListener.
HelloWorld.xml
<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC
    "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.5//EN" 
"http://www.gemstone.com/dtd/cache6_5.dtd">
<cache>
	<region name="exampleRegion" refid="REPLICATE">
		<cache-listener>
			<class-name>helloworld.SimpleCacheListener</class-name>
		</cache-listener>
	</region>
</cache>

helloworld/HelloWorldProducer.java and helloworld/HelloWorldConsumer.java

Purpose

Java applications that use the GemFire distributed caching API to connect to other applications and share data in memory.

The example programs HelloWorldConsumer.java and HelloWorldProducer.java are in GemFire's helloworld examples package of classes. They both use the GemFire Cache, CacheFactory, and Region APIs.

Example programs common package and import declarations

(Not shown: the consumer program also imports a couple of Java APIs for detecting keystrokes.)

package helloworld;

import com.gemstone.gemfire.cache.Cache;
import com.gemstone.gemfire.cache.CacheFactory;
import com.gemstone.gemfire.cache.Region;
Creating caches and connecting to each other

When they start, both programs create their cache, specifying the XML file to use. The cache creation automatically creates the distributed system using the gemfire.properties file settings. The distributed system is what connects the two programs to each other.

Cache cache = new CacheFactory()
      .set("cache-xml-file", "xml/HelloWorld.xml")
      .create();
Getting the data region

The programs get the example region that was declared in the XML file.

Region<String,String> exampleRegion = cache.getRegion("exampleRegion");
Working in the cache

The producer puts data into the region and reports its activities to standard output.

    System.out.println("Putting entry: Hello, World");
    exampleRegion.put("Hello", "World");
    System.out.println("Putting entry: Hello, Moon!");
    exampleRegion.put("Hello", "Moon!");

Because of how their data regions are configured in the XML file, the data put by the producer is automatically pushed to the consumer's cache.

The consumer application code does nothing with the data, but its region's listener handles the data events.

Closing the cache and disconnecting
cache.close();

helloworld/SimpleCacheListener.java

Purpose

GemFire Java application plug-in written to handle cache region events. You can code application plug-ins to respond to a variety of events in the GemFire system. This listener is installed on the region in both applications, through the XML file declarations.

SimpleCacheListener, afterCreate, and afterUpdate callbacks

This is the code that is called when the entry is put into the cache.

public void afterCreate(EntryEvent<K,V> e) {
	System.out.println("    Received afterCreate event for entry: " +
		e.getKey() + ", " + e.getNewValue());
}
public void afterUpdate(EntryEvent<K,V> e) {
	System.out.println("    Received afterUpdate event for entry: " +
		e.getKey() + ", " + e.getNewValue());
}
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.