Spring Data GemFire’s XML namespace supports full configuration of the Pivotal GemFire In-Memory Data Grid (IMDG). The XML namespace is the preferred way to configure Pivotal GemFire in a Spring context in order to properly manage GemFire’s lifecycle inside the Spring container. While support for GemFire’s native cache.xml persists for legacy reasons, GemFire application developers are encouraged to do everything in Spring XML to take advantage of the many wonderful things Spring has to offer such as modular XML configuration, property placeholders and overrides, SpEL, and environment profiles. Behind the XML namespace, Spring Data GemFire makes extensive use of Spring’s FactoryBean pattern to simplify the creation, configuration and initialization of GemFire components.

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

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

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

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

In addition to the core XML namespace (gfe), Spring Data GemFire provides a gfe-data XML namespace primarily intended to simplify the development of Pivotal GemFire client applications. This namespace currently contains support for GemFire Repositories and function execution as well as includes a <datasource> tag that offers a convenient way to connect to the Pivotal GemFire data grid.

To use Pivotal GemFire, a developer needs to either create a new Cache or connect to an existing one. With the current version of GemFire, there can be only one open Cache per VM (technically, per ClassLoader). In most cases, the Cache should only be created once.

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

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

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

A GemFire Cache can be fully configured using Spring, however, GemFire’s native XML configuration file, cache.xml, is also supported. For situations where the GemFire cache needs to be configured natively, simply provide a reference to the GemFire XML configuration file using the cache-xml-location attribute:

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

In addition to referencing an external XML configuration file, a developer may also specify GemFire System properties using any of Spring’s Properties support features.

For example, the developer may use the properties element defined in the util namespace to define Properties directly or load properties from a properties file:

Using a properties file is recommended for externalizing environment specific settings outside the application configuration.

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

GemFire implements the following types of Regions:

For more information about the various Region types and their capabilities as well as configuration options, please refer to Pivotal GemFire’s documentation on Region Types.

Pivotal GemFire allows Indexes (or Indices) to be created on Region data to improve the performance of OQL queries.

In Spring Data GemFire (SDG), Indexes are declared with the index element:

In Spring Data GemFire’s XML schema (a.k.a. SDG namespace), Index bean declarations are not bound to a Region, unlike GemFire’s native cache.xml. Rather, they are top-level elements just like <gfe:cache>. This allows a developer to declare any number of Indexes on any Region whether they were just created or already exist, a significant improvement over GemFire’s native cache.xml format.

An Index must have a name. A developer may give the Index an explicit name using the name attribute, otherwise the bean name (i.e. value of the id attribute) of the Index bean definition is used as the Index name.

The expression and from clause form the main components of an Index, identifying the data to index (i.e. the Region identified in the from clause) along with what criteria (i.e. expression) is used to index the data. The expression should be based on what application domain object fields are used in the predicate of application-defined OQL queries used to query and lookup the objects stored in the Region.

For example, if I have a Customer that has a lastName property…​

And, I also have an application defined SD[G] Repository to query for Customers…​

Then, the SD[G] Repository finder/query method would result in the following OQL statement being executed…​

Therefore, I might want to create an Index like so…​

The from clause must refer to a valid, existing Region and is how an Index gets applied to a Region. This is not Sprig Data GemFire specific; this is a feature of Pivotal GemFire.

The Index type maybe 1 of 3 enumerated values defined by Spring Data GemFire’s IndexType enumeration: FUNCTIONAL, HASH and PRIMARY_KEY.

Each of the enumerated values correspond to one of the QueryService create[|Key|Hash]Index methods invoked when the actual Index is to be created (or "defined"; more on "defining" Indexes below). For instance, if the IndexType is PRIMARY_KEY, then the QueryService.createKeyIndex(..) is invoked to create a KEY Index.

The default is FUNCTIONAL and results in one of the QueryService.createIndex(..) methods being invoked.

See the Spring Data GemFire XML schema for a full set of options.

For more information on Indexing in Pivotal GemFire, see Working with Indexes in Pivotal GemFire’s User Guide.

Spring Data GemFire supports DiskStore configuration via the disk-store element.

For example:

DiskStores are used by Regions for file system persistent backup and overflow of evicted entries as well as persistent backup of WAN Gateways. Multiple GemFire components may share the same DiskStore. Additionally, multiple file system directories may be defined for a single DiskStore.

Please refer to Pivotal GemFire’s documentation for a complete explanation of the configuration options.

Spring Data GemFire supports Cache and Region snapshots using Pivotal GemFire’s Snapshot Service. The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of GemFire’s Cache and Region Snapshot Service APIs.

As the Pivotal GemFire documentation describes, snapshots allow you to save and subsequently reload the cached data later, which can be useful for moving data between environments, such as from production to a staging or test environment in order to reproduce data-related issues in a controlled context. You can imagine combining Spring Data GemFire’s Snapshot Service support with Spring’s bean definition profiles to load snapshot data specific to the environment as necessary.

Spring Data GemFire’s support for Pivotal GemFire’s Snapshot Service begins with the <gfe-data:snapshot-service> element from the <gfe-data> namespace.

For example, I might want to define Cache-wide snapshots to be loaded as well as saved using a couple snapshot imports and a data export definition as follows:

You can define as many imports and/or exports as you like. You can define just imports or just exports. The file locations and directory paths can be absolute, or relative to the Spring Data GemFire application, JVM process’s working directory.

This is a pretty simple example and the Snapshot Service defined in this case refers to the GemFire Cache with the default name of gemfireCache (as described in Configuring a Cache). If you name your cache bean definition something other than the default, than you can use the cache-ref attribute to refer to the cache bean by name:

It is also straightforward to define a Snapshot Service for a particular GemFire Region by specifying the region-ref attribute:

When the region-ref attribute is specified, Spring Data GemFire’s SnapshotServiceFactoryBean resolves the region-ref attribute value to a Region bean defined in the Spring context and proceeds to create a RegionSnapshotService. The snapshot import and export definitions function the same way, however, the location must refer to a file on export.

Spring Data GemFire provides annotation support for implementing and registering Pivotal GemFire Functions.

Spring Data GemFire also provides namespace support for registering Pivotal GemFire Functions for remote Function execution.

Please refer to Pivotal GemFire' documentation for more information on the Function execution framework.

GemFire Functions are declared as Spring beans and must implement the org.apache.geode.cache.execute.Function interface or extend org.apache.geode.cache.execute.FunctionAdapter.

The namespace uses a familiar pattern to declare functions:

WAN Gateways provide a way to synchronize Pivotal GemFire Distributed Systems across geographic areas. Spring Data GemFire provides namespace support for configuring WAN Gateways as illustrated in the following examples.

Pivotal GemFire can be very difficult to setup and use successfully given all the configuration properties, configuration options (cache.xml, Gfsh + Cluster Configuration, Spring XML/Java-based configuration) along with different supported topologies (client/server, P2P, WAN) and Distributed System Design Patterns (e.g. shared-nothing architecture). The Annotation-based configuration model aims to simplify all this plus more.

The Annotation-based configuration model is an alternative to XML-based configuration using Spring Data GemFire’s XML Namespace. With XML, an application developer would use the spring-gemfire (gfe) schema for configuration and the spring-data-gemfire (gfe-data) schema for data access related concerns. See Bootstrapping Pivotal GemFire with the Spring Container for more details.

Like Spring Boot, Spring Data GemFire’s Annotation-based configuration model was designed as an opinionated, convention over configuration approach for using Pivotal GemFire. Indeed, the Annotation-based configuration model was inspired by Spring Boot as well as several other Spring and Spring Data projects.

By following convention, all Annotations provide reasonable and sensible defaults for all the attributes out-of-the-box. The default value for a given Annotation attribute directly corresponds to the default value provided in Pivotal GemFire for the same configuration property or setting.

The intention is to let an application developer enable an Pivotal GemFire feature or an embedded service by simply declaring the Annotation on his/her Spring @Configuration or @SpringBootApplcation class without needing to unnecessarily configure a large number of attributes or properties just to use the feature.

Again, getting up and running as quickly and as easily as possible is the primary objective.

However, the option to customize the configuration meta-data and behavior of Pivotal GemFire is there should an application developer need it and Spring Data GemFire’s Annotation-based configuration will quietly back away. The application developer simply just needs to specify the configuration attributes s/he wishes to adjust. And, as we will see below, there are several ways to configure an Pivotal GemFire feature or embedded service using Annotations.

All the new SDG Annotations can be found in the org.springframework.data.gemfire.config.annotation package.

Like all Spring Boot applications that begin by annotating the application class with @SpringBootApplication, a Spring Boot application can easily become an Pivotal GemFire cache application simply by declaring 1 of 3 main Annotations:

These 3 Annotations are the Spring/Pivotal GemFire application developer’s starting point.

To realize the intent behind these Annotations, a user must understand that there are 2 types of cache instances that can be created with Pivotal GemFire: a client or a peer.

A Spring Boot application can be configured as an Pivotal GemFire cache client (i.e. with an instance of ClientCache), which communicates with an existing, standalone cluster of Pivotal GemFire servers used to manage the application’s data. The client/server topology is the most typical system architecture employed when using Pivotal GemFire and the user can make her Spring Boot application a cache client simply by annotating it with @ClientCacheApplication.

Alternatively, a Spring Boot application may be a peer member of an Pivotal GemFire cluster. That is, the application itself is just another server in the cluster of servers that will manage data. The application creates an "embedded" peer Cache instance when a developer annotates his/her application class with @PeerCacheApplication.

By extension, the application may also serve as a CacheServer for cache clients, allowing clients to connect and perform data access operations on the server. This is accomplished by annotating the application class with @CacheServerApplication in place of @PeerCacheApplication, which will create a peer Cache instance along with the CacheServer.

By way of example, if I wanted to create a Spring Boot, Pivotal GemFire cache client application, I would start with…​

And, if I wanted to create a Spring Boot application with an embedded peer Cache instance, where my application will be a server and peer member of a cluster, or distributed system formed by Pivotal GemFire, then I would start with…​

Alternatively, a user may use the @CacheServerApplication annotation in place of @PeerCacheApplication, which will create both an "embedded" peer Cache instance along with a CacheServer running on "localhost", listening on the default cache server port, 40404…​

There are multiple ways that a client can connect to and communicate with servers in a GemFire cluster. The most common and recommended approach is to use Pivotal GemFire Locators.

Since Pivotal GemFire sets up a "DEFAULT" Pool connected to a CacheServer running on "localhost", listening on port 40404 by default when a ClientCache instance is created, there is nothing special a user need do to utilize the client/server topology. Simply annotate your server-side Spring Boot application with @CacheServerApplication and your client-side Spring Boot application with @ClientCacheApplication and you are all set.

You can even start your servers using Gfsh’s start server command if you prefer. Your Spring Boot @ClientCacheApplication will still connect to the server regardless of how it is started. Although, we think you will prefer to configure and start your servers using the Spring Data GemFire approach, with Annotations.

However, as an application developer, you will no doubt want to customize the "DEFAULT" Pool setup by Pivotal GemFire to possibly connect to 1 or more Locators, for instance…​

Along with the locators attribute, the @ClientCacheApplication annotation has a servers attribute that can be used to specify 1 or more nested @Server annotations that enable the cache client to connect directly to 1 or more servers.

A user may also configure additional Pools, other than the "DEFAULT" Pool provided by Pivotal GemFire when a ClientCache instance is created with the @ClientCacheApplication annotation, by using the @EnablePool and @EnablePools annotations.

The name attribute is the only required attribute of the @EnablePool annotation. As we will see below, the value of name corresponds to both the name of the Pool bean created in the Spring context as well as the name used to reference the corresponding configuration properties. It is also the name of the Pool registered and used in Pivotal GemFire.

Similarly, on the server, a user can configure multiple CacheServers that a client can connect to…​

One thing an observant reader may have noticed is, in all cases, the user is specifying hard-coded values for hostnames, ports as well other configuration-oriented Annotation attributes. This is not ideal when a user’s application gets promoted and deployed to different environments, such as from DEV to QA to STAGING to PROD.

How does an application developer handle dynamic configuration determined at runtime?

Another goal when designing the Annotation-based configuration model was to preserve Type-Safety in the Annotation attributes. For example, if an attribute could be expressed as an int, like a port number, then the attribute’s type should be an int.

Unfortunately, this is not conducive to dynamic and resolvable configuration at runtime.

One of the finer features of Spring is the ability to use property placeholders or SpEL expressions in properties or attributes of the configuration meta-data when configuring beans in a Spring context. Although, this would require all Annotation attributes be Strings thereby giving up Type-Safety; not acceptable!

So, Spring Data GemFire borrows from another commonly used pattern in Spring, Configurers. Many different Configurer interfaces are provided out-of-the-box in Spring Web MVC, such as the org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer.

Configurers are a way to allow application developers to receive a callback and customize the configuration of a component on startup. The framework calls back to user-provided code to adjust the configuration at runtime. One of the more common uses of this pattern is to supply conditional configuration based on the application’s runtime environment.

Spring Data GemFire provides several Configurer callback interfaces to customize different aspects of Annotation-based configuration meta-data at runtime, before the Sring managed beans that the Annotations create are initialized:

For example, we can use the CacheServerConfigurer and ClientCacheConfigurer to customize the port numbers used by our CacheServer and ClientCache applications, respectively.

First, in our server application…​

Then, in our client application…​

By using the provided Configurers, a user is able to receive a callback in order to further customize the configuration that is enabled by the associated Annotation.

In addition, when the Configurer is declared as a bean in the Spring context, the bean definition can take advantage of other Spring container features, such as property placeholders, or SpEL expressions in @Value annotations on factory method parameters, and so on.

All Spring Data GemFire-provided Configurers take 2 bits of information in the callback: the name of the bean created in the Spring context by the Annotation along with a reference to the FactoryBean used by the Annotation to configure the GemFire component (e.g. a ClientCache instance with SDG’s ClientCacheFactoryBean).

Given a Configurer can be declared as a regular bean definition like any other, it is not difficult to imagine a user combining different Spring configuration options, such as the use of Spring Profiles with Conditions as well as other features to create even more sophisticated and flexible configuration.

However, Configurers are not the only option.

In addition to Configurers, each Annotation attribute in the Annotation-based configuration model is associated with a corresponding configuration property, prefixed with spring.data.gemfire., that can be declared in Spring Boot application.properties.

Building on our examples above, the client’s application.properties would define…​

And, the server’s application.properties would define…​

Then, we can simplify the @ClientCacheApplication class to…​

And, the @CacheServerApplication class as…​

The example above illustrates why it is import to "name" your Annotation-based beans (other than it is required in certain cases). Doing so makes it possible to reference the bean in a Spring context from XML, properties and even Java. It is even possible to inject Annotation-defined beans into an application class, for whatever purpose; for example…​

Likewise, naming a Annotated-defined bean allows you to code a Configurer to customize a specific, "named" bean since the beanName is 1 of 2 arguments passed to the callback.

Often times, an associated Annotation attribute property takes 2 forms: a "named" property along with an "unnamed" property.

For example…​

While there are 3 named CacheServers above, there is 1 unnamed CacheServer property that serves as the default value for any unspecified value for that property even for "named" CacheServers. So, while "Venus" sets and overrides its own bind-address, "Saturn" and "Neptune" inherit from the unnamed spring.data.gemfire.cache.server.bind-address property.

Refer to an Annotation’s Javadoc for which Annotation attributes support property-based configuration, and whether they support "named" properties over just "default", unnamed properties.

Pivotal GemFire provides the ability to start many different embedded services required by an application depending on the use case.

Often times it is necessary to turn up logging in order to understand exactly what Pivotal GemFire is doing and when.

To enable Logging, simply annotate your application class with @EnableLogging and set the appropriate attributes or associated properties…​

While the logLevel attribute can be specified with all the cache-based application annotations (e.g. @ClientCacheApplication(logLevel="info")), it is easier to customize logging behavior with the @EnableLogging annotation.

See the @EnableLogging annotation Javadoc for more details.

To gain even deeper insight into Pivotal GemFire during runtime, an application developer can enable Statistics. Gathering statistical data facilitates system analysis and troubleshooting when complex problems occur, which are often distributed in nature and timing is a factor.

When Statistics are enabled, a user can use Pivotal GemFire’s VSD (Visual Statistics Display) tool to analyze the statistical data that is collected.

To enable Statistics, simply annotate your application class with @EnableStatistics…​

Enabling Statistics on a server is particularly valuable when evaluating performance, which is as simple as annotating your @PeerCacheApplication or @CacheServerApplication class with @EnableStatistics.

Use the @EnableStatistics annotation attributes or associated properties to customize the Statistics gathering and collection process.

See the @EnableStatistics annotation Javadoc for more details.

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

One of the more powerful features of Pivotal GemFire is PDX Serialization. While a complete discussion on PDX is well beyond the scope of this document, serialization using PDX is a much better alternative to Java Serialization, with the following benefits…​

In general, serialization in Pivotal GemFire is needed anytime data is transferred to/from clients and servers or between peers in a cluster for normal distribution and replication processes as well as when data is overflowed or persisted to disk.

To enable PDX, simply annotate your application class with @EnablePdx…​

Typically, an application’s domain object types will either implement the org.apache.geode.pdx.PdxSerializable interface, or an application developer will choose to implement and register the non-invasive org.apache.geode.pdx.PdxSerializer interface to handle the application domain object types that need to be serialized.

Unfortunately, Pivotal GemFire only allows one PdxSerializer to be registered, which suggests that all application domain object types should be handled by a "single" PdxSerializer instance. But, that is a serious anti-pattern and foolish practice to be sure.

Even though only a single PdxSerializer instance can be registered with Pivotal GemFire, it makes sense to create a PdxSerializer implementation per application domain object type.

By using the Composite Software Design Pattern, the application developer can provide an implementation of the PdxSerializer interface that aggregates of all application domain object type-specific PdxSerializer instances but acts as a single PdxSerializer instance, and register it.

You can declare this Composite PdxSerializer as a managed bean in the Spring context and refer to this Composite PdxSerializer by bean name in the @EnablePdx annotation using the serializerBeanName attribute. Spring Data GemFire will take care of registering it with Pivotal GemFire on the user’s behalf.

It is also possible to declare Pivotal GemFire’s org.apache.geode.pdx.ReflectionBasedAutoSerializer as a bean definition in a Spring context. Alternatively, you can use Spring Data GemFire’s more robust, org.springframework.data.gemfire.mapping.MappingPdxSerializer, which uses Spring Data mapping meta-data and infrastructure applied to the serialization process for more efficient handling than reflection alone.

Many other aspects and features of PDX can be adjusted with the @EnablePdx annotation attributes or associated configuration properties.

See the @EnablePdx annotation Javadoc for more details.

Equally important to serializing data to be transferred over-the-wire is securing the data while in transit. Of course, the common way to accomplish this in Java is using the Secure Sockets Extension (SSE) and Transport Layer Security (TLS).

To enable SSL, simply annotate your application class with @EnableSsl and set the necessary SSL configuration attributes (e.g. keystores, usernames/passwords, etc)…​

Different Pivotal GemFire components: GATEWAY, HTTP, JMX, LOCATOR, SERVER can be individually configured with SSL, or they can all be collectively configured all at once to use SSL using the CLUSTER enumerated value.

It is easy to specify which Pivotal GemFire components that the SSL configuration settings should applied to using the nested @EnableSsl annotation Component enum…​

In addition component-level SSL configuration, ciphers, protocols and keystore/truststore information can also be specified using the corresponding Annotation attribute or associated configuration properties.

See the @EnableSsl annotation Javadoc for more details.

More details on Pivotal GemFire SSL support can be found here.

While many of the gemfire.properties are conveniently encapsulated in and abstracted with an Annotation in the SDG Annotation-based configuration model, the less commonly used GemFire Properties are still accessible from the @EnableGemFireProperties annotation.

Using the @EnableGemFireProperties annotation on your application class is convenient and a nice alternative to creating a gemfire.properties file or setting GemFire Properties as Java System properties on the command-line when launching your application.

A few examples of some of the less common GemFire Properties that a user usually need not worry about include, but are not limited to: ack-wait-threshold, disable-tcp, socket-buffer-size, etc.

To individually set any GemFire Property, simply annotate your application class with @EnableGemFireProperties and set the GemFire Properties you want to change from the default, out-of-the-box value set by Pivotal GemFire…​

Keep in mind, some of the GemFire Properties are client specific (e.g. conflateEvents) while others are server specific (e.g. distributedSystemId, enableNetworkPartitionDetection, enforceUniqueHost, memberTimeout, redundancyZone).

More details on Pivotal GemFire properties can be found here.

So far, outside of PDX, our discussion has centered around configuring Pivotal GemFire’s more administrative functions: creating a cache instance, starting embedded services, enabling Logging, Statistics and SSL, using gemfire.properties to affect very low-level configuration and behavior. While all these configuration options are important, none of them relate directly to the application. In other words, we still need some place to store our application data and make it generally available and accessible.

Pivotal GemFire organizes data in a cache into Regions. You can think of a Region as a table in a relational database. Generally, a Region should only store a single type of object making it more conducive for building effective Indexes. We will talk about Indexing later.

Previously, Spring Data GemFire users needed to explicitly define and declare the Regions used in their applications to store data by writing very verbose Spring configuration meta-data, whether a user was using SDG’s FactoryBeans from the API in Spring’s Java-based container configuration…​

Or, using XML…​

While neither Java nor XML configuration is hard to do, it is cumbersome, especially if an application has a large number of Regions that need to be defined. Many relational database-based applications can literally have 100s or even 1000s of tables.

Ugh!

Now users can define and configure Regions based on their application domain objects (entities). No longer does a user need to explicitly define Region bean definitions in Spring configuration meta-data, unless finer-grained control is required.

To simplify Region creation, Spring Data GemFire combines the use of SD Repositories with the expressive power of Annotation-based configuration using the new @EnableEntityDefinedRegions annotation.

First, an application developer starts by defining the application domain objects…​

Next, the application developer would define a basic Repository for Books by extending Spring Data Commons org.springframework.data.repository.CrudRepository interface…​

The org.springframe.data.repository.CrudRepository is a Data Access Object (DAO) providing basic data access operations (CRUD) along with support for simple queries (e.g. findById(..)). The user can define additional, more sophisticated queries simply by declaring query methods on the Repository interface (e.g. List<BooK> findByAuthor(Author author);).

Under-the-hood, Spring Data GemFire provides an implementation of this interface when the Spring container is bootstrapped. SDG will even implement the query methods defined by the user so long as the user follows simple conventions.

Now, when a user defined the Book class, she also specified the Region in which instances of Book will be mapped and stored by declaring the Spring Data GemFire mapping annotation, @Region on the entity’s type. Of course, if the entity type (i.e. Book) referenced in the type parameter of the Repository interface (i.e. BookRepository) is not annotated with @Region, the name is derived from the simple class name of the entity type (i.e. "Book").

Spring Data GemFire uses the mapping context containing mapping meta-data for all the entities defined in your application to determine all the Regions that will be needed at runtime.

To enable and use this feature, simply annotate the application class with @EnableEntityDefinedRegions…​

By default, the @EnableEntityDefinedRegions annotation will scan for entity classes recursively starting from the package of the configuration class on which the @EnableEntityDefinedRegions annotation is defined.

However, it is common to limit the search during the scan by setting the basePackages attribute with the package names containing your application entity classes.

Alternatively, a user can use the more type-safe basePackageClasses attribute for specifying the package to scan by setting the attribute to an entity type in the package containing the entity’s class, or by using a non-entity placeholder class in the package specifically created for identifying the package to scan. For example…​

In addition to specifying the location where to begin the scan, like Spring’s @ComponentScan annotation, a user can specify include and exclude filters with all the same semantics of the org.springframework.context.annotation.ComponentScan.Filter annotation.

See the @EnableEntityDefinedRegion annotation Javadoc for more details.

Another very important and useful feature of Pivotal GemFire is Continuous Querying.

In a world of Internet-enabled things, events and streams of data are coming in from everywhere. Being able to handle and process a large stream of data and react to events in real-time, as they happen, is becoming an increasingly important requirement for many applications. One example is self-driving vehicles. Being able to receive, filter, transform, analyze and act on data in real-time is a key differentiator and characteristic of real-time enabled applications.

Fortunately, Pivotal GemFire was ahead of its time in this regard. Using Continuous Queries (CQ) a client application can express the data, or events it is interested in and register listeners to handle and process the events as they arrive. The data that a client application may be interested in is expressed in a OQL query, where the query predicate is used to filter, or identify the data of interests. When data is changed or added and it matches the criteria defined in the query predicate of the registered CQ, the client application is notified.

Spring Data GemFire makes defining and registering CQs along with an associated listener to handler and process CQ events without all the cruft of Pivotal GemFire’s plumbing, a non-event (no pun intended). SDG’s new Annotation-based configuration for CQs builds on the already existing Continuous Query support in the Continuous Query Listener Container.

For instance, say a Book publisher wants to register interests in and receive notification anytime orders (demand) for a Book exceeds the current inventory (supply), then the publisher’s print application might register the following CQ…​

To enable Continuous Queries, simply annotate your application class with @EnableContinuousQueries.

Defining Continuous Queries is as simple as annotating any Spring @Component annotated POJO class methods with the @ContinuousQuery annotation, in similar fashion to SDG’s Function annotated POJO methods. A method defined with a CQ using the @ContinuousQuery annotation will be called anytime data matching the query predicate is added or changed.

Additionally, the POJO method signature should adhere to the requirements outlined in the section on ContinuousQueryListener and ContinuousQueryListenerAdapter.

See the @EnableContinuousQueries and @ContinuousQuery annotation Javadoc for more details on available attributes and configuration settings.

More details on Spring Data GemFire’s Continuous Query support can be found here.

More details on Pivotal GemFire’s Continuous Queries can be found here.

With Spring Data GemFire, Pivotal GemFire can be used as a caching provider in Spring’s Cache Abstraction.

In Spring’s Cache Abstraction, the caching annotations (e.g. @Cacheable) identify the cache on which a cache lookup is performed before invoking a potentially expensive operation, or where the results of an application service method are cached after the operation is invoked.

In Spring Data GemFire, a Spring Cache corresponds directly to a Region. The Region must exist before any @Cacheable application service method is called. This is true for any of Spring’s caching annotations (i.e. @Cacheable, @CachePut and @CacheEvict) that identify the cache to use in the operation.

For instance, our publisher’s Point-of-Sale (POS) application might have a feature to determine, or lookup the Price of a Book during a sales transaction.

To make the application developer’s life easier when using Spring Data GemFire and Pivotal GemFire with Spring’s Cache Abstraction, 2 new features have been added to the new Annotation-based configuration model.

Given the following Spring caching configuration…​

Using Spring Data GemFire’s new features, the same caching configuration can be simplified to…​

First, the @EnableGemfireCaching annotation replaces both the Spring EnableCaching annotation along with the need to declare an explicit cacheManager bean definition in the Spring config.

Second, the @EnableCachingDefinedRegions annotation, like the @EnableEntityDefinedRegions annotation described in Configuring Regions, inspects all the Spring caching annotated application service components to identify all the caches that will be needed by the application at runtime and creates Regions in Pivotal GemFire for these caches on application startup.

The Region created is local to the application process that created the Region. If the application is a peer Cache, then the Region will only exist on the application node. If the application is a ClientCache, then SDG creates a client PROXY Region and expects that a Region with the same name already exists on the servers in the cluster.

Refer to the section, Support for the Spring Cache Abstraction for more details on using Pivotal GemFire as a caching provider in Spring’s Cache Abstraction.

More details on Spring’s Cache Abstraction can be found here.

This may be the most exciting new feature in Spring Data GemFire.

When a client application class is annotated with @EnableClusterConfiguration, any Regions or Indexes defined and declared as beans in the Spring context by the client application are "pushed" to the cluster of servers to which the client is connected. Not only that, but this "push" is performed in such a way that Pivotal GemFire will remember the configuration pushed by the client. If all the nodes in the cluster go down, they will come back up with the same configuration as before.

In a sense, this feature is not much different than if a user were to use Gfsh to create the Regions and Indexes on all the servers in the cluster. Except now, with Spring Data GemFire, users does not need to use Gfsh to create Regions and Indexes. The user’s Spring Boot application, enabled with the power of Spring Data GemFire, already contains all the configuration meta-data SDG needs to create Regions and Indexes for the user.

When users are using the Spring Data Repository abstraction, we know all the Regions (e.g. @Region annotated entity types) and Indexes (e.g. @Indexed annotated entity fields and properties) that the users' application will need. When users are using Spring’s Cache Abstraction, we also know all the Regions for all the caches identified in the caching annotations that the application is going to need. Essentially, the user is already telling us everything we need to know just by developing her application with the entire Spring Framework and all of its provided services, infrastructure, etc, whether expressed in Annotation meta-data, Java, XML or otherwise, and whether for configuration, for mapping, or whatever purpose.

The user can focus on her application business logic along with using the framework provided services and supporting infrastructure (e.g. Spring Data Repositories, Spring’s Transaction Management, Spring Caching, etc) and Spring Data GemFire will take care of all the Pivotal GemFire plumbing required by those framework services on the user’s behalf.

Pushing configuration from the client to the servers in the cluster and having the cluster remember it is made possible in part by the use of Pivotal GemFire’s Cluster Configuration service. Pivotal GemFire’s Cluster Configuration service is also the same service used by Gfsh to record schema-related changes issued by the user to the cluster from the shell.

Of course, since the cluster "remembers" the prior configuration pushed by a client from a previous run perhaps, Spring Data GemFire is careful not to stomp on any existing Regions and Indexes already defined in the servers. This is especially important when Regions already contain data.

For a moment, imagine the power expressed in the following configuration…​

An application developer instantly gets a Spring Boot, Pivotal GemFire ClientCache application using Spring Data Repositories with Spring’s Cache Abstraction, using Pivotal GemFire as the caching provider, where Regions and Indexes are not only created on the client, but pushed to the servers in the cluster.

All the application developer need do is define the application’s domain model objects annotated with mapping and Index annotations, define Repository interfaces supporting basic data access operations and querying for each of the entity types, define the service components containing the business logic manipulating the entities, declare the appropriate annotations on service methods that require caching, transactional behavior, etc, and the developer is in business. Nothing the user did in this case pertains to infrastructure and plumbing required in the application’s back-end services (e.g. Pivotal GemFire). Database users have similar features, no Spring, Pivotal GemFire developers can too.

When combined with a couple more Spring Data GemFire Annotations…​

Then, the application is really going to start to take flight.

See the @EnableClusterConfiguration annotation Javadoc for more details.

Without a doubt, application Security is extremely important and Spring Data GemFire provides comprehensive support for securing both Pivotal GemFire clients and servers.

Recently, Pivotal GemFire introduced a new Integrated Security framework, replacing its old Authentication and Authorization Security model, for handling authentication and authorization. One of the main features and benefits of this new Security framework is that it integrates with Apache Shiro and can therefore delegate both authentication and authorization requests to Apache Shiro when enforcing security.

The following demonstrates how Spring Data GemFire can simplify Pivotal GemFire’s Security story even further.

The following tips will help users get the most out of using the new Annotation-based configuration model.

As we saw in the section on Configuring Cluster Configuration Push, when many Pivotal GemFire and/or Spring Data GemFire features are enabled using Annotations, we start 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, given…​

We could break this configuration down by concern. For example…​

Spring does not care. Organize your application configuration as you see fit.

SDG Annotations you never heard of…​

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

As we learned in the previous sections, there is a tremendous amount of power provided by Spring Data GemFire's new Annotation-based configuration model. Hopefully, it lives up to its goal of making it easier for users to get started quickly when using Pivotal GemFire with Spring.

Keep in mind when using the new Annotations that it does not preclude you, the application developer, from using Java config, or even XML, if you prefer. You can even combine all 3 approaches by using Spring’s @Import and @ImportResource annotations on a Spring @Configuration or @SpringBootApplication class, if you like. The moment you explicitly provide a bean definition that would otherwise be provided by Spring Data GemFire using an Annotation, the Annotation-based configuration backs away.

In certain cases you may even need to fallback to Java config, as in the Configurers case, to handle more complex or conditional configuration logic that is not easily expressed in or cannot be accomplished using Annotations. Do not be alarmed; this is to be expected.

For example, another case where Java config or XML will be needed is when configuring Pivotal GemFire WAN components, which currently do not have any Annotation configuration support. However, defining and registering WAN components is as simple as using the org.springframework.data.gemfire.wan.GatewaReceiverFactoryBean and org.springframework.data.gemfire.wan.GatewaySenderFactoryBean API classes in Java configuration on your Spring @Configuration or @SpringBootApplication classes (recommended).

The Annotations were not meant to handle every situation; the Annotations were meant to help application developers get up and running as quickly and as easily as possible, especially during development.

As with many other high-level abstractions provided by Spring projects, Spring Data GemFire provides a template to simplify GemFire data access. The class provides several one-liner methods containing common Region operations, but also has the ability to execute code against the native GemFire API without having to deal with GemFire checked exceptions by using a GemfireCallback.

The template class requires a GemFire Region instance, and once configured, is thread-safe and can be reused across multiple application classes:

Once the template is configured, a developer can use it alongside GemfireCallback to work directly with the GemFire Region without having to deal with checked exceptions, threading or resource management concerns:

For accessing the full power of the Pivotal GemFire query language, a developer can use the find and findUnique methods, which, as opposed to the query method, can execute queries across multiple Regions, execute projections, and the like.

The find method should be used when the query selects multiple items (through`SelectResults`) and the latter, findUnique, as the name suggests, when only one object is returned.

Using a new data access technology requires not only accommodating a new API but also handling exceptions specific to that technology.

To accommodate the exception handling case, the Spring Framework provides a technology agnostic and consistent exception hierarchy that abstracts the application from proprietary, and usually "checked", exceptions to a set of focused runtime exceptions.

As mentioned in Spring Framework’s documentation, Exception translation can be applied transparently to your Data Access Objects (DAO) through the use of the @Repository annotation and AOP by defining a PersistenceExceptionTranslationPostProcessor bean. The same exception translation functionality is enabled when using GemFire as long as the CacheFactoryBean is declared, e.g. using either a <gfe:cache/> or <gfe:client-cache> declaration, which acts as an exception translator and is automatically detected by the Spring infrastructure and used accordingly.

One of the most popular features of the Spring Framework is Transaction Management.

If you are not familiar with Spring’s transaction abstraction then we strongly recommend reading about Spring’s Transaction Management infrastructure as it offers a consistent programming model that works transparently across multiple APIs and can be configured either programmatically or declaratively (the most popular choice).

For Pivotal GemFire, Spring Data GemFire provides a dedicated, per-cache, PlatformTransactionManager that, once declared, allows Region operations to be executed atomically through Spring:

Currently, Pivotal GemFire supports optimistic transactions with read committed isolation. Furthermore, to guarantee this isolation, developers should avoid making in-place changes that manually modify values present in the cache. To prevent this from happening, the transaction manager configures the cache to use copy on read semantics by default, meaning a clone of the actual value is created each time a read is performed. This behavior can be disabled if needed through the copyOnRead property.

For more information on the semantics and behavior of the underlying Geode transaction manager, please refer to the Geode CacheTransactionManager Javadoc as well as the documentation.

It is also possible for Pivotal GemFire to participate in a Global, JTA based transaction, such as a transaction managed by an Java EE Application Server (e.g. WebSphere Application Server, a.k.a. WAS) using Container Managed Transactions (CMT) along with other JTA resources.

However, unlike many other JTA "compliant" resources (e.g. JMS Message Brokers like ActiveMQ), Pivotal GemFire is not an XA compliant resource. Therefore, Pivotal GemFire must be positioned as the "Last Resource" in a JTA transaction (prepare phase) since it does not implement the 2-phase commit protocol, or rather does not handle distributed transactions.

Many managed environments with CMT maintain support for "Last Resource", non-XA compliant resources in JTA transactions though it is not actually required in the JTA spec. More information on what a non-XA compliant, "Last Resource" means can be found in Red Hat’s documentation. In fact, Red Hat’s JBoss project, Narayana is one such LGPL Open Source implementation. Narayana refers to this as "Last Resource Commit Optimization" (LRCO). More details can be found here.

However, whether you are using Pivotal GemFire in a standalone environment with an Open Source JTA Transaction Management implementation that supports "Last Resource", or a managed environment (e.g. Java EE AS such as WAS), Spring Data Geode has you covered.

There are a series of steps you must complete to properly use Pivotal GemFire as a "Last Resource" in a JTA transaction involving more than 1 transactional resource. Additionally, there can only be 1 non-XA compliant resource (e.g. Pivotal GemFire) in such an arrangement.

1) First, you must complete Steps 1-4 in GemFire’s documentation here.

2) Referring to Step 5 in GemFire’s documentation, Spring Data GemFire’s Annotation support will attempt to set the GemFireCache, copyOnRead property for you when using the @EnableGemFireAsLastResource annotation.

However, if SDG’s auto-configuration is unsuccessful then you must explicitly set the copy-on-read attribute on the <gfe:cache> or <gfe:client-cache> element in XML or the copyOnRead property of the SDG CacheFactoryBean class in JavaConfig to true. For example…​

Peer Cache XML:

Peer Cache JavaConfig:

Client Cache XML:

Client Cache JavaConfig:

3) At this point, you skip Steps 6-8 in GemFire’s documentation and let Spring Data Geode work its magic. All you need do is annotate your Spring @Configuration class with Spring Data GemFire’s new @EnableGemFireAsLastResource annotation and a combination of Spring’s Transaction Management infrastructure and Spring Data GemFire’s @EnableGemFireAsLastResource configuration does the trick.

The configuration looks like this…​

The only requirements are…​

3.1) The @EnableGemFireAsLastResource annotation must be declared on the same Spring @Configuration class where Spring’s @EnableTransactionManagement annotation is also specified.

3.2) The order attribute of the @EnableTransactionManagement annotation must be explicitly set to an integer value that is not Integer.MAX_VALUE or Integer.MIN_VALUE (defaults to Integer.MAX_VALUE).

Of course, hopefully you are aware that you also need to configure Spring’s JtaTransactionManager when using JTA Transactions like so..

For more details on using Spring’s Transaction Management with JTA, see here.

Effectively, Spring Data GemFire’s @EnableGemFireAsLastResource annotation imports configuration containing 2 Aspect bean definitions that handles the GemFire o.a.g.ra.GFConnectionFactory.getConnection() and o.a.g.ra.GFConnection.close() operations at the appropriate points during the transactional operation.

Specifically, the correct sequence of events are…​

This is consistent with how you, as the application developer, would code this manually if you had to use the JTA API + GemFire API yourself, as shown in the GemFire example.

Thankfully, Spring does the heavy lifting for you and all you need do after applying the appropriate configuration (shown above) is…​

#1 & #4 above are appropriately handled for you by Spring’s JTA based PlatformTransactionManager once the @Transactional boundary is entered by your application (i.e. when the MyTransactionSerivce.someTransactionalMethod() is called).

#2 & #3 are handled by Spring Data GemFire’s new Aspects enabled with the @EnableGemFireAsLastResource annotation.

#3 of course is the responsibility of your application.

Indeed, with the appropriate logging configured, you will see the correct sequence of events…​

For more details on using Pivotal GemFire in JTA transactions, see here.

For more details on configuring Pivotal GemFire as a "Last Resource", see here.

A powerful functionality offered by Pivotal GemFire is Continuous Query (or CQ). In short, CQ allows one to create and register an OQL query, and then automatically be notified when new data that gets added to GemFire matches the query predicate. Spring Data GemFire provides dedicated support for CQs through the org.springframework.data.gemfire.listener package and its listener container; very similar in functionality and naming to the JMS integration in the Spring Framework; in fact, users familiar with the JMS support in Spring, should feel right at home.

Basically Spring Data GemFire allows methods on POJOs to become end-points for CQ. Simply define the query and indicate the method that should be called to be notified when there is a match. Spring Data GemFire takes care of the rest. This is very similar to Java EE’s message-driven bean style, but without any requirement for base class or interface implementations, based on Pivotal GemFire.

Pivotal GemFire XML configuration (usually referred to as cache.xml) allows user objects to be declared as part of the configuration. Usually these objects are CacheLoaders or other pluggable callback components supported by GemFire. Using native GemFire configuration, each user type declared through XML must implement the Declarable interface, which allows arbitrary parameters to be passed to the declared class through a Properties instance.

In this section, we describe how you can configure these pluggable components when defined in cache.xml using Spring while keeping your Cache/Region configuration defined in cache.xml. This allows your pluggable components to focus on the application logic and not the location or creation of DataSources or other collaborators.

However, if you are starting a green field project, it is recommended that you configure Cache, Region, and other pluggable GemFire components directly in Spring. This avoids inheriting from the Declarable interface or the base class presented in this section.

See the following sidebar for more information on this approach.

As an example of configuring a Declarable component using Spring, consider the following declaration (taken from the Declarable Javadoc):

To simplify the task of parsing, converting the parameters and initializing the object, Spring Data GemFire offers a base class (WiringDeclarableSupport) that allows GemFire user objects to be wired through a template bean definition or, in case that is missing, perform auto-wiring through the Spring IoC container. To take advantage of this feature, the user objects need to extend WiringDeclarableSupport, which automatically locates the declaring BeanFactory and performs wiring as part of the initialization process.

Spring Data GemFire provides an implementation of the Spring Cache Abstraction to position Pivotal GemFire as a caching provider in Spring’s caching infrastructure.

To use Pivotal GemFire as a backing implementation, a "caching provider" in Spring’s Cache Abstraction, simply add GemfireCacheManager to your configuration:

When the GemfireCacheManager (Singleton) bean instance is declared and declarative caching is enabled (either in XML with <cache:annotation-driven/> or in JavaConfig with Spring’s @EnableCaching annotation), the Spring caching annotations (e.g. @Cacheable) identify the "caches" that will cache data in-memory using GemFire Regions.

These caches (i.e. Regions) must exist before the caching annotations that use them otherwise an error will occur.

By way of example, suppose you have a Customer Service application with a CustomerService application component that performs caching…​

Then you will need the following config.

XML:

JavaConfig:

Of course, you are free to choose whatever Region type you like (e.g. REPLICATE, PARTITION, LOCAL, etc).

For more details on Spring’s Cache Abstraction, again, please refer to the documentation.

It is fairly common for serialized objects to have transient data. Transient data is often dependent on the system or environment where it lives at a certain point in time. For instance, a DataSource is environment specific. Serializing such information is useless, and potentially even dangerous, since it is local to a certain VM/machine. For such cases, Spring Data GemFire offers a special Instantiator that performs wiring for each new instance created by GemFire during deserialization.

Through such a mechanism, one can rely on the Spring container to inject and manage certain dependencies making it easy to split transient from persistent data and have rich domain objects in a transparent manner.

Spring users might find this approach similar to that of @Configurable). The WiringInstantiator works just like WiringDeclarableSupport, trying to first locate a bean definition as a wiring template and falling back to autowiring otherwise.

Please refer to the previous section (Wiring Declarable Components) for more details on wiring functionality.

To use this SDG Instantiator, simply declare it as a bean:

During the Spring container startup, once it is being initialized, the Instantiator will, by default, register itself with the GemFire serialization system and perform wiring on all instances of SomeDataSerializableClass created by GemFire during deserialization.

For data intensive applications, a large number of instances might be created on each machine as data flows in. Out-of-the-box, GemFire uses reflection to create new types, but for some scenarios, this might prove to be expensive. As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, Spring Data GemFire allows the automatic generation of Instatiator classes which instantiate a new type (using the default constructor) without the use of reflection:

The definition above, automatically generates two Instantiators for two classes, namely CustomTypeA and CustomTypeB and registers them with GemFire, under user id 1025 and 1026. The two Instantiators avoid the use of reflection and create the instances directly through Java code.

Spring Data GemFire provides support to map entities that will be stored in a Region in the GemFire In-Memory Data Grid. The mapping metadata is defined using annotations on application domain classes just like this:

The first thing you notice here is the @Region annotation that can be used to customize the Region in which an instance of the Person class is stored. The @Id annotation can be used to annotate the property that shall be used as the cache (Region) key, identifying the Region entry. The @PersistenceConstructor annotation helps to disambiguate multiple, potentially available constructors taking parameters and explicitly marking the constructor annotated as the constructor to be used to construct entities. In an application domain class with no or only a single constructor you can omit the annotation.

In addition to storing entities in top-level Regions, entities can be stored in Sub-Regions as well.

For instance:

Be sure to use the full-path of the GemFire Region, as defined with the Spring Data GemFire XML namespace using the id or name attributes of the <*-region> element.

Spring Data GemFire provides a custom PdxSerializer implementation that uses the mapping information to customize entity serialization. Beyond that, it allows customizing the entity instantiation by using the Spring Data EntityInstantiator abstraction. By default the serializer uses a ReflectionEntityInstantiator that will use the persistence constructor of the mapped entity (either the default constructor, a singly declared constructor or an explicitly annotated constructor annotated with the @PersistenceConstructor annotation).

To provide values for constructor parameters it will read fields with name of the constructor parameters from the supplied PdxReader.

An entity class annotated in this way will have the field foo read from the PdxReader and passed to the constructor parameter value for firstname. The value for lastname will be the Spring bean with the name bean.

Spring Data GemFire provides support to use the Spring Data Repository abstraction to easily persist entities into GemFire along with execute queries. A general introduction to the Repository programming model is provided here.

To bootstrap Spring Data Repositories, you use the <repositories/> element from the Spring Data GemFire Data namespace:

This configuration snippet looks for interfaces below the configured base package and creates Repository instances for those interfaces backed by a SimpleGemFireRepository.

Alternatively, many users prefer to use Spring’s Java-based container configuration.

Using this approach, it is a simple matter to bootstrap Spring Data Repositories using the SDG @EnableGemfireRepositories annotation:

Rather than use the basePackages attribute, you may prefer to use the type-safe basePackageClasses attribute instead. The basePackageClasses allows you to specify the package containing all your application Repository classes by specifying just one of your application Repository interface types. Consider creating a special no-op marker class or interface in each package that serves no other purpose than to identify the location of application Repositories referenced by this attribute.

In addition to the basePackage[sClasses] attributes, like Spring’s @ComponentScan annotation, the @EnableGemfireRepositories annotation provides include and exclude filters, based on Spring’s ComponentScan.Filter type. You can use the filterType attribute to filter by different aspects, such as whether an application Repository type is annotated with a particular Annotation or extends a particular class type, and so on. See the FilterType Javadoc for more details.

The @EnableGemfireRepositories annotation also provides the ability to specify the location of named OQL queries, which reside in a Java Properties file, using the namedQueriesLocation attribute. The property name must match the name of a Repository query method and the property value is the OQL query you want executed when the Repository query method is called.

The repositoryImplementationPostfix attribute can be set to an alternate value (defaults to "Impl") if your application requires 1 or more custom Repository implementations. This feature is commonly used to extend the Spring Data Repository infrastructure in order to implement a feature not provided out-of-the-box (OOTB) by the data store (e.g. SDG).

One example of where custom Repository implementations are needed with Pivotal GemFire is when performing Joins. Joins are not supported by SDG Repositories OOTB. With a Pivotal GemFire PARTITION Region, the Join must be performed on collocated PARTITION Regions even, since Pivotal GemFire does not support "distributed" Joins. In addition, the Equi-Join OQL Query must be performed inside a GemFire Function. See here for more details on Pivotal GemFire Equi-Join Queries.

Many other aspects of the SDG’s Repository infrastructure extension maybe customized as well. See the @EnableGemfireRepositories Javadoc for more details on all configuration settings.

Spring Data GemFire Repositories enable the definition of query methods to easily execute GemFire OQL Queries against the Region the managed entity is mapped to.

The first query method listed here will cause the following OQL query to be derived: SELECT x FROM /People x WHERE x.emailAddress = $1. The second query method works the same way except it’s returning all entities found whereas the first query method expects a single result to be found.

In case the supported keywords are not sufficient to expresss and declare your OQL query, or the method name becomes too verbose, you can annotate the query methods with @Query as seen for methods 3 and 4.

Many query languages, such as Pivotal GemFire’s OQL (Object Query Language), have extensions that are not directly supported by Spring Data Commons' Repository infrastructure.

One of Spring Data Commons' Repository infrastructure goals is to function as the lowest common denominator in order to maintain support for and portability across the widest array of data stores available and in use for application development today. Technically, this means developers can access multiple different data stores supported by Spring Data Commons within their applications by reusing their existing application-specific Repository interfaces, a very convenient and powerful abstraction.

To support GemFire’s OQL Query language extensions and preserve portability across different data stores, Spring Data GemFire adds support for OQL Query extensions using Java Annotations. These Annotations will be ignored by other Spring Data Repository implementations (e.g. Spring Data JPA or Spring Data Redis) that do not have similar query language extensions.

For instance, many data stores will most likely not implement GemFire’s OQL IMPORT keyword. By implementing IMPORT as an Annotation (i.e. @Import) rather than as part of the query method signature (specifically, the method 'name'), then this will not interfere with the parsing infrastructure when evaluating the query method name to construct another data store language appropriate query.

Currently, the set of GemFire OQL Query language extensions that are supported by Spring Data GemFire include:

As an example, suppose you have a Customers application domain class and corresponding GemFire Region along with a CustomerRepository and a query method to lookup Customers by last name, like so…​

This will result in the following OQL Query:

<TRACE> <HINT 'LastNameIdx'> IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers x WHERE x.lastName = $1 LIMIT 10

Spring Data GemFire’s Repository extension and support is careful not to create conflicting declarations when the OQL Annotation extensions are used in combination with the @Query annotation.

As another example, suppose you have a raw @Query annotated query method defined in your CustomerRepository like so…​

This query method results in the following OQL Query:

IMPORT org.example.app.domain.Customer; <TRACE> <HINT 'ReputationIdx'> SELECT DISTINCT * FROM /Customers x WHERE x.reputation > $1 ORDER BY c.reputation DESC LIMIT 5

As you can see, the @Limit(10) annotation will not override the LIMIT defined explicitly in the raw query. As well, @Hint("CustomerIdx") annotation does not override the HINT explicitly defined in the raw query. Finally, the @Trace annotation is redundant and has no additional effect.

Spring Data GemFire includes annotation support to simplify working with GemFire Function Execution. Under-the-hood, the Pivotal GemFire API provides classes to implement and register GemFire Functions that are deployed on GemFire servers, which may then be invoked by other peer member applications or remotely from cache clients.

Functions can execute in parallel, distributed among multiple GemFire servers in the cluster, aggregating results with the map-reduce pattern that are sent back to the caller. Functions can also be targeted to run on a single server or Region. The Pivotal GemFire API supports remote execution of Functions targeted using various predefined scopes: on Region, on members [in groups], on servers, etc. The implementation and execution of remote Functions, as with any RPC protocol, requires some boilerplate code.

Spring Data GemFire, true to Spring’s core value proposition, aims to hide the mechanics of remote Function execution and allow developers to focus on core POJO programming and business logic. To this end, Spring Data GemFire introduces annotations to declaratively register public methods of a POJO class as GemFire Functions along with the ability to invoke registered Functions [remotely] via annotated interfaces.

There are two separate concerns to address implementation and execution.

First is Function implementation (server-side), which must interact with the FunctionContext to access the invocation arguments, ResultsSender as well as other execution context information. The Function implementation typically accesses the Cache and/or Regions and is registered with the FunctionService under a unique Id.

A cache client application invoking a Function does not depend on the implementation. To invoke a Function, the application instantiates an Execution providing the Function ID, invocation arguments and the Function target, which defines its scope: Region, server, servers, member or members. If the Function produces a result, the invoker uses a ResultCollector to aggregate and acquire the execution results. In certain cases, a custom ResultCollector implementation is required and may be registered with the Execution.

Using GemFire APIs, the FunctionContext provides a runtime invocation context that includes the client’s calling arguments and a ResultSender implementation to send results back to the client. Additionally, if the Function is executed on a Region, the FunctionContext is actually an instance of RegionFunctionContext, which provides additional information such as the target Region on which the Function was invoked and any Filter (set of specific keys) associated with the Execution, etc. If the Region is a PARTITION Region, the Function should use the PartitionRegionHelper to extract only the local data.

Using Spring, a developer can write a simple POJO and use the Spring container to bind one or more of it’s public methods to a Function. The signature for a POJO method intended to be used as a Function must generally conform to the client’s execution arguments. However, in the case of a Region execution, the Region data may also be provided (presumably the data held in the local partition if the Region is a PARTITION Region). Additionally, the Function may require the Filter that was applied, if any. This suggests that the client and server share a contract for the calling arguments but that the method signature may include additional parameters to pass values provided by the FunctionContext. One possibility is for the client and server to share a common interface, but this is not strictly required. The only constraint is that the method signature includes the same sequence of calling arguments with which the Function was invoked after the additional parameters are resolved.

For example, suppose the client provides a String and int as the calling arguments. These are provided in the FunctionContext as an array:

Object[] args = new Object[] { "test", 123 };

Then, the Spring container should be able to bind to any method signature similar to the following. Let’s ignore the return type for the moment:

The general rule is that once any additional arguments, i.e. Region data and Filter, are resolved, the remaining arguments must correspond exactly, in order and type, to the expected Function method parameters. The method’s return type must be void or a type that may be serialized (either as a java.io.Serializable, DataSerializable or PdxSerializable). The latter is also a requirement for the calling arguments. The Region data should normally be defined as a Map, to facilitate unit testing, but may also be of type Region if necessary. As shown in the example above, it is also valid to pass the FunctionContext itself, or the ResultSender, if you need to control how the results are returned to the client.

A process invoking a remote Function needs to provide the Function’s ID, calling arguments, the execution target (onRegion, onServers, onServer, onMember, onMembers) and optionally, a Filter set. Using Spring Data GemFire, all a developer need do is define an interface supported by annotations. Spring will create a dynamic proxy for the interface, which will use the FunctionService to create an Execution, invoke the Execution and coerce the results to the defined return type, if necessary. This technique is very similar to the way Spring Data GemFire’s Repository extension works, thus some of the configuration and concepts should be familiar. Generally, a single interface definition maps to multiple Function executions, one corresponding to each method defined in the interface.

Using the Function execution annotated interface defined in the previous section, simply auto-wire your interface into an application bean that will invoke the Function:

Alternately, you can use a Function execution template directly. For example, GemfireOnRegionFunctionTemplate creates an onRegion Function Execution.

Internally, Function Executions always return a List. executeAndExtract assumes a singleton List containing the result and will attempt to coerce that value into the requested type. There is also an execute method that returns the List as is. The first parameter is the Function ID. The Filter argument is optional. The following arguments are a variable argument List.

When using Spring Data GemFire’s Function annotation support combined with Pivotal GemFire’s PDX Serialization, there are a few logistical things to keep in mind.

As explained above, and by way of example, typically developers will define GemFire Functions using POJO classes annotated with Spring Data GemFire Function annotations like so…​

Your Order and OrderSource enum might be as follows…​

Of course, a developer may define a Function Execution interface to call the 'process' GemFire Server Function…​

Clearly, this process(..) Order Function is being called from a client-side with a ClientCache (i.e. <gfe:client-cache/>) based application. This implies that the Function arguments must also be serializable. The same is true when invoking peer-to-peer member Functions (e.g. @OnMember(s)) between peers in the cluster. Any form of `distribution requires the data transmitted between client and server, or peers, to be serialized.

Now, if the developer has configured GemFire to use PDX for serialization (instead of Java serialization, for instance) it is common for developers to also set the pdx-read-serialized attribute to true in their configuration of the GemFire server(s)…​

Or from a GemFire cache client application…​

This causes all values read from the cache (i.e. Regions) as well as information passed between client and servers, or peers, to remain in serialized form, including, but not limited to, Function arguments.

GemFire will only serialize application domain object types that you have specifically configured (registered), with either GemFire’s ReflectionBasedAutoSerializer, or specifically (and recommended) using a "custom" GemFire PdxSerializer. If you are using Spring Data GemFire’s Repository extension to Spring Data Common’s Repository abstraction and infrastructure, you might even want to consider using Spring Data GemFire’s MappingPdxSerializer, which uses a entity’s mapping meta-data to determine data from the application domain object that will be serialized to the PDX instance.

What is less than apparent, though, is that GemFire automatically handles Java Enum types regardless of whether they are explicitly configured or not (i.e. registered with a ReflectionBasedAutoSerializer using a regex pattern and the classes parameter, or are handled by a "custom" GemFire PdxSerializer), despite the fact that Java Enums implement java.io.Serializable.

So, when a developer sets pdx-read-serialized to true on GemFire Servers where the GemFire Functions (including Spring Data GemFire Function annotated POJO classes) are registered, then the developer may encounter surprising behavior when invoking the Function Execution.

What the developer may pass as arguments when invoking the Function is…​

But, what the GemFire Function on the Server gets is…​

The Order and OrderSource have been passed to the Function as PDX instances. Again, this is all because pdx-read-serialized is set to true, which may be necessary in cases where the GemFire Servers are interacting with multiple different clients (e.g. Java, native clients, such as C++/C#, etc).

This flies in the face of Spring Data GemFire’s "strongly-typed", Function annotated POJO class method signatures, as the developer is expecting application domain object types, not PDX serialized instances.

So, Spring Data GemFire includes enhanced Function support to automatically convert method arguments passed to the Function that are of type PDX to the desired application domain object types defined by the Function method’s parameter types.

However, this also requires the developer to explicitly register a GemFire PdxSerializer on the GemFire Servers where Spring Data GemFire Function annotated POJOs are registered and used, e.g. …​

Alternatively, a developer my use GemFire’s ReflectionBasedAutoSerializer for convenience. Of course, it is recommended that you use a "custom" PdxSerializer where possible to maintain finer grained control over your serialization strategy.

Finally, Spring Data GemFire is careful not to convert your Function arguments if you treat your Function arguments generically, or as one of GemFire’s PDX types…​

Spring Data GemFire only converts PDX type data to the corresponding application domain types if and only if the corresponding application domain types are on the classpath the the Function annotated POJO method expects it.

For a good example of "custom", "composed" application-specific GemFire PdxSerializers as well as appropriate POJO Function parameter type handling based on the method signatures, see Spring Data GemFire’s ClientCacheFunctionExecutionWithPdxIntegrationTest class.

Spring Data GemFire provides 2 primary templates for Lucene data access operations, depending on how low a level your application is prepared to deal with.

The LuceneOperations interface defines query operations using Pivotal GemFire Lucene types.

The operations in the LuceneOperations interface match the operations provided by the Pivotal GemFire’s LuceneQuery interface. However, SDG has the added value of translating proprietary GemFire or Lucene Exceptions into Spring’s highly consistent and expressive DAO Exception Hierarchy, particularly as many modern data access operations involve more than single store or repository.

Additionally, SDG’s LuceneOperations interface can shield your application from interface breaking changes introduced by the underlying Pivotal GemFire or Apache Lucene APIs when they do and will occur.

However, it would be remorse to only offer a Lucene Data Access Object that only uses Pivotal GemFire and Apache Lucene data types (e.g. GemFire’s LuceneResultStruct), therefore SDG gives you the ProjectingLuceneOperations interface to remedy these important application concerns.

The ProjectingLuceneOperations interface primarily uses application domain object types to work with your application data. The query method variants accept a projection type and the template applies the query results to instances of the given projection type using the Spring Data Commons Projection infrastructure.

Additionally, the template wraps the paged Lucene query results in an instance of the Spring Data Commons abstraction representing a Page. The same projection logic can still be applied to the results in the page and are lazily projected as each page in the collection is accessed.

By way of example, suppose I have a class representing a Person like so…​

Additionally, I might have a single interface to represent people as Customers depending on my application view…​

If I define the following LuceneIndex…​

Then it is a simple matter to query for people as either Person objects…​

Or as a Page of type Customer…​

The Page can then be used to fetch individual pages of results…​

Conveniently, the Spring Data Commons Page interface implements java.lang.Iterable<T> too making it very easy to iterate over the content as well.

The only restriction to the Spring Data Commons Projection infrastructure is that the projection type must be an interface. However, it is possible to extend the provided, out-of-the-box (OOTB) SDC Projection infrastructure and provide a custom ProjectionFactory that uses CGLIB to generate proxy classes as the projected entity.

A custom ProjectionFactory can be set on a Lucene template using setProjectionFactory(:ProjectionFactory).

Finally, Spring Data GemFire provides Annotation configuration support for LuceneIndexes. Eventually, the SDG Lucene support will find its way into the Repository infrastructure extension for Pivotal GemFire so that Lucene queries can be expressed as methods on an application Repository interface, much like the OQL support today.

However, in the meantime, if you want to conveniently express LuceneIndexes, you can do so directly on your application domain objects like so…​

You must be using the SDG Annotation configuration support along with the @EnableEntityDefineRegions and @EnableIndexing Annotations to enable this feature…​

Given our definition of the Person class above, the SDG Annotation configuration support will find the Person entity class definition, determine that people will be stored in a PARTITION Region called "People" and that the Person will have an OQL Index on birthDate along with a LuceneIndex on lastName.

More will be described with this feature in subsequent releases.

Normally, a Spring-based application will bootstrap Pivotal GemFire using Spring Data GemFire’s. Just by specifying a <gfe:cache/> element using the _Spring Data GemFire XML namespace, a single, embedded GemFire peer Cache instance is created and initialized with default settings in the same JVM process as your application.

However, it is sometimes necessary, perhaps a requirement imposed by your IT organization, that GemFire be fully managed and operated using the provided Pivotal GemFire tool suite, such as with Gfsh. By using Gfsh, GemFire will bootstrap your Spring application context rather than the other way around. Instead of an application server, or a Java main class using Spring Boot, whatever, GemFire does the bootstrapping and will host your application.

Keep in mind, however, that GemFire is not an application server. In addition, there are limitations to using this approach where GemFire cache configuration is concerned.

In order to bootstrap a Spring application context in GemFire when starting a GemFire Server process using Gfsh, a user must make use of GemFire’s Initalizer functionality. An Initializer block can declare a callback application that is launched after the cache is initialized by GemFire.

An Initializer is declared within an initializer element using a minimal snippet of GemFire’s native cache.xml. The cache.xml file is required in order to bootstrap the Spring application context, much like a minimal snippet of Spring XML config is needed to bootstrap a Spring application context configured with component scanning (e.g. <context:component-scan base-packages="…​"/>)

Fortunately, such an Initializer is already conveniently provided by the framework, the SpringContextBootstrappingInitializer. A typical, yet very minimal configuration for this class inside GemFires’s cache.xml file will look like this:

The SpringContextBootstrappingInitializer class follows similar conventions as Spring’s ContextLoaderListener class used to bootstrap a Spring application context inside a Web Application, where application context configuration files are specified with the contextConfigLocations Servlet Context Parameter.

In addition, the SpringContextBootstrappingInitializer class can also be used with a basePackages parameter to specify a comma-separated list of base packages containing appropriately annotated application components that the Spring container will search in order to find and create Spring beans and other application components on the classpath:

Then, with a properly configured and constructed CLASSPATH along with cache.xml file shown above, specified as a command-line option when starting a GemFire Server in Gfsh, the command-line would be:

The application-context.xml can be any valid Spring context configuration meta-data including all the SDG namespace elements. The only limitation with this approach is that a GemFire cache cannot be configured using the Spring Data GemFire namespace. In other words, none of the <gfe:cache/> element attributes, such as cache-xml-location, properties-ref, critical-heap-percentage, pdx-serializer-ref, lock-lease, etc, can be specified. If used, these attributes will be ignored.

The reason for this is that GemFire itself has already created an initialized the cache before the Initializer gets invoked. As such, the cache will already exist and since it is a "Singleton", it cannot be re-initialized or have any of it’s configuration augmented.

Spring Data GemFire already provides existing support for wiring GemFire components, such as CacheListeners, CacheLoaders, CacheWriters and so on, that are declared and created by GemFire in cache.xml using SDG’s WiringDeclarableSupport class as described in Configuration using auto-wiring and annotations. However, this only works when Spring is the one doing the bootstrapping (i.e. bootstrapping GemFire).

When your Spring application context is bootstrapped by GemFire, then these GemFire application components go unnoticed since the Spring application context does not even exist yet! The Spring application context will not get created until GemFire calls the Initializer block, which only occurs after all the other GemFire components and configuration have already been created and initialized.

So, in order to solve this problem, a new LazyWiringDeclarableSupport class was introduced that is, in a sense, Spring application context aware. The intention of this abstract base class is that any implementing class will register itself to be configured by the Spring container that will eventually be created by GemFire once the Initializer is called. In essence, this give your GemFire defined application components a chance to be configured and auto-wired with Spring beans defined in the Spring application context.

In order for your GemFire application components to be auto-wired by the Spring container, create an application class that extends the LazyWiringDeclarableSupport and annotate any class member that needs to be provided as a Spring bean dependency, similar to:

As implied in the CacheLoader example above, you might necessarily (although, rarely) have defined both a Region and CacheListener component in GemFire cache.xml. The CacheLoader may need access to an application DAO, or perhaps a Spring application context defined JDBC DataSource for loading Users into a GemFire REPLICATE Region on start.

The Hello World sample application demonstrates the core functionality of the Spring Data GemFire project. It bootstraps GemFire, configures it, executes arbitrary commands against the cache and shuts it down when the application exits. Multiple instances of the application can be started at the same time and they will work together, sharing data without any user intervention.

The <repositories /> element triggers the setup of the Spring Data repository infrastructure. The most important attribute is base-package which defines the package to scan for Spring Data repository interfaces.^[1]

The <populator /> element allows to populate the a data store via the Spring Data repository infrastructure.^[2]

The following table lists the keywords generally supported by the Spring Data repository query derivation mechanism. However, consult the store-specific documentation for the exact list of supported keywords, because some listed here might not be supported in a particular store.

The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return types, because some listed here might not be supported in a particular store.