5. Bootstrapping GemFire through the Spring Container

Spring Data GemFire provides full configuration and initialization of the GemFire data grid through Spring's IoC container and provides several classes that simplify the configuration of GemFire components including Caches, Regions, WAN Gateways, Persistence Backup, and other Distributed System components to support a variety of scenarios with minimal effort.

[Note]Note

This section assumes basic familiarity with GemFire. For more information see the product documentation.

5.1 Advantages of using Spring over GemFire cache.xml

As of release 1.2.0, Spring Data GemFire's XML namespace supports full configuration of the data grid. In fact, the Spring Data GemFire namespace is considered the preferred way to configure GemFire. GemFire will continue to support native cache.xml for legacy reasons, but you can now do everything in Spring XML and take advantage of the many wonderful things Spring has to offer such as modular XML configuration, property placeholders, SpEL, and environment profiles. Behind the namespace, Spring Data GemFire makes extensive use of Spring's FactoryBean pattern to simplify the creation and initialization of GemFire components.

For example, GemFire provides several callback interfaces such as CacheListener, CacheWriter, and CacheLoader to allow developers to add custom event handlers. Using the Spring IoC container, these may configured as normal Spring beans and injected into GemFire components. This is a significant improvement over native cache.xml which provides relatively limited configuration options and requires callbacks to implement GemFire's Declarable interface (see Section 6.6, “Wiring Declarable components” to see how you can still use Declarables within Spring's DI container).

In addition, IDEs such as the Spring Tool Suite (STS) provide excellent support for Spring XML namespaces, such as code completion, pop-up annotations, and real time validation, making them easy to use.

5.2 Using the Core Spring Data GemFire Namespace

To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components. It is also possible to configure the beans directly through Spring's standard <bean> definition. However, as of Spring Data GemFire 1.2.0, all bean properties are exposed via the namespace so there is little benefit to using raw bean definitions. For more information about XML Schema-based configuration in Spring, see this appendix in the Spring Framework reference documentation.

[Note]Note

Spring Data Repository support uses a separate XML namespace. See Chapter 9, GemFire Repositories for more information on how to configure GemFire Repositories.

To use the Spring Data GemFire namespace, simply declare it in your Spring XML configuration meta-data:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlxsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:1gfe="http://www.springframework.org/schema/gemfire"2
  xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        3http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
     
    <bean id ... >

    4<gfe:cache ...>

</beans>

1

Spring GemFire namespace prefix. Any name will do but through out the reference documentation, gfe will be used.

2

The namespace URI.

3

The namespace URI location. Note that even though the location points to an external address (which exists and is valid), Spring will resolve the schema locally as it is included in the Spring Data GemFire library.

4

Declaration example for the GemFire namespace. Notice the prefix usage.

Once declared, the namespace elements can be declared simply by appending the aforementioned prefix.

[Note]Note

It is possible to change the default namespace, for example from beans to gfe. This is useful for configuration composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="1http://www.springframework.org/schema/gemfire"
    xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
 2
 xmlns:beans="http://www.springframework.org/schema/beans"
 xsi:schemaLocation="
     http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
     http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
     
    3<beans:bean id ... >
 
    4<cache ...>

</beans>

1

The default namespace declaration for this XML file points to the Spring Data GemFire namespace.

2

The beans namespace prefix declaration.

3

Bean declaration using the beans namespace. Notice the prefix.

4

Bean declaration using the gfe namespace. Notice the lack of prefix (as the default namespace is used).

5.3 Configuring the GemFire Cache

In order to use GemFire, one needs to either create a new Cache or connect to an existing one. In the current version of GemFire, there can be only one opened cache per VM (or per classloader to be technically correct). In most cases the cache is created once.

[Note]Note
This section describes the creation and configuration of a full cache member, appropriate for peer to peer cache topologies and cache servers. A full cache is also commonly used for standalone applications, integration tests and proofs of concept. In a typical production system, most application processes will act as cache clients and will create a ClientCache instance instead. This is described in the sections Section 5.3.3, “Configuring a GemFire Client Cache” and Section 5.5.11, “Client Region”

A cache with default configuration can be created with a very simple declaration:

<gfe:cache/>

A Spring application context containing this definition will, upon initialization, will register a CacheFactoryBean to create a Spring bean named gemfireCache referencing a GemFire Cache instance. This will be either an existing cache, or if one does not exist, a newly created one. Since no additional properties were specified, a newly created cache will apply the default cache configuration.

All Spring Data GemFire components which depend on the Cache respect this naming convention so that there is no need to explicitly declare the Cache dependency. If you prefer, you can make the dependence explicit via the cache-ref attribute provided by various namespace elements. Also you can easily override the Cache's bean name:

<gfe:cache id="my-cache"/>

Starting with Spring Data GemFire 1.2.0, The GemFire Cache may be fully configured using Spring. However, GemFire's native XML configuration file (e.g., cache.xml) is also supported. For scenarios in which the GemFire cache needs to be configured natively, simply provide a reference the GemFire configuration file using the cache-xml-location attribute:

<gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml"/>

In this example, if the cache needs to be created, it will use the file named cache.xml located in the classpath root.

[Note]Note

Note that the configuration makes use of Spring's Resource abstraction to locate the file. This allows various search patterns to be used, depending on the runtime environment or the prefix specified (if any) in the resource location.

In addition to referencing an external configuration file one can specify GemFire properties using any of Spring's common properties support features. For example, one can use the properties element defined in the util namespace to define properties directly or load properties from properties files. The latter is recommended for externalizing environment specific settings outside the application configuration:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:gfe="http://www.springframework.org/schema/gemfire"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
        
     <gfe:cache properties-ref="props"/>
 
     <util:properties id="props" location="file:/vfabric/gemfire/gemfire.properties"/>
</beans>
[Note]Note

The cache settings apply only if a new cache needs to be created. If an open cache already exists in the JVM, these settings will be ignored.

5.3.1 Advanced Cache Configuration

For advanced cache configuration, the cache element provides a number of configuration options exposed as attributes or child elements

1
<gfe:cache
        copy-on-read="true"
        critical-heap-percentage="70" 
        eviction-heap-percentage="60"
        lock-lease="120"
        lock-timeout="60"
        pdx-serializer="myPdxSerializer"
        pdx-disk-store="diskStore"
        pdx-ignore-unread-fields="true"
        pdx-persistent="true"
        pdx-read-serialized="false"
        message-sync-interval="1"
        search-timeout="300"
        close="false"
        lazy-init="true"
    >
     2<gfe:transaction-listener ref="myTransactionListener"/> 

     3<gfe:transaction-writer>
        <bean class="org.springframework.data.gemfire.example.TransactionListener"/>
      </gfe:transaction-writer>
      
     4<gfe:dynamic-region-factory/>
     5<gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/>
</gfe:cache>
    

1

Various cache options are supported by attributes. For further information regarding anything shown in this example, please consult the GemFire product documentation

The close attribute determines if the cache should be closed when the Spring application context is closed. The default is true however for cases in which multiple application contexts use the cache (common in web applications), set this value to false.

The lazy-init attribute determines if the cache should be initialized before another bean references it. The default is true however in some cases it may be convenient to set this value to false.

2

An example of a TransactionListener callback declaration using a bean reference. The referenced bean must implement TransactionListener

3

An example of a TransactionWriter callback declaration using an inner bean declaration this time. The bean must implement TransactionWriter

4

Enable GemFire's DynamicRegionFactory

5

Declares a JNDI binding to enlist an external datasource in a GemFire transaction

[Note]Note
The use-bean-factory-locator attribute (not shown) deserves a mention. The factory bean responsible for creating the cache uses an internal Spring type called a BeanFactoryLocator to enable user classes declared in GemFire's native cache.xml to be registered as Spring beans. The BeanFactoryLocator implementation also permits only one bean definition for a cache with a given id. In certain situations, such as running JUnit integration tests from within Eclipse, it is necessary to disable the BeanFactoryLocator by setting this value to false to prevent an exception. This exception may also arise during JUnit tests running from a build script. In this case the test runner should be configured to fork a new JVM for each test (in maven, set <forkmode>always</forkmode>) . Generally there is no harm in setting this value to false.

Enabling PDX Serialization

The example above includes a number of attributes related to GemGire's enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX is enabled by registering a PDX serializer which is done via the pdx-serializer attribute. GemFire provides an implementation class com.gemstone.gemfire.pdx.ReflectionBasedAutoSerializer, however it is common for developers to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements the required interface. More information on serialization support can be found in Chapter 7, Working with GemFire Serialization

5.3.2 Configuring a GemFire Cache Server

In Spring Data GemFire 1.1 dedicated support for configuring a CacheServer was added, allowing complete configuration through the Spring container:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:gfe="http://www.springframework.org/schema/gemfire"
  xmlns:context="http://www.springframework.org/schema/context"	
  xsi:schemaLocation="http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
  http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

  <gfe:cache />

  <!-- Advanced example depicting various cache server configuration options -->
  <gfe:cache-server id="advanced-config" auto-startup="true"
       bind-address="localhost" port="${gfe.port.6}" host-name-for-clients="localhost"
       load-poll-interval="2000" max-connections="22" max-threads="16"
       max-message-count="1000" max-time-between-pings="30000"  
       groups="test-server">

     <gfe:subscription-config eviction-type="ENTRY" capacity="1000" disk-store="file://${java.io.tmpdir}"/>
   </gfe:cache-server>

   <context:property-placeholder location="classpath:cache-server.properties"/>

</beans>

The configuration above illustrates the cache-server element and the many options available.

[Note]Note

Rather than hard-coding the port, this configuration uses Spring's context namespace to declare a property-placeholder. The property placeholder reads one or more properties file and then replaces property placeholders with values at runtime. This allows administrators to change such values without having to touch the main application configuration. Spring also provides SpEL and the environment abstraction one to support externalization of environment specific properties from the main code base, easing the deployment across multiple machines.

[Note]Note

To avoid initialization problems, the CacheServers started by Spring Data GemFire will start after the container has been fully initialized. This allows potential regions, listeners, writers or instantiators defined declaratively to be fully initialized and registered before the server starts accepting connections. Keep this in mind when programmatically configuring these items as the server might start after your components and thus not be seen by the clients connecting right away.

5.3.3 Configuring a GemFire Client Cache

Another configuration addition in Spring Data GemFire 1.1 is the dedicated support for configuring ClientCache. This is similar to a cache in both usage and definition and supported by org.springframework.data.gemfire.clientClientCacheFactoryBean.

<beans>
    <gfe:client-cache />   
</beans>

client-cache supports much of the same options as the cache element. However as opposed to a full cache, a client cache connects to a remote cache server through a pool. By default a pool is created to connect to a server on localhost port 40404. The the default pool is used by all client regions unless the region is configured to use a different pool.

Pools can be defined through the pool element; The client side pool can be used to configure connectivity to the server for individual entities or for the entire cache. For example, to customize the default pool used by client-cache, one needs to define a pool and wire it to cache definition:

<beans>
  <gfe:client-cache id="simple" pool-name="my-pool"/>

  <gfe:pool id="my-pool" subscription-enabled="true">
     <gfe:locator host="${locatorHost}" port="${locatorPort}"/>
 </gfe:pool>
</beans>

The <client-cache> tag also includes a ready-for-events attribute. If set to true, the client cache initialization will include ClientCache.readyForEvents().

Client side configuration is covered in more detail in Section 5.5.11, “Client Region”.

5.4 Using the GemFire Data Access Namespace

In addition to the core gfe namespace, Spring Data GemFire provides a gfe-data namespace intended primarily to simplify the development of GemFire client applications. This namespace currently supports for GemFire repositories and function execution and a <datasource> tag that offers a convenient way to connect to the data grid.

5.4.1 An Easy Way to Connect to GemFire

For many applications, A basic connection to a GemFire grid, using default values is sufficient. Spring Data GemFire's <datasource> tag provides a simple way to access data. The data source creates a client cache and connection pool. In addition, it will query the member servers for all existing root regions and create a proxy (empty) client region for each one.

<gfe-data:datasource>
   <locator host="somehost" port="1234"/>
</gfe-data:datasource>

The datasource tag is synactically similar to <gfe:pool>. It may be configured with one or more locator or server tags to connect to an existing data grid. Additionally, all attributes available to configure a pool are supported. This configuration will automatically create ClientRegion beans for each region defined on members connected to the locator, so they may be seamlessly referenced by Spring Data mapping annotations, GemfireTemplate, and wired into application classes.

Of course, you can explicitly configure client regions. For example, if you want to cache data in local memory:

<gfe-data:datasource>
   <locator host="somehost" port="1234"/>
</gfe-data:datasource>

<gfe:client-region id="Customer" shortcut="CACHING_PROXY"/>

5.5 Configuring a GemFire Region

A region is required to store and retrieve data from the cache. Region is an interface extending java.util.Map and enables basic data access using familiar key-value semantics. The Region interface is wired into classes that require it so the actual region type is decoupled from the programming model . Typically each region is associated with one domain object, similar to a table in a relational database.

GemFire implements the following types of regions:

  • Replicated - Data is replicated across all cache members that define the region. This provides very high read performance but writes take longer to perform the replication.

  • Partioned - Data is partitioned into buckets among cache members that define the region. This provides high read and write performance and is suitable for very large data sets that are too big for a single node.

  • Local - Data only exists on the local node.

  • Client - Technically a client region is a local region that acts as a proxy to a replicated or partitioned region hosted on cache servers. It may hold data created or fetched locally. Alternately, it can be empty. Local updates are synchronized to the cache server. Also, a client region may subscribe to events in order to stay synchronized with changes originating from remote processes that access the same region.

For more information about the various region types and their capabilities as well as configuration options, please refer to the GemFire Developer's Guide and community site.

5.5.1 Using an externally configured Region

For referencing regions already configured through GemFire native configuration, e.g. a cache.xml file, use the lookup-region element. Simply declare the target region name with thename attribute; for example, to declare a bean definition named region-bean for an existing region named Orders one can use the following bean definition:

<gfe:lookup-region id="region-bean" name="Orders"/>

If the name is not specified, the bean's id will be used. The example above becomes:

<!-- lookup for a region called 'Orders' -->
<gfe:lookup-region id="Orders"/>
[Note]Note

If the region does not exist, an initialization exception will be thrown. For configuring new GemFire regions, proceed to the appropriate sections below.

Note, in the previous examples, since no cache name was defined, the default naming convention (gemfireCache) was used. Alternately, one can reference the cache bean through the cache-ref attribute:

<gfe:cache id="cache"/>
<gfe:lookup-region id="region-bean" name="Orders" cache-ref="cache"/>

The lookup-region provides a simple way of retrieving existing, pre-configured regions without exposing the region semantics or setup infrastructure.

5.5.2 Configuring Regions

Spring Data GemFire provides comprehensive support for configuring any type of GemFire Region via the following elements:

  • Local Region <local-region>

  • Replicated Region <replicated-region>

  • Partitioned Region <partitioned-region>

  • Client Region <client-region>

For a comprehensive description of Region types please consult the GemFire product documentation.

Common Region Attributes

The following table(s) list attributes available for various region types:

Table 5.1. Common Region Attributes

NameValuesDescription
cache-ref GemFire Cache bean name The name of the bean defining the GemFire Cache (by default 'gemfireCache').
close boolean, default:false (Note: The default was true prior to 1.3.0) Indicates whether the Region should be closed at shutdown.
concurrency-checks-enables boolean, default:true Determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed Regions.
data-policy See GemFire's Data Policy The Region's Data Policy. Note, not all Data Policies are supported for every Region type.
destroy boolean, default:false Indicates whether the Region should be destroyed at shutdown.
disk-store-ref The name of a configured Disk Store. A reference to a bean created via the disk-store element.
disk-synchronous boolean, default:false Indicates whether Disk Store writes are synchronous.
enable-gateway boolean, default:false Indicates whether the Region will synchronize entries over a WAN Gateway.
hub-id The name of the Gateway Hub. This will automatically set enable-gateway to true. If enable-gateway is explicitly set to false, an exception will be thrown.
id Any valid bean name. Will also be the Region name by default.
ignore-if-exists boolean, default:false Ignores this bean definition configuration if the Region already exists in the GemFire Cache, resulting in a lookup instead.
ignore-jta boolean, default:false Indicates whether the Region participates in JTA transactions.
index-update-type synchronous or asynchronous, default:asynchronous Indicates whether indices will be updated synchronously or asynchronously on entry creation.
initial-capacity integer, default:16 The initial memory allocation for number of Region entries.
key-constraint Any valid, fully-qualified Java class name. The expected key type.
name Any valid Region name. The name of the Region definition. If not specified, it will assume the value of the id attribute (the bean name).
persistent boolean, default:false Indicates whether the Region persists entries to a Disk Store (disk).
statistics boolean, default:false Indicates whether the Region reports statistics.
value-constraint Any valid, fully-qualified Java class name. The expected value type.


Cache Listeners

Cache Listeners are registered with a region to handle region events such as entries being created, updated, destroyed, etc. A Cache Listener can be any bean that implements the CacheListener interface. A region may have multiple listeners, declared using the cache-listener element enclosed in a *-region element. In the example below, there are two CacheListeners declared. The first references a top-level named Spring bean; the second is an anonymous inner bean definition.

<gfe:replicated-region id="region-with-listeners">
    <gfe:cache-listener>
        <!-- nested cache listener reference -->
        <ref bean="c-listener"/>
        <!-- nested cache listener declaration -->
        <bean class="some.pkg.AnotherSimpleCacheListener"/>
    </gfe:cache-listener>

    <bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
 </gfe:replicated-region>
    

The following example uses an alternate form of the cache-listener element with a ref attribute. This allows for more concise configuration for a single cache listener. Note that the namespace only allows a single cache-listener element so either the style above or below must be used.

[Caution]Caution

Using ref and a nested declaration in a cache-listener, or similar element, is illegal. The two options are mutually exclusive and using both on the same element will result in an exception.

<beans>
    <gfe:replicated-region id="region-with-one listener">
        <gfe:cache-listener ref="c-listener"/>
    </gfe:replicated-region>

    <bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
 </beans>
    
[Note]Bean Reference Conventions

The cache-listener element is an example of a common pattern used in the namespace anywhere GemFire provides a callback interface to be implemented in order to invoke custom code in response to cache or region events. Using Spring's IoC container, the implementation is a standard Spring bean. In order to simplify the configuration, the schema allows a single occurrence of the cache-listener element, but it may contain nested bean references and inner bean definitions in any combination if multiple instances are permitted. The convention is to use the singular form (i.e., cache-listener vs cache-listeners) reflecting that the most common scenario will in fact be a single instance. We have already seen examples of this pattern in the advanced cache configuration example.

Cache Loaders and Cache Writers

Similar to cache-listener, the namespace provides cache-loader and cache-writer elements to register these respective components for a region. A CacheLoader is invoked on a cache miss to allow an entry to be loaded from an external data source, a database for example. A CacheWriter is invoked after an entry is created or updated, intended for synchronizing to an external data source. The difference is GemFire only supports at most a single instance of each for each region. However, either declaration style may be used. See CacheLoader and CacheWriter for more details.

Subregions

In Release 1.2.0, Spring Data GemFire added support for subregions, allowing regions to be arranged in a hierarchical relationship. For example, GemFire allows for a /Customer/Address region and a different /Employee/Address region. Additionally, a subregion may have it's own subregions and its own configuration. A subregion does not inherit attributes from the parent region. Regions types may be mixed and matched subject to GemFire constraints. A subregion is naturally declared as a child element of a region. The subregion's name attribute is the simple name. The above example might be configured as:

<beans>

    <gfe:replicated-region name="Customer">
        <gfe:replicated-region name="Address"/>
    </gfe:replicated-region>

    <gfe:replicated-region name="Employee">
        <gfe:replicated-region name="Address"/>
    </gfe:replicated-region>

</beans>

Note that the id attribute is not permitted for a subregion. The subregions will be created with bean names /Customer/Address and /Employee/Address, respectively. So they may be injected using the full path name into other beans that use them, such as GemfireTemplate. The full path should also be used in OQL query strings.

5.5.3 A Word of Caution on Regions, Subregions and Lookups

Prior to Spring Data GemFire 1.4, one of the underlying properties of the high-level replicated-region, partitioned-region, local-region and client-region elements in Spring Data GemFire's XML namespace, which correspond to GemFire's Region types based on Data Policy, is that these elements perform a lookup first before attempting to create the region. This is done in case the region already exists, which might be the case if the region was defined in GemFire's native configuration, e.g. cache.xml, thereby avoiding any errors. This was by design, though subject to change.

[Caution]Caution

The Spring team highly recommends that the replicated-region, partitioned-region, local-region and client-region elements be strictly used only for defining new regions. One of the problems with these elements doing a lookup first is, if the developer assumed that defining a bean definition for a REPLICATE region would create a new region, however, consequently a region with the same name already exists having different semantics for eviction, expiration, subscription and/or other attributes, this could adversely affect application logic and/or expectations thereby violating application requirements.

[Important]Important

Recommended Practice - Only use the replicated-region, partitioned-region, local-region and client-region XML namespace elements for defining new regions.

However, because the high-level region elements perform a lookup first, this can cause problems for dependency injected region resources to application code, like DAOs or Repositories.

Take for instance the following native GemFire configuration file (e.g. cachel.xml)...

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cache PUBLIC  "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN"
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache>
    <region name="Customers" refid="REPLICATE">
	    <region name="Accounts" refid="REPLICATE">
		    <region name="Orders" refid="REPLICATE">
			    <region name="Items" refid="REPLICATE"/>
            </region>
        </region>
    </region>
</cache>
	

Also, consider that you might have defined a DAO as follows...

public class CustomerAccountDao extends GemDaoSupport {

    @Resource(name = "Customers/Accounts")
    private Region customersAccounts;

    ...
}
	

Here, we are injecting a reference to the Customers/Accounts GemFire Region in our DAO. As such, it is not uncommon for a developer to define beans for all or some of these regions in Spring XML configuration meta-data as follows...

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
          xmlns:gfe="http://www.springframework.org/schema/gemfire"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
">

    <gfe:cache cache-xml-location="classpath:cache.xml"/>

    <gfe:lookup-region name="Customers/Accounts"/>
    <gfe:lookup-region name="Customers/Accounts/Orders"/>
</beans>
	

Here the Customers/Accounts and Customers/Accounts/Orders GemFire Regions are referenced as beans in the Spring context as "Customers/Accounts" and "Customers/Accounts/Orders", respectively. The nice thing about using the lookup-region element and the corresponding syntax above is that it allows a developer to reference a subregion directly without unnecessarily defining a bean for the parent region (e.g. Customers).

However, if now the developer changes his/her configuration meta-data syntax to using the nested format, like so...

<gfe:lookup-region name="Customers">
    <gfe:lookup-region name="Accounts">
        <gfe:lookup-region name="Orders"/>
    </gfe:lookup-region>
</gfe:lookup-region>
	

Or, perhaps the developer erroneously chooses to use the high-level replicated-region element, which will do a lookup first, as in...

<gfe:replicated-region name="Customers" persistent="true">
    <gfe:replicated-region name="Accounts" persistent="true">
        <gfe:replicated-region name="Orders" persistent="true"/>
    </gfe:replicated-region>
</gfe:replicated-region>
	

Then the region beans defined in the Spring context will consist of the following: { "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }. This means the dependency injected reference (i.e. @Resource(name = "Customers/Accounts")) is now broken since no bean with name "Customers/Accounts" is defined.

GemFire is flexible in referencing both parent regions and subregions. The parent can be referenced as "/Customers" or "Customers" and the child as "/Customers/Accounts" or just "Customers/Accounts". However, Spring Data GemFire is very specific when it comes to naming beans after regions, typically always using the forward slash (/) to represents subregions (e.g. "/Customers/Accounts").

Therefore, it is recommended that users use either the nested lookup-region syntax as illustrated above, or define direct references with a leading forward slash (/) like so...

<gfe:lookup-region name="/Customers/Accounts"/>
<gfe:lookup-region name="/Customers/Accounts/Orders"/>
	

The example above where the nested replicated-region elements were used to reference the subregions serves to illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? Not, since the regions were defined in native GemFire configuration (i.e. cache.xml) and will exist by the time the cache is initialized, or once the <gfe:cache> bean is created. Since the high-level region XML namespace abstractions, like replicated-region, perform the lookup first, it uses the regions as defined in the cache.xml configuration file.

5.5.4 Data Persistence

Regions can be made persistent. GemFire ensures that all the data you put into a region that is configured for persistence will be written to disk in a way that it can be recovered the next time you create the region. This allows data to be recovered after a machine or process failure or after an orderly shutdown and restart of GemFire.

To enable persistence with Spring Data GemFire, simply set the persistent attribute to true:

<gfe:partitioned-region id="persitent-partition" persistent="true"/>
[Important]Important

Persistence for partitioned regions is supported from GemFire 6.5 onwards - configuring this option on a previous release will trigger an initialization exception.

Persistence may also be configured using the data-policy attribute, set to one of GemFire's data policy settings. For instance...

<gfe:partitioned-region id="persitent-partition" data-policy="PERSISTENT_PARTITION"/>

The data policy must match the region type and must also agree with the persistent attribute if explicitly set. An initialization exception will be thrown if, for instance, the persistent attribute is set to false, yet a persistent data policy was specified.

When persisting regions, it is recommended to configure the storage through the disk-store element for maximum efficiency. The diskstore is referenced using the disk-store-ref attribute. Additionally, the region may perform disk writes synchronously or asynchronously:

<gfe:partitioned-region id="persitent-partition" persistent="true" disk-store-ref="myDiskStore" disk-synchronous="true"/>

This is discussed further in Section 5.7, “Configuring a Disk Store”

5.5.5 Subscription Interest Policy

GemFire allows configuration of subscriptions to control peer to peer event handling. Spring Data GemFire provides a <gfe:subscription/> to set the interest policy on replicated and partitioned regions to either ALL or CACHE_CONTENT.

<gfe:partitioned-region id="subscription-partition">
     <gfe:subscription type="CACHE_CONTENT"/>
</gfe:partitioned-region>

5.5.6 Data Eviction and Overflowing

Based on various constraints, each region can have an eviction policy in place for evicting data from memory. Currently, in GemFire, eviction applies to the least recently used entry (also known as LRU). Evicted entries are either destroyed or paged to disk (also known as overflow).

Spring Data GemFire supports all eviction policies (entry count, memory and heap usage) for both partitioned-region and replicated-region as well as client-region, through the nested eviction element. For example, to configure a partition to overflow to disk if its size is more then 512 MB, one could use the following configuration:

<gfe:partitioned-region id="overflow-partition">
     <gfe:eviction type="MEMORY_SIZE" threshold="512" action="OVERFLOW_TO_DISK"/>
</gfe:partitioned-region>
[Important]Important

Replicas cannot use a local destroy eviction since that would invalidate them. See the GemFire docs for more information.

When configuring regions for overflow, it is recommended to configure the storage through the disk-store element for maximum efficiency.

For a detailed description of eviction policies, see the GemFire documentation (such as this page).

5.5.7 Data Expiration

GemFire allows you to control how long entries exist in the cache. Eviction is driven by elapsed time, as opposed to eviction which is driven by memory usage. Once an entry expires it may no longer be accessed from the cache. GemFire supports the following expiration types:
  • Time to live (TTL) - The amount of time, in seconds, the object may remain in the cache after the last creation or update. For entries, the counter is set to zero for create and put operations. Region counters are reset when the region is created and when an entry has its counter reset.

  • Idle timeout - The amount of time, in seconds, the object may remain in the cache after the last access. The idle timeout counter for an object is reset any time its TTL counter is reset. In addition, an entry’s idle timeout counter is reset any time the entry is accessed through a get operation or a netSearch . The idle timeout counter for a region is reset whenever the idle timeout is reset for one of its entries.

Each of these may be applied to the region itself or entries in the region. Spring Data GemFire provides <region-ttl>, <region-tti>, <entry-ttl> and <entry-tti> region child elements to specify timeout values and expiration actions.

5.5.8 Local Region

Spring Data GemFire offers a dedicated local-region element for creating local regions. Local regions, as the name implies, are standalone meaning they do not share data with any other distributed system member. Other than that, all common region configuration options are supported. A minimal declaration looks as follows (again, the example relies on the Spring Data GemFire namespace naming conventions to wire the cache):

<gfe:local-region id="myLocalRegion" />

Here, a local region is created (if one doesn't exist already). The name of the region is the same as the bean id (myLocalRegion) and the bean assumes the existence of a GemFire cache named gemfireCache.

5.5.9 Replicated Region

One of the common region types is a replicated region or replica. In short, when a region is configured to be a replicated region, every member that hosts that region stores a copy of the region's entries locally. Any update to a replicated region is distributed to all copies of the region. When a replica is created, it goes through an initialization stage in which it discovers other replicas and automatically copies all the entries. While one replica is initializing you can still continue to use the other rep

Spring Data GemFire offers a replicated-region element. A minimal declaration looks as follows. All common configuration options are available for replicated regions.

<gfe:replicated-region id="simpleReplica" />

5.5.10 Partitioned Region

Another region type supported out of the box by the Spring Data GemFire namespace is the partitioned region. To quote the GemFire docs:

"A partitioned region is a region where data is divided between peer servers hosting the region so that each peer stores a subset of the data. When using a partitioned region, applications are presented with a logical view of the region that looks like a single map containing all of the data in the region. Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of the operation. [...] GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster."

A partition is created using the partitioned-region element. Its configuration options are similar to that of the replicated-region plus the partion specific features such as the number of redundant copies, total maximum memory, number of buckets, partition resolver and so on. Below is a quick example on setting up a partition region with 2 redundant copies:

<!-- bean definition named 'distributed-partition' backed by a region named 'redundant' with 2 copies
and a nested resolver declaration  -->
<gfe:partitioned-region id="distributed-partition" copies="2" total-buckets="4" name="redundant">
    <gfe:partition-resolver>
        <bean class="some.pkg.SimplePartitionResolver"/>
    </gfe:partition-resolver>
</gfe:partitioned-region>

partitioned-region Options

The following table offers a quick overview of configuration options specific to partitioned regions. These are in addition to the common region configuration options described above.

Table 5.2. partitioned-region options

NameValuesDescription
partition-resolver bean name The name of the partitioned resolver used by this region, for custom partitioning.
partition-listener bean name The name of the partitioned listener used by this region, for handling partition events.
copies0..4The number of copies for each partition for high-availability. By default, no copies are created meaning there is no redundancy. Each copy provides extra backup at the expense of extra storage.
colocated-with valid region name The name of the partitioned region with which this newly created partitioned region is colocated.
local-max-memory positive integer The maximum amount of memory, in megabytes, to be used by the region in this process.
total-max-memory any integer value The maximum amount of memory, in megabytes, to be used by the region in all processes.
recovery-delay any long value The delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes. -1 (the default) indicates that redundancy will not be recovered after a failure.
startup-recovery-delay any long value The delay in milliseconds that new members will wait before satisfying redundancy. -1 indicates that adding new members will not trigger redundancy recovery. The default is to recover redundancy immediately when a new member is added.

5.5.11 Client Region

GemFire supports various deployment topologies for managing and distributing data. The topic is outside the scope of this documentation however to quickly recap, they can be classified in short in: peer-to-peer (p2p), client-server, and wide area cache network (or WAN). In the last two scenarios, it is common to declare client regions which connect to a cache server. Spring Data GemFire offers dedicated support for such configuration through Section 5.3.3, “Configuring a GemFire Client Cache”, client-region and pool elements. As the names imply, the former defines a client region while the latter defines connection pools to be used/shared by the various client regions.

Below is a typical client region configuration:

<!-- client region using the default client-cache pool -->
<gfe:client-region id="simple">
    <gfe:cache-listener ref="c-listener"/>
</gfe:client-region>

<!-- region using its own dedicated pool -->
<gfe:client-region id="complex" pool-name="gemfire-pool">
    <gfe:cache-listener ref="c-listener"/>
</gfe:client-region>

<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>

<!-- pool declaration -->
<gfe:pool id="gemfire-pool" subscription-enabled="true">
    <gfe:locator host="someHost" port="40403"/>
</gfe:pool>

As with the other region types, client-region supports CacheListeners as well as a single CacheLoader or CacheWriter. It also requires a connection pool for connecting to a server. Each client can have its own pool or they can share the same one.

[Note]Note
In the above example, the pool is configured with a locator. The locator is a separate process used to discover cache servers in the distributed system and are recommended for production systems. It is also possible to configure the pool to connect directly to one or more cache servers using the server element.

For a full list of options to set on the client and especially on the pool, please refer to the Spring Data GemFire schema (Appendix A, Spring Data GemFire Schema) and the GemFire documentation.

Client Interests

To minimize network traffic, each client can define its own 'interest', pointing out to GemFire, the data it actually needs. In Spring Data GemFire, interests can be defined for each client, both key-based and regular-expression-based types being supported; for example:

<gfe:client-region id="complex" pool-name="gemfire-pool">
    <gfe:key-interest durable="true" result-policy="KEYS">
        <bean id="key" class="java.lang.String">
             <constructor-arg value="someKey" />
        </bean>
    </gfe:key-interest>
    <gfe:regex-interest pattern=".*" receive-values="false"/>
</gfe:client-region>

A special key ALL_KEYS means interest is registered for all keys (identical to a regex interest of .*). The receive-values attribute indicates whether or not the values are received for create and update events. If true, values are received; if false, only invalidation events are received - refer to the GemFire documentation for more details.

5.5.12 JSON Support

Gemfire 7.0 introduced support for caching JSON documents with OQL query support. These are stored internally as PdxInstance types using the JSONFormatter to perform conversion to and from JSON strings. Spring Data GemFire provides a <gfe-data:json-region-autoproxy/> tag to enable a Spring AOP component to advise appropropriate region operations, effectively encapsulating the JSONFormatter, allowing your application to work directly with JSON strings. In addition, Java objects written to JSON configured regions will be automatically converted to JSON using the Jackson ObjectMapper. Reading these values will return a JSON string.

By default, <gfe-data:json-region-autoproxy/> will perform the conversion on all regions. To apply this feature to selected regions, provide a comma delimited list of their ids via the region-refs attribute. Other attributes include a pretty-print flag (false by default) and convert-returned-collections. By default the results of region operations getAll() and values() will be converted for configured regions. This is done by creating a parallel structure in local memory. This can incur significant overhead for large collections. Set this flag to false to disable automatic conversion for these operation.

[Note]Note
Certain region operations, specifically those that use GemFire's proprietary Region.Entry such as entries(boolean), entrySet(boolean) and getEntry() type are not targeted for AOP advice. In addition, the entrySet() method which returns a Set<java.util.Map.Entry<?,?>> is not affected.
     <gfe-data:json-region-autoproxy pretty-print="true" region-refs="myJsonRegion" convert-returned-collections="true"/>
    

This feature also works with seamlessly with GemfireTemplate operations, provided that the template is declared as a Spring bean. Currently native QueryService operations are not supported.

5.6 Creating an Index

GemFire allows creation on indexes (or indices) to improve the performance of (common) queries. Spring Data GemFire allows indecies to be declared through the index element:

<gfe:index id="myIndex" expression="someField" from="/someRegion"/>

Before creating an index, Spring Data GemFire will verify whether one with the same name already exists. If it does, it will compare the properties and if they don't match, will remove the old one to create a new one. If the properties match, Spring Data GemFire will simply return the index (in case it does not exist it will simply create one). To prevent the update of the index, even if the properties do not match, set the property override to false.

Note that index declaration are not bound to a region but rather are top-level elements (just like gfe:cache). This allows one to declare any number of indecies on any region whether they are just created or already exist - an improvement versus the GemFire cache.xml. By default the index relies on the default cache declaration but one can customize it accordingly or use a pool (if need be) - see the namespace schema for the full set of options.

5.7 Configuring a Disk Store

As of Release 1.2.0, Spring Data GemFire supports disk store configuration via a top level disk-store element.

[Note]Note

Prior to Release 1.2.0, disk-store was a child element of *-region. If you have regions configured with disk storage using a prior release of Spring Data GemFire and want to upgrade to the latest release, move the disk-store element to the top level, assign an id and use the region's disk-store-ref attribute. Also, disk-synchronous is now a region level attribute.

<gfe:disk-store id="diskStore1" queue-size="50" auto-compact="true" 
        max-oplog-size="10" time-interval="9999">
        <gfe:disk-dir location="/gemfire/store1/" max-size="20"/>
        <gfe:disk-dir location="/gemfire/store2/" max-size="20"/>
</gfe:disk-store>

Disk stores are used by regions for file system persistent backup or overflow storage of evicted entries, and persistent backup of WAN gateways. Note that multiple components may share the same disk store. Also multiple directories may be defined for a single disk store. Please refer to the GemFire documentation for an explanation of the configuration options.

5.8 Configuring GemFire's Function Service

As of Release 1.3.0, Spring Data GemFire provides annotation support for implementing and registering functions. Spring Data GemFire also provides namespace support for registering GemFire Functions for remote function execution. Please refer to the GemFire documentation for more information on the function execution framework. Functions are declared as Spring beans and must implement the com.gemstone.gemfire.cache.execute.Function interface or extend com.gemstone.gemfire.cache.execute.FunctionAdapter. The namespace uses a familiar pattern to declare functions:

<gfe:function-service>
  <gfe:function>
      <bean class="com.company.example.Function1"/>
      <ref bean="function2"/>
  </gfe:function>
</gfe:function-service>
    
<bean id="function2" class="com.company.example.Function2"/>

5.9 Configuring WAN Gateways

WAN gateways provide a way to synchronize GemFire distributed systems across geographic distributed areas. As of Release 1.2.0, Spring Data GemFire provides namespace support for configuring WAN gateways as illustrated in the following examples:

5.9.1 WAN Configuration in GemFire 7.0

GemFire 7.0 introduces new APIs for WAN configuration. While the original APIs provided in GemFire 6 are still supported, it is recommended that you use the new APIs if you are using GemFire 7.0. The Spring Data GemFire namespace supports either. In the example below, GatewaySenders are configured for a partitioned region by adding child elements to the region (gateway-sender and gateway-sender-ref). The GatewaySender may register EventFilters and TransportFilters. Also shown below is an example configuration of an AsyncEventQueue which must also be wired into a region (not shown).

<gfe:partitioned-region id="region-inner-gateway-sender" >
    <gfe:gateway-sender 
        remote-distributed-system-id="1">
            <gfe:event-filter>
                <bean class="org.springframework.data.gemfire.example.SomeEventFilter"/>
            </gfe:event-filter>
            <gfe:transport-filter>
                <bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
            </gfe:transport-filter>
    </gfe:gateway-sender>
    <gfe:gateway-sender-ref bean="gateway-sender"/>
</gfe:partitioned-region>
    
<gfe:async-event-queue id="async-event-queue" batch-size="10" persistent="true" disk-store-ref="diskstore" 
         maximum-queue-memory="50">
    <gfe:async-event-listener>
        <bean class="org.springframework.data.gemfire.example.SomeAsyncEventListener"/>
    </gfe:async-event-listener>
</gfe:async-event-queue>
        
    
<gfe:gateway-sender id="gateway-sender" remote-distributed-system-id="2">
    <gfe:event-filter>
         <ref bean="event-filter"/>
         <bean class="org.springframework.data.gemfire.example.SomeEventFilter"/>
    </gfe:event-filter>
    <gfe:transport-filter>
         <ref bean="transport-filter"/>
         <bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
     </gfe:transport-filter>
</gfe:gateway-sender>
   
<bean id="event-filter" class="org.springframework.data.gemfire.example.AnotherEventFilter"/>
<bean id="transport-filter" class="org.springframework.data.gemfire.example.AnotherTransportFilter"/>
    

On the other end of a GatewaySender is a corresponding GatewayReceiver to receive gateway events. The GatewayReceiver may also be configured with EventFilters and TransportFilters.

<gfe:gateway-receiver id="gateway-receiver" 
    start-port="12345" end-port="23456" bind-address="192.168.0.1">
        <gfe:transport-filter>
            <bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
        </gfe:transport-filter>
</gfe:gateway-receiver>

Please refer to the GemFire product document for a detailed explanation of all the configuration options.

5.9.2 WAN Configuration in GemFire 6.6

<gfe:cache/>

<gfe:replicated-region id="region-with-gateway" enable-gateway="true" hub-id="gateway-hub"/>

<gfe:gateway-hub id="gateway-hub" manual-start="true">
    <gfe:gateway gateway-id="gateway">
         <gfe:gateway-listener>
             <bean class="com.company.example.MyGatewayListener"/>
         </gfe:gateway-listener>
         <gfe:gateway-queue maximum-queue-memory="5" batch-size="3" 
                batch-time-interval="10" />
     </gfe:gateway>

     <gfe:gateway gateway-id="gateway2">
         <gfe:gateway-endpoint port="1234" host="host1" endpoint-id="endpoint1"/>
         <gfe:gateway-endpoint port="2345" host="host2" endpoint-id="endpoint2"/>
    </gfe:gateway>
</gfe:gateway-hub>

A region may synchronize all or part of its contents to a gateway hub used to access one or more remote systems. The region must set enable-gateway to true and specify the hub-id.

[Note]Note

If just a hub-id is specified, Spring Data GemFire automatically assumes that the gateway should be enabled.

Please refer to the GemFire product document for a detailed explanation of all the configuration options.