To configure a GemFire cache, create a Spring bean definition file and add the Spring GemFire namespace. In STS (Figure 14-3), select the project and open the context menu (right-click) and select New→Spring Bean Configuration File. Give it a name and click Next.

Figure 14-3. Create a Spring bean definition file in STS

In the XSD namespaces view, select the gfe namespace (Figure 14-4).

Click Finish to open the bean definition file in an XML editor with the correct namespace declarations. (See Example 14-1.)

Figure 14-4. Selecting Spring XML namespaces

<?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"
       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">  
   
   <gfe:cache/>

</beans>

Now use the gfe namespace to add a cache element. That’s it! This simple cache declaration will create an embedded cache, register it in the Spring ApplicationContext as gemfireCache, and initialize it when the context is created.

You can easily change the bean name by setting the id attribute on the cache element. However, all other namespace elements assume the default name unless explicitly overridden using the cache-ref attribute. So you can save yourself some work by following the convention.

The cache element provides some additional attributes, which STS will happily suggest if you press Ctrl-Space. The most significant is the properties-ref attribute. In addition to the API, GemFire exposes a number of global configuration options via external properties. By default, GemFire looks for a file called gemfire.properties in all the usual places: the user’s home directory, the current directory, and the classpath. While this is convenient, it may result in unintended consequences if you happen to have these files laying around. Spring alleviates this problem by offering several better alternatives via its standard property loading mechanisms. For example, you can simply construct a java.util.Properties object inline or load it from a properties file located on the classpath or filesystem. Example 14-2 uses properties to configure GemFire logging.

<util:properties id="props">
   <prop key="log-level">info</prop>
   <prop key="log-file">gemfire.log</prop>
</util:properties>
  
<gfe:cache properties-ref="props" />

<util:properties id="props" location="gemfire-cache.properties" />

<gfe:cache properties-ref="props" />

Note the use of Spring’s util namespace to create a Properties object. This is related to, but not the same as, Spring’s property placeholder mechanism, which uses token-based substitution to allow properties on any bean to be defined externally from a variety of sources. Additionally, the cache element includes a cache-xml-location attribute to enable the cache to be configured with GemFire’s native configuration schema. As previously noted, this is mostly there for legacy reasons.

The cache element also provides some pdx-* attributes required to enable and configure GemFire’s proprietary serialization feature (PDX). We will address PDX in Repository Usage.

For advanced cache configuration, the cache element provides additional attributes for tuning memory and network communications (shown in Figure 14-5) and child elements to register callbacks such as TransactionListers, and TransactionWriters (Figure 14-6).

Figure 14-5. Displaying a list of cache attributes in STS

Figure 14-6. Displaying a list of child elements in STS

As mentioned in the chapter opener, GemFire provides a few types of regions. The XML namespace defines replicated-region, partitioned-region, local-region, and client-region elements to create regions. Again, this does not cover all available features but highlights some of the more common ones. A simple region declaration, as shown in Example 14-3, is all you need to get started.

<gfe:cache/>
<gfe:replicated-region id="Customer" />

<gfe:cache id="gemfireCache" />
<gfe:replicated-region id="Customer" cache-ref="gemfireCache" />

Typically, GemFire is deployed as a distributed data grid, hosting replicated or partitioned regions on cache servers. Client applications use client regions to access data. For development and integration testing, it is a best practice to eliminate any dependencies on an external runtime environment. You can do this by simply declaring a replicated or local region with an embedded cache, as is done in the sample code. Spring environment profiles are extremely useful in configuring GemFire for different environments.

In Example 14-4, the dev profile is intended for integration testing, and the prod profile is used for the deployed cache configuration. The cache and region configuration is transparent to the application code. Also note the use of property placeholders to specify the locator hosts and ports from an external properties file. Cache client configuration is discussed further in Cache Client Configuration.

<beans profile="dev">
  <gfe:cache/>
  <gfe:replicated-region id="Customer" />
</beans>

<beans profile="prod">
  <context:properties-placeholder location="client-app.properties" />
  <gfe:client-cache pool-name="pool" />
  
  <gfe:client-region id="Customer" />
  
  <gfe:pool id="pool">
    <gfe:locator host="${locator.host.1}" port="${locator.port.1}"/>
    <gfe:locator host="${locator.host.2}" port="${locator.port.2}"/>
 </gfe:pool>
</beans>

As shown in Figure 14-7, there are a number of common region configuration options as well as specific options for each type of region. For example, you can configure all regions to back up data to a local disk store synchronously or asynchronously.

Figure 14-7. Displaying replicated region attributes in STS

Additionally, you may configure regions to synchronize selected entries over a WAN gateway to distribute data over a wide geographic area. You may also register CacheListeners, CacheLoaders, and CacheWriters to handle region events. Each of these interfaces is used to implement a callback that gets invoked accordingly. A CacheListener is a generic event handler invoked whenever an entry is created, updated, destroyed, etc. For example, you can write a simple CacheListener to log cache events, which is particularly useful in a distributed environment (see Example 14-5). A CacheLoader is invoked whenever there is a cache miss (i.e., the requested entry does not exist), allowing you to “read through” to a database or other system resource. A CacheWriter is invoked whenever an entry is updated or created to provide “write through” or “write behind” capabilities.

public class LoggingCacheListener extends CacheListenerAdapter {
  
  private static Log log = LogFactory.getLog(LoggingCacheListener.class);
 
  @Override
  public void afterCreate(EntryEvent event) {
     String regionName = event.getRegion().getName();
     Object key = event.getKey();
     Object newValue = event.getNewValue();
     log.info("In region [" + regionName + "] created key ["
       + key + "] value [" + newValue + "]");
   }

   @Override
   public void afterDestroy(EntryEvent event) {
    …
   }

   @Override
   public void afterUpdate(EntryEvent event) {
    …
   }
}

Other options include expiration, the maximum time a region or an entry is held in the cache, and eviction, policies that determine which items are removed from the cache when the defined memory limit or the maximum number of entries is reached. Evicted entries may optionally be stored in a disk overflow.

You can configure partitioned regions to limit the amount of local memory allocated to each partition node, define the number of buckets used, and more. You may even implement your own PartitionResolver to control how data is colocated in partition nodes.

In a client server configuration, application processes are cache clients—that is, they produce and consume data but do not distribute it directly to other processes. Neither does a cache client implicitly see updates performed by remote processes. As you might expect by now, this is entirely configurable. Example 14-6 shows a basic client-side setup using a client-cache, client-region, and a pool. The client-cache is a lightweight implementation optimized for client-side services, such as managing one or more client regions. The pool represents a connection pool acting as a bridge to the distributed system and is configured with any number of locators.

<gfe:client-cache pool-name="pool" />

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

<gfe:pool id="pool">
  <gfe:locator host="${locator.host.1}" port="${locator.port.1}"/>
  <gfe:locator host="${locator.host.2}" port="${locator.port.2}"/>
</gfe:pool>

You can configure the pool to control thread allocation for connections and network communications. Of note is the subscription-enabled attribute, which you must set to true to enable synchronizing region entry events originating from remote processes (Example 14-7).

<gfe:client-region id="Customer">
   <gfe:key-interest durable="false" receive-values="true" />
</client-region>

<gfe:pool id="pool" subcription-enabled="true">
  <gfe:locator host="${locator.host.1}" port="${locator.port.1}"/>
  <gfe:locator host="${locator.host.2}" port="${locator.port.2}"/>
</gfe:pool>

With subscriptions enabled, the client-region may register interest in all keys or specific keys. The subscription may be durable, meaning that the client-region is updated with any events that may have occurred while the client was offline. Also, it is possible to improve performance in some cases by suppressing transmission of values unless explicitly retrieved. In this case, new keys are visible, but the value must be retrieved explicitly with a region.get(key) call, for example.

Spring also allows you to create and initialize a cache server process simply by declaring the cache and region(s) along with an additional cache-server element to address server-side configuration. To start a cache server, simply configure it using the namespace and start the application context, as shown in Example 14-8.

public static void main(String args[]) {
   new ClassPathXmlApplicationContext("cache-config.xml");
}

Figure 14-8 shows a Spring-configured cache server hosting two partitioned regions and one replicated region. The cache-server exposes many parameters to tune network communications, system resources, and the like.

Figure 14-8. Configuring a cache server

WAN configuration is required for geographically distributed systems. For example, a global organization may need to share data across the London, Tokyo, and New York offices. Each location manages its transactions locally, but remote locations need to be synchronized. Since WAN communications can be very costly in terms of performance and reliability, GemFire queues events, processed by a WAN gateway to achieve eventual consistency. It is possible to control which events get synchronized to each remote location. It is also possible to tune the internal queue sizes, synchronization scheduling, persistent backup, and more. While a detailed discussion of GemFire’s WAN gateway architecture is beyond the scope of this book, it is important to note that WAN synchronization must be enabled at the region level. See Example 14-9 for a sample configuration.

<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="..."/>
    </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>

This example shows a region enabled for WAN communications using the APIs available in GemFire 6 versions. The enable-gateway attribute must be set to true (or is implied by the presence of the hub-id attribute), and the hub-id must reference a gateway-hub element. Here we see the gateway-hub configured with two gateways. The first has an optional GatewayListener to handle gateway events and configures the gateway queue. The second defines two remote gateway endpoints.

GemFire allows you to configure disk stores for persistent backup of regions, disk overflow for evicted cache entries, WAN gateways, and more. Because a disk store may serve multiple purposes, it is defined as a top-level element in the namespace and may be referenced by components that use it. Disk writes may be synchronous or asynchronous.

For asynchronous writes, entries are held in a queue, which is also configurable. Other options control scheduling (e.g., the maximum time that can elapse before a disk write is performed or the maximum file size in megabytes). In Example 14-10, an overflow disk store is configured to store evicted entries. For asynchronous writes, it will store up to 50 entries in a queue, which will be flushed every 10 seconds or if the queue is at capacity. The region is configured for eviction to occur if the total memory size exceeds 2 GB. A custom ObjectSizer is used to estimate memory allocated per entry.

<gfe:partitioned-region id="partition-data" persistent="true" disk-store-ref="ds2">
  <gfe:eviction type="MEMORY_SIZE" threshold="2048" action="LOCAL_DESTROY">
  <gfe:object-sizer>
    <bean class="org.springframework.data.gemfire.SimpleObjectSizer" />
  </gfe:object-sizer>
  </gfe:eviction>
</gfe:partitioned-region>
    
<gfe:disk-store id="ds2" queue-size="50" auto-compact="true" 
     max-oplog-size="10" time-interval="10000">
  <gfe:disk-dir location="/gemfire/diskstore" />
</gfe:disk-store>

Since GemFire regions require a unique key for each object, the top-level domain objects—Customer, Order, and Product—all inherit from AbstractPersistentEntity, which defines an id property (Example 14-13).

import org.springframework.data.annotation.Id;
 
public class AbstractPersistentEntity {
  
  @Id
  private final Long id; 
}

Each domain object is annotated with @Region. By convention, the region name is the same as the simple class name; however, we can override this by setting the annotation value to the desired region name. This must correspond to the region name—that is, the value of id attribute or the name attribute, if provided, of the region element. Common attributes, such as @PersistenceConstructor (shown in Example 14-14) and @Transient, work as expected.

@Region
public class Product extends AbstractPersistentEntity {

  private String name, description;
  private BigDecimal price;
  private Map<String, String> attributes = new HashMap<String, String>();

  @PersistenceConstructor
  public Product(Long id, String name, BigDecimal price, String description) {
    
    super(id);
    Assert.hasText(name, "Name must not be null or empty!");
    Assert.isTrue(BigDecimal.ZERO.compareTo(price) < 0, "Price must be greater than zero!");

    this.name = name;
    this.price = price;
    this.description = description;
}

GemFire repositories support basic CRUD and query operations, which we define using Spring Data’s common method name query mapping mechanism. In addition, we can configure a repository method to execute any OQL query using @Query, as shown in Example 14-15.

public interface ProductRepository extends CrudRepository<Product, Long> {

  List<Product> findByDescriptionContaining(String description);

  /**
   * Returns all {@link Product}s having the given attribute value.
   * @param attribute
   * @param value
   * @return
   */
  @Query("SELECT * FROM /Product where attributes[$1] = $2")
  List<Product> findByAttributes(String key, String value);

  List<Product> findByName(String name);
}

You can enable repository discovery using a dedicated gfe-data namespace, which is separate from the core gfe namespace. Alternatively, if you’re using Java configuration, simply annotate your configuration class with @EnableGemfireRepositories, as shown in Example 14-16.

<gfe-data:repositories base-package="com.oreilly.springdata.gemfire" />

PDX is GemFire’s proprietary serialization library. It is highly efficient, configurable, interoperable with GemFire client applications written in C# or C++, and supports object versioning. In general, objects must be serialized for operations requiring network transport and disk persistence. Cache entries, if already serialized, are stored in serialized form. This is generally true with a distributed topology. A standalone cache with no persistent backup generally does not perform serialization.

If PDX is not enabled, Java serialization will be used. In this case, your domain classes and all nontransient properties must implement java.io.Serializable. This is not a requirement for PDX. Additionally, PDX is highly configurable and may be customized to optimize or enhance serialization to satisfy your application requirements.

Example 14-17 shows how to set up a GemFire repository to use PDX.

<gfe:cache pdx-serializer="mapping-pdx-serializer" />

<bean id="mapping-pdx-serializer" 
      class="org.springframework.data.gemfire.mapping.MappingPdxSerializer" />

The MappingPdxSerializer is automatically wired with the default mapping context used by the repositories. One limitation to note is that each cache instance can have only one PDX serializer, so if you’re using PDX for repositories, it is advisable to set up a dedicated cache node (i.e., don’t use the same process to host nonrepository regions).