1 Introduction To The GemFire Plugin

This user guide describes details on configuring and using GemFire specifically in the context of a Grails application. Complete documentation on GemFire is available at http://www.gemstone.com/products/gemfire.

1.1 Installing Gemfire

Installing GemFire

If you plan to use Gemfire only in peer-2-peer mode then you can skip this installation. If you want to use Gemfire in client/server mode then follow these instructions to install Gemfire:

1. Register at the SpringSource GemFire download site to access the download.

The registration process is quick and helps us help you later if you have questions or problems. The product includes an evaluation license.

1. Install GemFire Enterprise 6.5 according to the instructions on the download site.

You can also get GemFire from your salesperson.

Configure your environment for GemFire.

1. Set the JAVA_HOME environment variable to point to your Java runtime installation. (There should be a bin directory under JAVA_HOME.)
2. Set the GEMFIRE environment variable to point to your GemFire installation top-level directory. (There should be bin, lib, dtd, and other directories under GEMFIRE.)
3. Configure GF_JAVA and your PATH and CLASSPATH as shown in these examples. (GF_JAVA must point to the java executable file under your JAVA_HOME.)

Unix Bourne and Korn shells (sh, ksh, bash)

GF_JAVA=$JAVA_HOME/bin/java;export GF_JAVA
PATH=$PATH:$JAVA_HOME/bin:$GEMFIRE/bin;export PATH
CLASSPATH=$GEMFIRE/lib/gemfire.jar:$GEMFIRE/lib/antlr.jar:$GEMFIRE/lib/gfSecurityImpl.jar:$CLASSPATH;export CLASSPATH

Windows

set GF_JAVA=%JAVA_HOME%binjava.exe
set PATH=%PATH%;%JAVA_HOME%bin;%GEMFIRE%bin
set CLASSPATH=%GEMFIRE%libgemfire.jar;%GEMFIRE%libantlr.jar;%GEMFIRE%libgfSecurityImpl.jar;%CLASSPATH%

2 Cache Regions

2.1 Cache Region Configuration

The code below declares 2 regions with the names region1 and region2.

// grails-app/conf/Config.groovy
grails.gemfire.regions = {
    // declare region1
    region1()
    // declare region2
    region2()
}

Regions may be configured with a syntax like this:

// grails-app/conf/Config.groovy
import com.gemstone.gemfire.cache.DataPolicy
grails.gemfire.regions = {
    region1 {
        // configure region1…
        dataPolicy = DataPolicy.REPLICATE
        publisher = false
    }
    region2 {
        // configure region2…
        dataPolicy = DataPolicy.PARTITION
    }
}

The DSL supports all of the configuration attributes which are supported by the AttributesFactory.

The DSL provides some syntax to simplify the configuration and eliminate explicit references to GemFire classes like DataPolicy. The previous example could be written like this:

// grails-app/conf/Config.groovy
grails.gemfire.regions = {
    region1 {
        // configure region1…
        dataPolicy = REPLICATE
        publisher = false
    }
    region2 {
        // configure region2…
        dataPolicy = PARTITION
    }
}

The following table lists all of the properties which may be referenced directly without a class prefix.

Several properties require an instance of the ExpirationAttributes class. These include regionTimeToLive, regionIdleTimeout, entryTimeToLive and entryIdleTimeout. Configuring those properties might look something like this:

// grails-app/conf/Config.groovy
import com.gemstone.gemfire.cache.ExpirationAction
import com.gemstone.gemfire.cache.ExpirationAttributes
grails.gemfire.regions = {
    region1 {
        entryTimeToLive = new ExpirationAttributes(120)
        entryTimeToIdle = new ExpirationAttributes(200, ExpirationAction.DESTROY)
    }
}

The DSLS allows the explicit references to the ExpirationAction and ExpirationAttributes classes to be removed.

// grails-app/conf/Config.groovy
grails.gemfire.regions = {
    region1 {
        entryTimeToLive = expirationAttributes(120)
        entryTimeToIdle = expirationAttributes(200, DESTROY)
    }
}

2.2 Accesing Cache Regions

If a region were configured like this:

// grails-app/conf/Config.groovy
grails.gemfire.regions = {
    departmentData {
        entryTimeToLive = expirationAttributes(120)
    }
}

It could be accessed like this:

// grails-app/controllers/com/demo/ReportingController.groovy
package com.demo
class ReportingController {
    def departmentData
    def index = {
        def hrData = departmentData['hr']
        def accountData = departmentData['accounting']
        // …
    }
    def addToCache = {
        def key = params.key
        def value = params.value
        departmentData[key] = value
        redirect action: 'list'
    }
    // …
}

3 Cache Servers

• Grid computing
• Continuous querying
• Advanced data partitioning

In order to use client/server mode you need to install gemfire as per the documentation.

This plugin provides scripts to start up cache servers and locators.

To startup cache servers you can use the start-cache-server command.

grails start-cache-server server1

You can stop a server again using the stop-cache-server command:

grails stop-cache-server server1

The port of the server is automatically assigned. If you want to specify the port, locator server or multicast options there are more advanced arguments:

grails start-cache-server server1 --locators=localhost[4111] --port=41112 --mcast-port=0

If the multicast port (mcast-port) option is set to 0 then multicast is disabled. If you disable multicast then you will need to setup a locator server.

You can setup a locator by running the start-locator command:

grails start-locator

This will start the locator on port 55221 by default. If you wish to start the locator service on a different port you can use:

grails start-locator --port=4111

A locator is responsible for looking up the location of cache servers. If you don't use a locator then the default multicast lookup will happen.

3.1 Cache Server Clients

// grails-app/conf/Config.groovy
grails.gemfire.servers = {    
	myServer {
		properties = ['log-level': 'warning']
		pool {
			addServer "localhost", 4111
			setMinConnections 1
			setMaxConnections 20
			setRetryAttempts 10
			setSubscriptionEnabled true
		}
	}
}

The example above using a single cache server. If you plan to use multiple cache servers then you can specify one or many locators.

// grails-app/conf/Config.groovy
grails.gemfire.servers = {    
	myServer {
		properties = ['log-level': 'warning']
		pool {
			addLocator "localhost", 4111
			setMinConnections 1
			setMaxConnections 20
			setRetryAttempts 10
			setSubscriptionEnabled true
		}
	}
}

If you want to use continuous queries make sure that subscriptionEnabled is set to true on the pool. For all the configuration options see the PoolFactory API in the Gemfire documentation