For many applications, a basic connection to a Pivotal GemFire data grid using default values is sufficient. Spring Data for Pivotal GemFire’s <datasource> tag provides a simple way to access data. The data source creates a ClientCache and connection Pool. In addition, it queries the cluster servers for all existing root Regions and creates an (empty) client Region proxy for each one.

The <datasource> tag is syntactically similar to <gfe:pool>. It may be configured with one or more nested locator or server elements to connect to an existing data grid. Additionally, all attributes available to configure a Pool are supported. This configuration automatically creates client Region beans for each Region defined on cluster members connected to the Locator, so they can be seamlessly referenced by Spring Data mapping annotations (GemfireTemplate) and autowired into application classes.

Of course, you can explicitly configure client Regions. For example, if you want to cache data in local memory, as the following example shows:

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

Spring Data for Pivotal GemFire includes dedicated support for configuring a CacheServer, allowing complete configuration through the Spring container, as the following example shows:

The preceding configuration shows the cache-server element and the many available options.

In addition to defining a Pivotal GemFire peer Cache, Spring Data for Pivotal GemFire also supports the definition of a Pivotal GemFire ClientCache in a Spring container. A ClientCache definition is similar in configuration and use to the Pivotal GemFire peer Cache and is supported by the org.springframework.data.gemfire.client.ClientCacheFactoryBean.

The simplest definition of a Pivotal GemFire cache client using default configuration follows:

client-cache supports many of the same options as the Cache element. However, as opposed to a full-fledged peer Cache member, a cache client connects to a remote cache server through a Pool. By default, a Pool is created to connect to a server running on localhost and listening to port 40404. The default Pool is used by all client Regions unless the Region is configured to use a specific Pool.

Pools can be defined with the pool element. This client-side Pool can be used to configure connectivity directly to a server for individual entities or for the entire cache through one or more Locators.

For example, to customize the default Pool used by the client-cache, the developer needs to define a Pool and wire it to the cache definition, as the following example shows:

The <client-cache> element also has a ready-for-events attribute. If the attribute is set to true, the client cache initialization includes a call to ClientCache.readyForEvents().

Client Region covers client-side configuration in more detail.

To reference Regions already configured in a Pivotal GemFire native cache.xml file, use the lookup-region element. Simply declare the target Region name with the name attribute. For example, to declare a bean definition identified as ordersRegion for an existing Region named Orders, you can use the following bean definition:

If name is not specified, the bean’s id will be used as the name of the Region. The example above becomes:

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

lookup-region lets you retrieve existing, pre-configured Regions without exposing the Region semantics or setup infrastructure.

auto-region-lookup lets you import all Regions defined in a Pivotal GemFire native cache.xml file into a Spring ApplicationContext when you use the cache-xml-location attribute on the <gfe:cache> element.

For instance, consider the following cache.xml file:

You can import the preceding cache.xml file as follows:

You can then use the <gfe:lookup-region> element (for example, <gfe:lookup-region id="Parent"/>) to reference specific Regions as beans in the Spring container, or you can choose to import all Regions defined in cache.xml by using the following:

Spring Data for Pivotal GemFire automatically creates beans for all Pivotal GemFire Regions defined in cache.xml that have not been explicitly added to the Spring container with explicit <gfe:lookup-region> bean declarations.

It is important to realize that Spring Data for Pivotal GemFire uses a Spring BeanPostProcessor to post-process the cache after it is both created and initialized to determine the Regions defined in Pivotal GemFire to add as beans in the Spring ApplicationContext.

You may inject these "auto-looked-up" Regions as you would any other bean defined in the Spring ApplicationContext, with one exception: You may need to define a depends-on association with the ‘gemfireCache’ bean, as follows:

The preceding example only applies when you use Spring’s component-scan functionality.

If you declare your components by using Spring XML config, then you would do the following:

Doing so ensures that the Pivotal GemFire cache and all the Regions defined in cache.xml get created before any components with auto-wire references when using the <gfe:auto-region-lookup> element.

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

See the Pivotal GemFire documentation for a comprehensive description of Region Types.

Pivotal GemFire Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid global GCs. When you enable compression for a Region, all values stored in memory for the Region are compressed, while keys and indexes remain uncompressed. New values are compressed when put into the Region and all values are decompressed automatically when read back from the Region. Values are not compressed when persisted to disk or when sent over the wire to other peer members or clients.

The following example shows a Region with compression enabled:

See Pivotal GemFire’s documentation for more information on Region Compression.

Pivotal GemFire Regions may also be configured to store Region values in off-heap memory, which is a portion of JVM memory that is not subject to Garbage Collection (GC). By avoid expensive GC cycles, your application can spend more of its time on things that matter, like processing requests.

Using off-heap memory is as simple as declaring the amount of memory to use and then enabling your Regions to use off-heap memory, as shown in the following configuration:

You can control other aspects of off-heap memory management by setting the following Pivotal GemFire configuration properties using the <gfe:cache> element:s

Pivotal GemFire’s ResourceManager will use these two threshold values (critical-off-heap-percentage & eviction-off-heap-percentage) to more effectively manage the off-heap memory in much the same way as the JVM does when managing heap memory. Pivotal GemFire ResourceManager will prevent the cache from consuming too much off-heap memory by evicting old data. If the off-heap manager is unable to keep up, then the ResourceManager refuses additions to the cache until the off-heap memory manager has freed up an adequate amount of memory.

See Pivotal GemFire’s documentation for more information on Managing Heap and Off-Heap Memory.

Specifically, read the section, Managing Off-Heap Memory.

Spring Data for Pivotal GemFire also supports Sub-Regions, allowing Regions to be arranged in a hierarchical relationship.

For example, Pivotal GemFire allows for a /Customer/Address Region and a different /Employee/Address Region. Additionally, a Sub-Region may have its own Sub-Regions and configuration. A Sub-Region does not inherit attributes from its parent Region. Regions types may be mixed and matched subject to Pivotal GemFire constraints. A Sub-Region is naturally declared as a child element of a Region. The Sub-Region’s name attribute is the simple name. The preceding example might be configured as follows:

Note that the Monospaced ([id]) attribute is not permitted for a Sub-Region. Sub-Regions are created with bean names (/Customer/Address and /Employee/Address, respectively, in this case). So they may be injected into other application beans, such as a GemfireTemplate, that need them by using the full path name of the Region. The full pathname of the Region should also be used in OQL query strings.

Spring Data for Pivotal GemFire also supports Region templates.

This feature allows developers to define common Region configuration and attributes once and reuse the configuration among many Region bean definitions declared in the Spring ApplicationContext.

Spring Data for Pivotal GemFire includes five Region template tags in its namespace:

In addition to the tags, concrete <gfe:*-region> elements (along with the abstract <gfe:*-region-template> elements) have a template attribute used to define the Region template from which the Region inherits its configuration. Region templates may even inherit from other Region templates.

The following example shows one possible configuration:

Region templates work for Sub-Regions as well. Notice that 'TemplateBasedPartitionRegion' extends 'PartitionRegionTemplate', which extends 'ExtendedRegionTemplate', which extends 'BaseRegionTemplate'. Attributes and sub-elements defined in subsequent, inherited Region bean definitions override what is in the parent.

Based on various constraints, each Region can have an eviction policy in place for evicting data from memory. Currently, in Pivotal GemFire, eviction applies to the Least Recently Used entry (also known as LRU). Evicted entries are either destroyed or paged to disk (referred to as “overflow to disk”).

Spring Data for Pivotal GemFire supports all eviction policies (entry count, memory, and heap usage) for PARTITION Regions, REPLICATE Regions, and client, local Regions by using the nested eviction element.

For example, to configure a PARTITION Region to overflow to disk if the memory size exceeds more than 512 MB, you can specify the following configuration:

When configuring Regions for overflow, you should configure the storage through the disk-store element for maximum efficiency.

For a detailed description of eviction policies, see the Pivotal GemFire documentation on Eviction.

Pivotal GemFire lets you control how long entries exist in the cache. Expiration is driven by elapsed time, as opposed to eviction, which is driven by the entry count or heap or memory usage. Once an entry expires, it may no longer be accessed from the cache.

Pivotal GemFire supports the following expiration types:

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

The following example shows a PARTITION Region with expiration values set:

For a detailed description of expiration policies, see the Pivotal GemFire documentation on expiration.

Regions can be persistent. Pivotal GemFire ensures that all the data you put into a Region that is configured for persistence is written to disk in a way that is recoverable the next time you recreate the Region. Doing so lets data be recovered after machine or process failure or even after an orderly shutdown and subsequent restart of the Pivotal GemFire data node.

To enable persistence with Spring Data for Pivotal GemFire, set the persistent attribute to true on any of the <*-region> elements, as the following example shows:

Persistence may also be configured by setting the data-policy attribute. To do so, set the attribute’s value to one of Pivotal GemFire’s DataPolicy settings, as the following example shows:

The DataPolicy must match the Region type and must also agree with the persistent attribute if it is also explicitly set. If the persistent attribute is set to false but a persistent DataPolicy was specified (such as PERSISTENT_REPLICATE or PERSISTENT_PARTITION), an initialization exception is thrown.

For maximum efficiency when persisting Regions, you should configure the storage through the disk-store element. The DiskStore is referenced by using the disk-store-ref attribute. Additionally, the Region may perform disk writes synchronously or asynchronously. The following example shows a synchronous DiskStore:

This is discussed further in Configuring a DiskStore.

Pivotal GemFire allows configuration of peer-to-peer (P2P) event messaging to control the entry events that the Region receives. Spring Data for Pivotal GemFire provides the <gfe:subscription/> sub-element to set the subscription policy on REPLICATE and PARTITION Regions to either ALL or CACHE_CONTENT. The following example shows a region with its subscription policy set to CACHE_CONTENT:

Spring Data for Pivotal GemFire offers a dedicated local-region element for creating local Regions. Local Regions, as the name implies, are standalone, meaning that they do not share data with any other distributed system member. Other than that, all common Region configuration options apply.

The following example shows a minimal declaration (again, the example relies on the Spring Data for Pivotal GemFire XML namespace naming conventions to wire the cache):

In the preceding example, a local Region is created (if a Region by the same name does not already exist). The name of the Region is the same as the bean ID (exampleLocalRegion), and the bean assumes the existence of a Pivotal GemFire cache named gemfireCache.

One of the common Region types is a REPLICATE Region or “replica”. In short, when a Region is configured to be a REPLICATE, every member that hosts the Region stores a copy of the Region’s entries locally. Any update to a REPLICATE 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 replicas.

All common configuration options are available for REPLICATE Regions. Spring Data for Pivotal GemFire offers a replicated-region element. The following example shows a minimal declaration:

See Pivotal GemFire’s documentation on Distributed and Replicated Regions for more details.

The Spring Data for Pivotal GemFire XML namespace also supports PARTITION Regions.

To quote the Pivotal 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. Pivotal 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 Region is created by using the partitioned-region element. Its configuration options are similar to that of the replicated-region with the addition of partition-specific features, such as the number of redundant copies, total maximum memory, number of buckets, partition resolver, and so on.

The following example shows how to set up a PARTITION Region with two redundant copies:

See Pivotal GemFire’s documentation on Partitioned Regions for more details.

Pivotal GemFire supports various deployment topologies for managing and distributing data. The topic of Pivotal GemFire topologies is beyond the scope of this documentation. However, to quickly recap, Pivotal GemFire’s supported topologies can be classified as: peer-to-peer (p2p), client-server, and wide area network (WAN). In the last two configurations, it is common to declare client Regions that connect to a cache server.

Spring Data for Pivotal GemFire offers dedicated support for each configuration through its client-cache elements: client-region and pool. As the names imply, client-region defines a client Region, while pool defines a Pool of connections used and shared by the various client Regions.

The following example shows a typical client Region configuration:

As with the other Region types, client-region supports CacheListener instances as well as a CacheLoader and a CacheWriter. It also requires a connection Pool for connecting to a set of either Locators or servers. Each client Region can have its own Pool, or they can share the same one. If a Pool is not specified, then the "DEFAULT" Pool will be used.

For a full list of options to set on the client and especially on the Pool, see the Spring Data for Pivotal GemFire schema (“Spring Data for Pivotal GemFire Schema”) and Pivotal GemFire’s documentation on Client-Server Configuration.

Pivotal GemFire has support for caching JSON documents in Regions, along with the ability to query stored JSON documents using the Pivotal GemFire OQL (Object Query Language). JSON documents are stored internally as PdxInstance types by using the JSONFormatter class to perform conversion to and from JSON documents (as a String).

Spring Data for Pivotal GemFire provides the <gfe-data:json-region-autoproxy/> element to enable an AOP component to advise appropriate, proxied Region operations, which effectively encapsulates the JSONFormatter, thereby letting your applications work directly with JSON Strings.

In addition, Java objects written to JSON configured Regions are automatically converted to JSON using Jackson’s ObjectMapper. When these values are read back, they are returned as a JSON String.

By default, <gfe-data:json-region-autoproxy/> performs the conversion for all Regions. To apply this feature to selected Regions, provide a comma-delimited list of Region bean IDs in the region-refs attribute. Other attributes include a pretty-print flag (defaults to false) and convert-returned-collections.

Also, by default, the results of the getAll() and values() Region operations are converted for configured Regions. This is done by creating a parallel data structure in local memory. This can incur significant overhead for large collections, so set the convert-returned-collections to false if you would like to disable automatic conversion for these Region operations.

The following example configuration shows how to set the pretty-print and convert-returned-collections attributes:

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

In addition to creating indexes up front as Index bean definitions are processed by Spring Data for Pivotal GemFire on Spring container initialization, you may also define all of your application indexes prior to creating them by using the define attribute, as follows:

When define is set to true (it defaults to false), it does not actually create the Index at that moment. All “defined” Indexes are created all at once, when the Spring ApplicationContext is “refreshed” or, to put it differently, when a ContextRefreshedEvent is published by the Spring container. Spring Data for Pivotal GemFire registers itself as an ApplicationListener listening for the ContextRefreshedEvent. When fired, Spring Data for Pivotal GemFire calls QueryService.createDefinedIndexes().

Defining indexes and creating them all at once boosts speed and efficiency when creating indexes.

See “Creating Multiple Indexes at Once” for more details.

Two Spring Data for Pivotal GemFire Index configuration options warrant special mention: ignoreIfExists and override.

These options correspond to the ignore-if-exists and override attributes on the <gfe:index> element in Spring Data for Pivotal GemFire’s XML namespace, respectively.

Each option significantly differs in behavior and entirely depends on the type of Pivotal GemFire Index exception thrown. This also means that neither option has any effect if a Pivotal GemFire Index-type exception is not thrown. These options are meant to specifically handle Pivotal GemFire IndexExistsException and IndexNameConflictException instances, which can occur for various, sometimes obscure reasons. The exceptions have the following causes:

Spring Data for Pivotal GemFire’s default behavior is to fail-fast, always. So, neither Index Exception are “handled” by default. These Index exceptions are wrapped in a SDG GemfireIndexException and rethrown. If you wish for Spring Data for Pivotal GemFire to handle them for you, you can set either of these Index bean definition options to true.

IgnoreIfExists always takes precedence over Override, primarily because it uses fewer resources, simply because it returns the “existing” Index in both exceptional cases.

With the cache-based Snapshot Service (that is, a CacheSnapshotService) you would typically pass it a directory containing all the snapshot files to load rather than individual snapshot files, as the overloaded load method in the CacheSnapshotService API indicates.

However, Spring Data for Pivotal GemFire recognizes that a typical developer workflow might be to extract and export data from one environment into several snapshot files, zip all of them up, and then conveniently move the zip file to another environment for import.

Therefore, Spring Data for Pivotal GemFire lets you specify a jar or zip file on import for a cache-based Snapshot Service, as follows:

Spring Data for Pivotal GemFire conveniently extracts the provided zip file and treats it as a directory import (load).

The real power of defining multiple snapshot imports and exports is realized through the use of snapshot filters. Snapshot filters implement Pivotal GemFire’s SnapshotFilter interface and are used to filter Region entries for inclusion into the Region on import and for inclusion into the snapshot on export.

Spring Data for Pivotal GemFire lets you use snapshot filters on import and export by using the filter-ref attribute or an anonymous, nested bean definition, as the following example shows:

In addition, you can express more complex snapshot filters by using the ComposableSnapshotFilter class. This class implements Pivotal GemFire’s SnapshotFilter interface as well as the Composite software design pattern.

In a nutshell, the Composite software design pattern lets you compose multiple objects of the same type and treat the aggregate as single instance of the object type — a powerful and useful abstraction.

ComposableSnapshotFilter has two factory methods, and and or. They let you logically combine individual snapshot filters using the AND and OR logical operators, respectively. The factory methods take a list of SnapshotFilters.

The following example shows a definition for a ComposableSnapshotFilter:

You could then go on to combine the activesUsersSinceFilter with another filter by using or, as follows:

By default, Spring Data for Pivotal GemFire uses Pivotal GemFire’s Snapshot Services on startup to import data and on shutdown to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export, from within your Spring application.

For this purpose, Spring Data for Pivotal GemFire defines two additional Spring application events, extending Spring’s ApplicationEvent class for imports and exports, respectively: ImportSnapshotApplicationEvent and ExportSnapshotApplicationEvent.

The two application events can be targeted for the entire Pivotal GemFire cache or for individual Pivotal GemFire Regions. The constructors in these classes accept an optional Region pathname (such as /Example) as well as zero or more SnapshotMetadata instances.

The array of SnapshotMetadata overrides the snapshot metadata defined by <gfe-data:snapshot-import> and <gfe-data:snapshot-export> sub-elements, which are used in cases where snapshot application events do not explicitly provide SnapshotMetadata. Each individual SnapshotMetadata instance can define its own location and filters properties.

All snapshot service beans defined in the Spring ApplicationContext receive import and export snapshot application events. However, only matching Snapshot Service beans process import and export events.

A Region-based [Import|Export]SnapshotApplicationEvent matches if the Snapshot Service bean defined is a RegionSnapshotService and its Region reference (as determined by the region-ref attribute) matches the Region’s pathname, as specified by the snapshot application event.

A Cache-based [Import|Export]SnapshotApplicationEvent (that is, a snapshot application event without a Region pathname) triggers all Snapshot Service beans, including any RegionSnapshotService beans, to perform either an import or export, respectively.

You can use Spring’s ApplicationEventPublisher interface to fire import and export snapshot application events from your application as follows:

In the preceding example, only the /Example Region’s Snapshot Service bean picks up and handles the export event, saving the filtered, “/Example” Region’s data to the data.snapshot file in a sub-directory of the application’s working directory.

Using the Spring application events and messaging subsystem is a good way to keep your application loosely coupled. You can also use Spring’s Scheduling services to fire snapshot application events on a periodic basis.

In the following example, GatewaySenders are configured for a PARTITION Region by adding child elements (gateway-sender and gateway-sender-ref) to the Region. A GatewaySender may register EventFilters and TransportFilters.

The following example also shows a sample configuration of an AsyncEventQueue, which must also be auto-wired into a Region (not shown):

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, as follows:

See the Pivotal GemFire documentation for a detailed explanation of all the configuration options.

In the usual Spring fashion, you can even express Properties in terms of other Properties, whether that is by The following example shows a nested property being set in an application.properties file:

The following example shows a nested property being set in Java:

As mentioned previously, Pivotal GemFire Locators are used by clients to connect to and find servers in a cluster. In addition, new members joining an existing cluster use Locators to find their peers.

It is often convenient for application developers as they are developing their Spring Boot and Spring Data for Pivotal GemFire applications to startup up a small cluster of two or three Pivotal GemFire servers. Rather than starting a separate Locator process, you can annotate your Spring Boot @CacheServerApplication class with @EnableLocator, as follows:

The @EnableLocator annotation starts an embedded Locator in the Spring Pivotal GemFire CacheServer application running on localhost, listening on the default Locator port, 10334. You can customize the host (bind address) and port that the embedded Locator binds to by using the corresponding annotation attributes.

Alternatively, you can set the @EnableLocator attributes by setting the corresponding spring.data.gemfire.locator.host and spring.data.gemfire.locator.port properties in application.properties.

Then you can start other Spring Boot @CacheServerApplication-enabled applications by connecting to this Locator with the following:

You can even combine both application classes shown earlier into a single class and use your IDE to create different run profile configurations to launch different instances of the same class with slightly modified configuration by using Java system properties, as follows:

Then, for each run profile, you can set and change the following system properties:

Only 1 of the run profiles for the ServerApplication class should set the -Dspring.profiles.active=embedded-locator Java system property. Then you can change the ..name and ..cache.server.port for each of the other run profiles and have a small cluster (distributed system) of Pivotal GemFire servers running on your local system.

More details on how Pivotal GemFire Locators work can be found here.

A Pivotal GemFire Manager is another peer member or node in the cluster that is responsible for cluster "management". Management involves creating Regions, Indexes, DiskStores, among other things, along with monitoring the runtime operations and behavior of the cluster components.

The Manager lets a JMX-enabled client (such as the Gfsh shell tool) connect to the Manager to manage the cluster. It is also possible to connect to a Manager with JDK-provided tools such as JConsole or JVisualVM, given that these are both JMX-enabled clients as well.

Perhaps you would also like to enable the Spring @CacheServerApplication shown earlier as a Manager as well. To do so, annotate your Spring @Configuration or @SpringBootApplication class with @EnableManager.

By default, the Manager binds to localhost, listening on the default Manager port of 1099. Several aspects of the Manager can be configured with annotation attributes or the corresponding properties.

The following example shows how to create an embedded Manager in Java:

With the preceding class, you can even use Gfsh to connect to the small cluster and manage it, as follows:

Because we also have the embedded Locator enabled, we can connect indirectly to the Manager through the Locator. A Locator lets JMX clients connect and find a Manager in the cluster. If none exists, the Locator assumes the role of a Manager. However, if no Locator exists, we would need to connect directly to the Manager by using the following:

More details on Pivotal GemFire management and monitoring can be found here.

Pivotal GemFire is also capable of running an embedded HTTP server. The current implementation is backed by Eclipse Jetty.

The embedded HTTP server is used to host Pivotal GemFire’s Management (Admin) REST API (not a publicly advertised API), the Developer REST API, and the Pulse Monitoring Web Application.

However, to use any of these Pivotal GemFire-provided web applications, you must have a full installation of Pivotal GemFire installed on your system, and you must set the GEODE_HOME environment variable to your installation directory.

To enable the embedded HTTP server, add the @EnableHttpService annotation to any @PeerCacheApplication or @CacheServerApplication annotated class, as follows:

By default, the embedded HTTP server listens on port 7070 for HTTP client requests. Of course, you can use the annotation attributes or corresponding configuration properties to adjust the port as needed.

Follow the earlier links for more details on HTTP support and the services provided.

Pivotal GemFire also implements the Memcached protocol with the ability to service Memcached clients. That is, Memcached clients can connect to a Pivotal GemFire cluster and perform Memcached operations as if the Pivotal GemFire servers in the cluster were actual Memcached servers.

To enable the embedded Memcached service, add the @EnableMemcachedServer annotation to any @PeerCacheApplication or @CacheServerApplication annotated class, as follows:

More details on Pivotal GemFire’s Memcached service (called "Gemcached") can be found here.

Pivotal GemFire also implements the Redis server protocol, which enables Redis clients to connect to and communicate with a cluster of Pivotal GemFire servers to issue Redis commands. As of this writing, the Redis server protocol support in Pivotal GemFire is still experimental.

To enable the embedded Redis service, add the @EnableRedisServer annotation to any @PeerCacheApplication or @CacheServerApplication annotated class, as follows:

More details on Pivotal GemFire’s Redis adapter can be found here.

Pivotal GemFire supports many different types of Regions. Each type corresponds to the Region’s DataPolicy, which determines exactly how the data in the Region will be managed (i.e. distributed, replicated, and so on).

When you annotate your application domain object types with the generic @Region mapping annotation, Spring Data for Pivotal GemFire decides which type of Region to create. SDG’s default strategy takes the cache type into consideration when determining the type of Region to create.

For example, if you declare the application as a ClientCache by using the @ClientCacheApplication annotation, SDG creates a client PROXY Region by default. Alternatively, if you declare the application as a peer Cache by using either the @PeerCacheApplication or @CacheServerApplication annotations, SDG creates a server PARTITION Region by default.

Of course, you can always override the default when necessary. To override the default applied by Spring Data for Pivotal GemFire, four new Region mapping annotations have been introduced:

The @ClientRegion mapping annotation is specific to client applications. All of the other Region mapping annotations listed above can only be used in server applications that have an embedded peer Cache.

It is sometimes necessary for client applications to create and use local-only Regions, perhaps to aggregate data from other Regions in order to analyze the data locally and carry out some function performed by the application on the user’s behalf. In this case, the data does not need to be distributed back to the server unless other applications need access to the results. This Region might even be temporary and discarded after use, which could be accomplished with Idle-Timeout (TTI) and Time-To-Live (TTL) expiration policies on the Region itself. (See “Configuring Expiration” for more on expiration policies.)

In any case, if you want to create a local-only client Region where the data is not going to be distributed back to a corresponding Region on the server with the same name, you can declare the @ClientRegion mapping annotation and set the shortcut attribute to ClientRegionShortcut.LOCAL, as follows:

All Region type-specific annotations provide additional attributes that are both common across Region types as well as specific to only that type of Region. For example, the collocatedWith and redundantCopies attributes in the PartitionRegion annotation apply to server-side, PARTITION Regions only.

More details on Pivotal GemFire Region types can be found here.

In addition to the @EnableEntityDefinedRegions annotation, Spring Data for Pivotal GemFire also provides the inverse annotation, @EnableClusterDefinedRegions. Rather than basing your Regions on the entity classes defined and driven from your application use cases (UC) and requirements (the most common and logical approach), alternatively, you can declare your Regions from the Regions already defined in the cluster to which your ClientCache application will connect.

This allows you to centralize your configuration using the cluster of servers as the primary source of data definitions and ensure that all client applications of the cluster have a consistent configuration. This is particularly useful when quickly scaling up a large number instances of the same client application to handle the increased load in a cloud-managed environment.

The idea is, rather than the client application(s) driving the data dictionary, the user defines Regions using Pivotal GemFire’s Gfsh CLI shell tool. This has the added advantage that when additional peers are added to the cluster, they too will also have and share the same configuration since it is remembered by Pivotal GemFire’s Cluster Configuration Service.

By way of example, a user might defined a Region in Gfsh, as follows:

With Pivotal GemFire’s Cluster Configuration Service, any additional peer members added to the cluster of servers to handle the increased load (on the backend) will also have the same configuration, for example:

As you can see, "ServerThree" now has the "Books" Region. If the any or all of the server go down, they will have the same configuration along with the "Books" Region when they come back up.

On the client-side, many Book Store client application instances might be started to process books against the Book Store online service. The "Books" Region might be 1 of many different Regions needed to implement the Book Store application service. Rather than have to create and configure each Region individually, SDG conveniently allows the client application Regions to be defined from the cluster, as follows:

Then, it becomes a simple matter to use the "Books" Region in your application. You can inject the "Books" Region directly, as follows:

Or, even define a Spring Data Repository definition based on the application domain type (entity), Book, mapped to the "Books" Region, as follows:

You can then either inject your custom BooksDataAccessObject or the BookRepository into your application service components to carry out whatever business function required.

Managing data with Pivotal GemFire is an active task. Tuning is generally required, and you must employ a combination of features (for example, both eviction and expiration) to effectively manage your data in memory with Pivotal GemFire.

Given that Pivotal GemFire is an In-Memory Data Grid (IMDG), data is managed in-memory and distributed to other nodes that participate in a cluster in order to minimize latency, maximize throughput and ensure that data is highly available. Since not all of an application’s data is going to typically fit in memory (even across an entire cluster of nodes, much less on a single node), you can increase capacity by adding new nodes to the cluster. This is commonly referred to as linear scale-out (rather than scaling up, which means adding more memory, more CPU, more disk, or more network bandwidth — basically more of every system resource in order to handle the load).

Still, even with a cluster of nodes, it is usually imperative that only the most important data be kept in memory. Running out of memory, or even venturing near full capacity, is rarely, if ever, a good thing. Stop-the-world GCs or worse, OutOfMemoryErrors, will bring your application to a screaming halt.

So, to help manage memory and keep the most important data around, Pivotal GemFire supports Least Recently Used (LRU) eviction. That is, Pivotal GemFire evicts Region entries based on when those entries were last accessed by using the Least Recently Used algorithm.

To enable eviction, annotate the application class with @EnableEviction, as follows:

Eviction policies are usually set on the Regions in the servers.

As shown earlier, the policies attribute can specify one or more nested @EvictionPolicy annotations, with each one being individually catered to one or more Regions where the eviction policy needs to be applied.

Additionally, you can reference a custom implementation of Pivotal GemFire’s org.apache.geode.cache.util.ObjectSizer interface, which can be defined as a bean in the Spring container and referenced by name by using the objectSizerName attribute.

An ObjectSizer lets you define the criteria used to evaluate and determine the the size of objects stored in a Region.

See the @EnableEviction annotation Javadoc for a complete list of eviction configuration options.

More details on Pivotal GemFire eviction can be found here.

Along with eviction, expiration can also be used to manage memory by allowing entries stored in a Region to expire. Pivotal GemFire supports both Time-to-Live (TTL) and Idle-Timeout (TTI) entry expiration policies.

Spring Data for Pivotal GemFire’s annotation-based expiration configuration is based on the earlier and existing entry expiration annotation support added in Spring Data for Pivotal GemFire version 1.5.

Essentially, Spring Data for Pivotal GemFire’s expiration annotation support is based on a custom implementation of Pivotal GemFire’s org.apache.geode.cache.CustomExpiry interface. This o.a.g.cache.CustomExpiry implementation inspects the user’s application domain objects stored in a Region for the presence of type-level expiration annotations.

Spring Data for Pivotal GemFire provides the following expiration annotations:

An application domain object type can be annotated with one or more of the expiration annotations, as follows:

To enable expiration, annotate the application class with @EnableExpiration, as follows:

In addition to application domain object type-level expiration policies, you can directly and individually configure expiration policies on a Region by Region basis using the @EnableExpiration annotation, as follows:

The preceding example sets expiration policies for the Books, Customers, and Orders Regions.

Expiration policies are usually set on the Regions in the servers.

See the @EnableExpiration annotation Javadoc for a complete list of expiration configuration options.

More details on Pivotal GemFire expiration can be found here.

In addition to eviction and expiration, you can also configure your data Regions with compression to reduce memory consumption.

Pivotal GemFire lets you compress in memory Region values by using pluggable Compressors, or different compression codecs. Pivotal GemFire uses Google’s Snappy compression library by default.

To enable compression, annotate the application class with @EnableCompression, as follows:

The compressorBeanName defaults to SnappyCompressor, enabling Pivotal GemFire’s SnappyCompressor.

The regionNames attribute is an array of Region names that specify the Regions that have compression enabled. By default, all Regions compress values if the regionNames attribute is not explicitly set.

See the @EnableCompression annotation Javadoc for more details.

More details on Pivotal GemFire compression can be found here.

Another effective means for reducing pressure on the JVM’s Heap memory and minimizing GC activity is to use Pivotal GemFire’s off-heap memory support.

Rather than storing Region entries on the JVM Heap, entries are stored in the system’s main memory. Off-heap memory generally works best when the objects being stored are uniform in size, are mostly less than 128K, and do not need to be deserialized frequently, as explained in the Pivotal GemFire User Guide.

To enable off-heap, annotate the application class with @EnableOffHeap, as follows:

The memorySize attribute is required. The value for the memorySize attribute specifies the amount of main memory a Region can use in either megabytes (m) or gigabytes (g).

The regionNames attribute is an array of Region names that specifies the Regions that store entries in main memory. By default, all Regions use main memory if the regionNames attribute is not explicitly set.

See the @EnableOffHeap annotation Javadoc for more details.

Alternatively, you can configure Regions to persist data to disk. You can also configure Regions to overflow data to disk when Region entries are evicted. In both cases, a DiskStore is required to persist and/or overflow the data. When an explicit DiskStore has not been configured for a Region with persistence or overflow, Pivotal GemFire uses the DEFAULT DiskStore.

We recommend defining Region-specific DiskStores when persisting and/or overflowing data to disk.

Spring Data for Pivotal GemFire provides annotation support for defining and creating application Region DiskStores by annotating the application class with the @EnableDiskStore and @EnableDiskStores annotations.

For example, while Book information might mostly consist of reference data from some external data source (such as Amazon), Order data is most likely going to be transactional in nature and something the application is going to need to retain (and maybe even overflow to disk if the transaction volume is high enough) — or so any book publisher and author hopes, anyway.

Using the @EnableDiskStore annotation, you can define and create a DiskStore as follows:

Again, more than one DiskStore can be defined by using the composite, @EnableDiskStores annotation.

As with other annotations in Spring Data for Pivotal GemFire’s annotation-based configuration model, both @EnableDiskStore and @EnableDiskStores have many attributes along with associated configuration properties to customize the DiskStores created at runtime.

Additionally, the @EnableDiskStores annotation defines certain common DiskStore attributes that apply to all DiskStores created from @EnableDiskStore annotations composed with the @EnableDiskStores annotation itself. Individual DiskStore configuration override a particular global setting, but the @EnableDiskStores annotation conveniently defines common configuration attributes that apply across all DiskStores aggregated by the annotation.

Spring Data for Pivotal GemFire also provides the DiskStoreConfigurer callback interface, which can be declared in Java configuration and used instead of configuration properties to customize a DiskStore at runtime, as the following example shows:

See the @EnableDiskStore and @EnableDiskStores annotation Javadoc for more details on the available attributes as well as associated configuration properties.

More details on Pivotal GemFire Region persistence and overflow (using DiskStores) can be found here.

There is not much use in storing data in Regions unless the data can be accessed.

In addition to Region.get(key) operations, particularly when the key is known in advance, data is commonly retrieved by executing queries on the Regions that contain the data. With Pivotal GemFire, queries are written by using the Object Query Language (OQL), and the specific data set that a client wishes to access is expressed in the query’s predicate (for example, SELECT * FROM /Books b WHERE b.author.name = 'Jon Doe').

Generally, querying without indexes is inefficient. When executing queries without an index, Pivotal GemFire performs the equivalent of a full table scan.

Indexes are created and maintained for fields on objects used in query predicates to match the data of interest, as expressed by the query’s projection. Different types of indexes, such as key and hash indexes, can be created.

Spring Data for Pivotal GemFire makes it easy to create indexes on Regions where the data is stored and accessed. Rather than explicitly declaring Index bean definitions by using Spring config as before, we can create an Index bean definition in Java, as follows:

Alternatively, we can use XML to create an Index bean definition, as follows:

However, now you can directly define indexes on the fields of your application domain object types for which you know will be used in query predicates to speed up those queries. You can even apply indexes for OQL queries generated from user-defined query methods on an application’s repository interfaces.

Re-using the example Book entity class from earlier, we can annotate the fields on Book that we know are used in queries that we define with query methods in the BookRepository interface, as follows:

In our new Book class definition, we annotated the author field with @Indexed and the title field with @LuceneIndexed. Also, the isbn field had previously been annotated with Spring Data’s @Id annotation, which identifies the field containing the unique identifier for Book instances, and, in Spring Data for Pivotal GemFire, the @Id annotated field or property is used as the key in the Region when storing the entry.

When the @Indexed annotation is used without setting any attributes, the index name, expression, and fromClause are derived from the field or property of the class on which the @Indexed annotation has been added. The expression is exactly the name of the field or property. The fromClause is derived from the @Region annotation on the domain object’s class, or the simple name of the domain object class if the @Region annotation was not specified.

Of course, you can explicitly set any of the @Indexed annotation attributes to override the default values provided by Spring Data for Pivotal GemFire.

The name of the index, which is auto-generated when not explicitly set, is also used as the name of the bean registered in the Spring container for the index. If necessary, this index bean can even be injected by name into another application component.

The generated name of the index follows this pattern: <Region Name><Field/Property Name><Index Type>Idx. For example, the name of the author index would be, BooksAuthorHashIdx.

To enable indexing, annotate the application class with @EnableIndexing, as follows:

While Lucene queries are not (yet) supported on Spring Data for Pivotal GemFire repositories, SDG does provide comprehensive support for Pivotal GemFire Lucene queries by using the familiar Spring template design pattern.

Finally, we close this section with a few extra tips to keep in mind when using indexes:

Another optimization that you can use when restarting your Spring application where indexes have to be rebuilt is to first define all the indexes up front and then create them all at once, which, in Spring Data for Pivotal GemFire, happens when the Spring container is refreshed.

You can define indexes up front and then create them all at once by setting the define attribute on the @EnableIndexing annotation to true.

See “Creating Multiple Indexes at Once” in Pivotal GemFire’s User Guide for more details.

Creating sensible indexes is an important task, since it is possible for a poorly designed index to do more harm than good.

See both the @Indexed annotation and @LuceneIndexed annotation Javadoc for complete list of configuration options.

More details on Pivotal GemFire OQL queries can be found here.

More details on Pivotal GemFire indexes can be found here.

More details on Pivotal GemFire Lucene queries can be found here.

There are several different ways in which you can configure security for servers in a Pivotal GemFire cluster.

The problem with the first approach is that you must implement your own SecurityManager, which can be quite tedious and error-prone. Implementing a custom SecurityManager offers some flexibility in accessing security metadata from whatever data source stores the metadata, such as LDAP or even a proprietary, internal data source. However, that problem has already been solved by configuring and using Apache Shiro Realms, which is more universally known and non-Pivotal GemFire-specific.

The second approach, using an Apache Shiro INI file, is marginally better, but you still need to be familiar with the INI file format in the first place. Additionally, an INI file is static and not easily updatable at runtime.

The third approach is the most ideal, since it adheres to widely known and industry-accepted concepts (that is, Apache Shiro’s Security framework) and is easy to setup, as the following example shows:

You could even create a custom implementation of an Apache Shiro Realm.

See Apache Shiro’s documentation on Realms for more details.

When Apache Shiro is on the CLASSPATH of the servers in the cluster and one or more Apache Shiro Realms have been defined as beans in the Spring container, Spring Data for Pivotal GemFire detects this configuration and uses Apache Shiro as the security provider to secure your Pivotal GemFire servers when the @EnableSecurity annotation is used.

See the @EnableSecurity annotation Javadoc for more details on available attributes and associated configuration properties.

More details on Pivotal GemFire security can be found here.

The security story would not be complete without discussing how to secure Spring-based, Pivotal GemFire cache client applications as well.

Pivotal GemFire’s process for securing a client application is, honestly, rather involved. In a nutshell, you need to:

Spring Data for Pivotal GemFire simplifies all of those steps by using the same @EnableSecurity annotation that was used in the server applications. In other words, the same @EnableSecurity annotation handles security for both client and server applications. This feature makes it easier for users when they decide to switch their applications from an embedded, peer Cache application to a ClientCache application, for instance. Simply change the SDG annotation from @PeerCacheApplication or @CacheServerApplication to @ClientCacheApplication, and you are done.

Effectively, all you need to do on the client is the following:

Then you can define the familiar Spring Boot application.properties file containing the required username and password, as the following example shows, and you are all set:

See the @EnableSecurity annotation Javadoc for more details on available attributes and associated configuration properties.

More details on Pivotal GemFire Security can be found here.

As we saw in the section on “Configuring Cluster Configuration Push”, when many Pivotal GemFire or Spring Data for Pivotal GemFire features are enabled by using annotations, we begin to stack a lot of annotations on the Spring @Configuration or @SpringBootApplication class. In this situation, it makes sense to start compartmentalizing the configuration a bit.

For instance, consider the following declaration:

We could break this configuration down by concern, as follows:

While it does not matter to the Spring Framework, we generally recommend aiming for readability, for the sake of the next person who has to maintain the code (which might be you at some point in the future).

The following SDG Annotations were not discussed in this reference documentation, either because the annotation supports a deprecated feature of Pivotal GemFire or because there are better, alternative ways to accomplishing the function that the annotation provides:

To configure and bootstrap a Pivotal GemFire ClientCache application, use the following:

See @ClientCacheApplication Javadoc.

See Configuring Pivotal GemFire Applications with Spring for more details.

To configure and bootstrap a Pivotal GemFire Peer Cache application, use the following:

See @CacheServerApplication Javadoc.

See @PeerCacheApplication Javadoc.

See Configuring Pivotal GemFire Applications with Spring for more details.

Annotate your Spring @PeerCacheApplication or @CacheServerApplication class with @EnableLocator to start an embedded Locator bound to all NICs listening on the default Locator port, 10334, as follows:

See @EnableLocator Javadoc.

See Configuring an Embedded Locator for more details.

Annotate your Spring @PeerCacheApplication or @CacheServerApplication class with @EnableManager to start an embedded Manager bound to all NICs listening on the default Manager port, 1099, as follows:

See @EnableManager Javadoc.

See Configuring an Embedded Manager for more details.

Annotate your Spring @PeerCacheApplication or @CacheServerApplication class with @EnableHttpService to start the embedded HTTP server (Jetty) listening on port 7070, as follows:

See @EnableHttpService Javadoc.

See Configuring the Embedded HTTP Server for more details.

Annotate your Spring @PeerCacheApplication or @CacheServerApplication class with @EnableMemcachedServer to start the embedded Memcached server (Gemcached) listening on port 11211, as follows:

See @EnableMemcachedServer Javadoc.

See Configuring the Embedded Memcached Server (Gemcached) for more details.

Annotate your Spring @PeerCacheApplication or @CacheServerApplication class with @EnableRedisServer to start the embedded Redis server listening on port 6379, as follows:

See @EnableRedisServer Javadoc.

See Configuring the Embedded Redis Server for more details.

To configure or adjust Pivotal GemFire logging, annotate your Spring, Pivotal GemFire client or server application class with @EnableLogging, as follows:

See @EnableLogging Javadoc.

See Configuring Logging for more details.

To gather Pivotal GemFire statistics at runtime, annotate your Spring, Pivotal GemFire client or server application class with @EnableStatistics, as follows:

See @EnableStatistics Javadoc.

See Configuring Statistics for more details.

To enable Pivotal GemFire PDX serialization, annotate your Spring, Pivotal GemFire client or server application class with @EnablePdx, as follows:

See @EnablePdx Javadoc.

See Configuring PDX for more details.

To enable Pivotal GemFire SSL, annotate your Spring, Pivotal GemFire client or server application class with @EnableSsl, as follows:

See @EnableSsl Javadoc.

See Configuring SSL for more details.

To enable Pivotal GemFire security, annotate your Spring, Pivotal GemFire client or server application class with @EnableSecurity, as follows:

See @EnableSecurity Javadoc.

See Configuring Security for more details.

To configure other, low-level Pivotal GemFire properties not covered by the feature-oriented, SDG configuration annotations, annotate your Spring, Pivotal GemFire client or server application class with @GemFireProperties, as follows:

See @EnableGemFireProperties Javadoc.

See Configuring Pivotal GemFire Properties for more details.

To use Pivotal GemFire as a caching provider in Spring’s Cache Abstraction, and have SDG automatically create Pivotal GemFire Regions for the caches required by your application service components, then annotate your Spring, Pivotal GemFire client or server application class with @EnableGemfireCaching and @EnableCachingDefinedRegions, as follows:

Then, simply go on to define the application services that require caching, as follows:

See @EnableCachingDefinedRegions Javadoc.

See @EnableGemfireCaching Javadoc.

See Configuring Spring’s Cache Abstraction for more details.

To make short work of creating Spring, Pivotal GemFire persistent client or server applications, annotate your application class with @EnableEntityDefinedRegions, @EnableGemfireRepositories and @EnableIndexing, as follows:

Next, define your entity class and use the @Region mapping annotation to specify the Region in which your entity will be stored. Use the @Indexed annotation to define Indexes on entity fields used in your application queries, as follows:

Finally, define your CRUD Repository with simple queries to persist and access Books, as follows:

See @EnableEntityDefinedRegions Javadoc.

See @EnableGemfireRepositories Javadoc.

See @EnableIndexing Javadoc.

See @Region Javadoc.

See @Indexed Javadoc.

See @LuceneIndexed Javadoc.

See Configuring Regions for more details.

See Spring Data for Pivotal GemFire Repositories for more details.

Alternatively, you can define client [*PROXY] Regions from Regions already defined in the cluster using @EnableClusterDefinedRegions, as follows:

See Configured Cluster-defined Regions for more details.

Pivotal GemFire Functions are useful in distributed compute scenarios where a potentially expensive computation requiring data can be performed in parallel across the nodes in the cluster. In this case, it is more efficient to bring the logic to where the data is located (stored) rather than requesting and fetching the data to be processed by the computation.

Use the @EnableGemfireFunctions along with the @GemfireFunction annotation to enable Pivotal GemFire Functions definitions implemented as methods on POJOs, as follows:

Use the @EnableGemfireFunctionExecutions along with 1 of the Function calling annotations: @OnMember, @OnMembers, @OnRegion, @OnServer and @OnServers.

See @EnableGemfireFunctions Javadoc.

See @GemfireFunction Javadoc.

See @EnableGemfireFunctionExecutions Javadoc.

See @OnMember Javadoc, @OnMembers Javadoc, @OnRegion Javadoc, @OnServer Javadoc, and @OnServers Javadoc.

See Annotation Support for Function Execution for more details.

Real-time, event stream processing is becoming an increasingly important task for data-intensive applications, primarily in order to respond to user requests in a timely manner. Pivotal GemFire Continuous Query (CQ) will help you achieve this rather complex task quite easily.

Enable CQ by annotating your application class with @EnableContinuousQueries and define your CQs along with the associated event handlers, as follows:

Then, define your CQs by annotating the associated handler method with @ContinousQuery, as follows:

Anytime an event occurs changing the Customer data to match the predicate in your continuous OQL query (CQ), the process method will be called.

See @EnableContinuousQueries Javadoc.

See @ContinuousQuery Javadoc.

See Continuous Query (CQ) and Configuring Continuous Queries for more details.

When developing Spring Data applications using Pivotal GemFire as Pivotal GemFire ClientCache applications, it is useful during development to configure the server to match the client in a client/server topology. In fact, Pivotal GemFire expects that when you have a "/Example" PROXY Region on the client, that a matching Region by name (i.e. "Example") exists in the server.

You could use Gfsh to create every Region and Index that your application requires, or, you could simply push the configuration meta-data already expressed when developing your Spring Data application using Pivotal GemFire when you run it.

This is as simple as annotation your main application class with @EnableClusterConfiguration(..):

See @EnableClusterConfiguration Javadoc.

See Configuring Cluster Configuration Push for more details.

The replication of data between different Pivotal GemFire clusters is an increasingly important fault-tolerance and high-availability (HA) mechanism. Pivotal GemFire WAN replication is a mechanism that allows one Pivotal GemFire cluster to replicate its data to another Pivotal GemFire cluster in a reliable and fault-tolerant manner.

Pivotal GemFire WAN replication requires two components to be configured:

To enable a GatewayReceiver, the application class needs to be annotated with @EnableGatewayReceiver as follows:

See @EnableGatewayReceiver Javadoc.

To enable GatewaySender, the application class needs to be annotated with @EnableGatewaySenders and @EnableGatewaySender as follows:

In the above example, the application is configured with 2 Regions, Region1 and Region2. In addition, two GatewaySenders will be configured to service both Regions. GatewaySender1 will be configured to replicate Region1’s data and `GatewaySender2 will be configured to replicate `Region2’s data.

As demonstrated each GatewaySender property can be configured on each EnableGatewaySender annotation.

It is also possible to have a more generic, "defaulted" properties approach, where all properties are configured on the EnableGatewaySenders annotation. This way, a set of generic, defaulted values can be set on the parent annotation and then overridden on the child if required, as demonstrated below:

See @EnableGatewaySenders Javadoc and @EnableGatewaySender Javadoc.

Spring Data for Pivotal GemFire simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of the infrastructure around CQ with the use of SDG’s ContinuousQueryListenerContainer, which does all the heavy lifting on behalf of the user. Users familiar with EJB and JMS should find the concepts familiar as it is designed as close as possible to the support provided in the Spring Framework with its Message-driven POJOs (MDPs).

The SDG ContinuousQueryListenerContainer acts as an event (or message) listener container; it is used to receive the events from the registered CQs and invoke the POJOs that are injected into it. The listener container is responsible for all threading of message reception and dispatches into the listener for processing. It acts as the intermediary between an EDP (Event-driven POJO) and the event provider and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and the like. This allows you, as an application developer, to write the (possibly complex) business logic associated with receiving an event (and reacting to it), and delegate the boilerplate Pivotal GemFire infrastructure concerns to the framework.

The listener container is fully customizable. A developer can chose either to use the CQ thread to perform the dispatch (synchronous delivery) or a new thread (from an existing pool) for an asynchronous approach by defining the suitable java.util.concurrent.Executor (or Spring’s TaskExecutor). Depending on the load, the number of listeners or the runtime environment, the developer should change or tweak the executor to better serve her needs. In particular, in managed environments (such as app servers), it is highly recommended to pick a proper TaskExecutor to take advantage of its runtime.

The ContinuousQueryListenerAdapter class is the final component in Spring Data for Pivotal GemFire CQ support. In a nutshell, class allows you to expose almost any implementing class as an EDP with minimal constraints. ContinuousQueryListenerAdapter implements the ContinuousQueryListener interface, a simple listener interface similar to Pivotal GemFire’s CqListener.

Consider the following interface definition. Notice the various event handling methods and their parameters:

In particular, note how the above implementation of the EventDelegate interface has no Pivotal GemFire dependencies at all. It truly is a POJO that we can and will make into an EDP via the following configuration.

The example above uses the Spring Data for Pivotal GemFire namespace to declare the event listener container and automatically register the listeners. The full blown, beans definition is displayed below:

Each time an event is received, the adapter automatically performs type translation between the Pivotal GemFire event and the required method argument(s) transparently. Any exception caused by the method invocation is caught and handled by the container (by default, being logged).

When used, WiringDeclarableSupport tries to first locate an existing bean definition and use that as the wiring template. Unless specified, the component class name will be used as an implicit bean definition name.

Let’s see how our DBLoader declaration would look in that case:

In the scenario above, as no parameter was specified, a bean with the id/name com.company.app.DBLoader was used as a template for wiring the instance created by Pivotal GemFire. For cases where the bean name uses a different convention, one can pass in the bean-name parameter in the Pivotal GemFire configuration:

By default, if no bean definition is found, WiringDeclarableSupport will autowire the declaring instance. This means that unless any dependency injection metadata is offered by the instance, the container will find the object setters and try to automatically satisfy these dependencies. However, a developer can also use JDK 5 annotations to provide additional information to the auto-wiring process.

For example, the hypothetical DBLoader declaration above can be injected with a Spring-configured DataSource in the following way:

By using the JSR-330 annotations, the CacheLoader code has been simplified since the location and creation of the DataSource has been externalized and the user code is concerned only with the loading process. The DataSource might be transactional, created lazily, shared between multiple objects or retrieved from JNDI. These aspects can easily be configured and changed through the Spring container without touching the DBLoader code.

Spring Data automatically tries to detect a persistent entity’s constructor to be used to materialize objects of that type. The resolution algorithm works as follows:

The value resolution assumes constructor argument names to match the property names of the entity, i.e. the resolution will be performed as if the property was to be populated, including all customizations in mapping (different datastore column or field name etc.). This also requires either parameter names information available in the class file or an @ConstructorProperties annotation being present on the constructor.

The value resolution can be customized by using Spring Framework’s @Value value annotation using a store-specific SpEL expression. Please consult the section on store specific mappings for further details.

Once an instance of the entity has been created, Spring Data populates all remaining persistent properties of that class. Unless already populated by the entity’s constructor (i.e. consumed through its constructor argument list), the identifier property will be populated first to allow the resolution of cyclic object references. After that, all non-transient properties that have not already been populated by the constructor are set on the entity instance. For that we use the following algorithm:

Let’s have a look at the following entity:

Spring Data adapts specifics of Kotlin to allow object creation and mutation.

In addition to the @Region annotation, Spring Data for Pivotal GemFire also recognizes type-specific Region mapping annotations: @ClientRegion, @LocalRegion, @PartitionRegion, and @ReplicateRegion.

Functionally, these annotations are treated exactly the same as the generic @Region annotation in the SDG mapping infrastructure. However, these additional mapping annotations are useful in Spring Data for Pivotal GemFire’s annotation configuration model. When combined with the @EnableEntityDefinedRegions configuration annotation on a Spring @Configuration annotated class, it is possible to generate Regions in the local cache, whether the application is a client or peer.

These annotations let you be more specific about what type of Region your application entity class should be mapped to and also has an impact on the data management policies of the Region (for example, partition — also known as sharding — versus replicating data).

Using these type-specific Region mapping annotations with the SDG annotation configuration model saves you from having to explicitly define these Regions in configuration.

The MappingPdxSerializer gives you the ability to register custom PdxSerializers based on an entity’s field or property names and types.

For example, suppose you have defined an entity type modeling a User as follows:

While the user’s name probably does not require any special logic to serialize the value, serializing the password on the other hand might require additional logic to handle the sensitive nature of the field or property.

Perhaps you want to protect the password when sending the value over the network, between a client and a server, beyond TLS alone, and you only want to store the salted hash. When using the MappingPdxSerializer, you can register a custom PdxSerializer to handle the user’s password, as follows:

After registering the application-defined SaltedHashPasswordPdxSerializer instance with the Password application domain model type, the MappingPdxSerializer will then consult the custom PdxSerializer to serialize and deserialize all Password objects regardless of the containing object (for example, User).

However, suppose you want to customize the serialization of Passwords only on User objects. To do so, you can register the custom PdxSerializer for the User type by specifying the fully qualified name of the Class’s field or property, as the following example shows:

Notice the use of the fully-qualified field or property name (that is example.app.security.auth.model.User.password) as the custom PdxSerializer registration key.

Like Pivotal GemFire’s ReflectionBasedAutoSerializer, SDG’s MappingPdxSerializer is also able to determine the identifier of the entity. However, MappingPdxSerializer does so by using Spring Data’s mapping metadata, specifically by finding the entity property designated as the identifier using Spring Data’s @Id annotation. Alternatively, any field or property named “id”, not explicitly annotated with @Id, is also designated as the entity’s identifier.

For example:

In this case, the Customer id field is marked as the identifier field in the PDX type metadata by using PdxWriter.markIdentifierField(:String) when the PdxSerializer.toData(..) method is called during serialization.

What happens when your entity defines a read-only property?

First, it is important to understand what a “read-only” property is. If you define a POJO by following the JavaBeans specification (as Spring does), you might define a POJO with a read-only property, as follows:

The readOnly property is read-only because it does not provide a setter method. It only has a getter method. In this case, the readOnly property (not to be confused with the readOnly DomainType field) is considered read-only.

As a result, the MappingPdxSerializer will not try to set a value for this property when populating an instance of ApplicationDomainType in the PdxSerializer.fromData(:Class<ApplicationDomainType>, :PdxReader) method during deserialization, particularly if a value is present in the PDX serialized bytes.

This is useful in situations where you might be returning a view or projection of some entity type and you only want to set state that is writable. Perhaps the view or projection of the entity is based on authorization or some other criteria. The point is, you can leverage this feature as is appropriate for your application’s use cases and requirements. If you want the field or property to always be written, simply define a setter method.

Likewise, what happens when your entity defines transient properties?

You would expect the transient fields or properties of your entity not to be serialized to PDX when serializing the entity. That is exactly what happens, unlike Pivotal GemFire’s own ReflectionBasedAutoSerializer, which serializes everything accessible from the object through Java Reflection.

The MappingPdxSerializer will not serialize any fields or properties that are qualified as being transient, either by using Java’s own transient keyword (in the case of class instance fields) or by using the @Transient Spring Data annotation on either fields or properties.

For example, you might define an entity with transient fields and properties as follows:

Neither the Process id field nor the readable hostname property are written to PDX.

Similar to Pivotal GemFire’s ReflectionBasedAutoSerializer, SDG’s MappingPdxSerializer lets you filter the types of objects that are serialized and deserialized.

However, unlike Pivotal GemFire’s ReflectionBasedAutoSerializer, which uses complex regular expressions to express which types the serializer handles, SDG’s MappingPdxSerializer uses the much more robust java.util.function.Predicate interface and API to express type-matching criteria.

The nice part about Java’s Predicate interface is that you can compose Predicates by using convenient and appropriate API methods, including: and(:Predicate), or(:Predicate), and negate().

The following example shows the Predicate API in action:

SDG’s MappingPdxSerializer includes support for both include and exclude class type filters.