Spring Data Geode’s XML namespace supports full configuration of the Apache Geode In-Memory Data Grid (IMDG). The XML namespace is the preferred way to configure Apache Geode in a Spring context in order to properly manage Geode’s lifecycle inside the Spring container. While support for Geode’s native cache.xml persists for legacy reasons, Geode 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 Geode makes extensive use of Spring’s FactoryBean pattern to simplify the creation, configuration and initialization of Geode components.

Apache Geode 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 Geode components. This is a significant improvement over native cache.xml, which provides relatively limited configuration options and requires callbacks to implement Geode’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 Geode provides a dedicated XML namespace for configuring core Apache Geode 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 Geode XML namespace, simply declare it in your Spring XML configuration meta-data:

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

To use Apache Geode, a developer needs to either create a new Cache or connect to an existing one. With the current version of Geode, 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 Geode 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 Geode 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 Geode Cache can be fully configured using Spring, however, Geode’s native XML configuration file, cache.xml, is also supported. For situations where the Geode cache needs to be configured natively, simply provide a reference to the Geode 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 Geode 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.

Geode 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 Apache Geode’s documentation on Region Types.

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

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

In Spring Data Geode’s XML schema (a.k.a. SDG namespace), Index bean declarations are not bound to a Region, unlike Geode’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 Geode’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 Geode specific; this is a feature of Apache Geode.

The Index type maybe 1 of 3 enumerated values defined by Spring Data Geode’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 Geode XML schema for a full set of options.

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

Spring Data Geode 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 Geode components may share the same DiskStore. Additionally, multiple file system directories may be defined for a single DiskStore.

Please refer to Apache Geode’s documentation for a complete explanation of the configuration options.

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

As the Apache Geode 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 Geode’s Snapshot Service support with Spring’s bean definition profiles to load snapshot data specific to the environment as necessary.

Spring Data Geode’s support for Apache Geode’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 Geode application, JVM process’s working directory.

This is a pretty simple example and the Snapshot Service defined in this case refers to the Geode 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 Geode Region by specifying the region-ref attribute:

When the region-ref attribute is specified, Spring Data Geode’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 Geode provides annotation support for implementing and registering Apache Geode Functions.

Spring Data Geode also provides namespace support for registering Apache Geode Functions for remote Function execution.

Please refer to Apache Geode' documentation for more information on the Function execution framework.

Geode 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 Apache Geode Distributed Systems across geographic areas. Spring Data Geode provides namespace support for configuring WAN Gateways as illustrated in the following examples.

Apache Geode can be very difficult to setup and use correctly given all the configuration properties, configuration options (Java API cache.xml, Gfsh with Cluster Configuration, Spring XML/Java-based configuration) in addition to 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 Geode’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 Apache Geode with the Spring Container for more details.

Like Spring Boot, Spring Data Geode’s Annotation-based configuration model was designed as an opinionated, convention over configuration approach for using Apache Geode. Indeed, this 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 configuration attributes out-of-the-box. The default value for a given Annotation attribute directly corresponds to the default value provided in Apache Geode for the same configuration property or setting.

The intention is to let an application developer enable an Apache Geode feature or an embedded service by simply declaring the Annotation on his/her Spring @Configuration or @SpringBootApplication 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 Apache Geode is there should an application developer need it and Spring Data Geode’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 Apache Geode 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 Apache Geode cache application simply by declaring 1 of 3 main Annotations:

These 3 Annotations are the Spring/Apache Geode 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 Apache Geode: a client or a peer.

A Spring Boot application can be configured as an Apache Geode cache client (i.e. with an instance of ClientCache), which communicates with an existing, standalone cluster of Apache Geode servers used to manage the application’s data. The client/server topology is the most typical system architecture employed when using Apache Geode 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 Apache Geode cluster. That is, the application itself is just another server in the cluster of servers that will manage data. The Spring Boot 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 serving cache clients, allowing clients to connect and perform data access operations on the server. This is accomplished by annotating the application class with @CacheServerApplication instead 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, Apache Geode 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 Apache Geode, then I would start with…​

Alternatively, a user may use the @CacheServerApplication annotation instead of @PeerCacheApplication to 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 an Apache Geode cluster. The most common and recommended approach is to use Apache Geode Locators.

Since Apache Geode sets up a "DEFAULT" Pool connected to a CacheServer running on "localhost", listening on port 40404 by default when a ClientCache instance is created, and a CacheServer listens on port 40404 accepting connections on all system NICs, there is nothing special a user needs to 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 ready to go.

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 Geode approach, with Annotations.

As an application developer, you will no doubt want to customize the "DEFAULT" Pool setup by Apache Geode 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, if necessary.

A user may also configure additional Pools, other than the "DEFAULT" Pool provided by Apache Geode 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 Apache Geode.

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 the configuration 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 and/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 to be Strings thereby giving up Type-Safety; not acceptable!

So, Spring Data Geode 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.

The Configurers design pattern are a way to allow application developers to receive a callback to customize the configuration of a component, or bean 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 Geode provides several Configurer callback interfaces to customize different aspects of Annotation-based configuration meta-data at runtime, before the Spring 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 Spring Boot 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 at runtime, during startup.

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 using the @Value annotation on factory method parameters, and so on.

All Spring Data Geode-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 create and configure the Geode component (e.g. a ClientCache instance is created and configured with SDG’s ClientCacheFactoryBean).

Given a Configurer can be declared as a regular bean definition like any other POJO, it is not difficult to imagine a user combining different Spring configuration options, such as the use of Spring Profiles with Conditions using both Property Placeholders and SpEL expressions as well as other nifty 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 a Spring Boot application.properties file.

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 Annotation-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.

Apache Geode 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 Apache Geode 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.

Additionally, you can specify the log-level using the spring.data.gemfire.logging.level property in application.properties.

See the @EnableLogging annotation Javadoc for more details.

To gain even deeper insight into Apache Geode at 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 where timing is a crucial factor.

When Statistics are enabled, a user can use Apache Geode’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 Apache Geode’s Statistics can be found here.

One of the more powerful features of Apache Geode is PDX Serialization. While a complete discussion on PDX is 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 Apache Geode 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.

Enabling PDX serialization is much simpler than modifying all of your application domain object types to be java.io.Serializable, which maybe undesirable to impose such restrictions on your application domain model.

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 a non-invasive implementation of the org.apache.geode.pdx.PdxSerializer interface to handle all the application domain object types that need to be serialized.

Unfortunately, Apache Geode 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 unmaintainable practice to be sure.

Even though only a single PdxSerializer instance can be registered with Apache Geode, it makes sense to create a single 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 all of the 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 Geode will take care of registering it with Apache Geode on the user’s behalf.

It is also possible to declare Apache Geode’s org.apache.geode.pdx.ReflectionBasedAutoSerializer as a bean definition in a Spring context. Alternatively, you should use Spring Data Geode’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 or properties (e.g. keystores, usernames/passwords, etc)…​

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

It is easy to specify which Apache Geode 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 Apache Geode 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 Geode 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 Geode Properties as Java System properties on the command-line when launching your application.

A few examples of some of the less common Geode 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 Geode Property, simply annotate your application class with @EnableGemFireProperties and set the Geode Properties you want to change from the default, out-of-the-box value set by Apache Geode…​

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

More details on Apache Geode properties can be found here.

So far, outside of PDX, our discussion has centered around configuring Apache Geode’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.

Apache Geode 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 and writing queries. We will talk about Indexing later.

Previously, Spring Data Geode 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 all that difficult 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 hundreds or even thousands of tables.

Ugh!

Now users can define and configure Regions based on their application domain objects (i.e. entities). No longer will 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 Geode combines the use of Spring Data 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, an 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 Geode provides an implementation of the applications Repository 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 Geode 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 Geode 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 declared.

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 Apache Geode 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, Apache Geode 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 occur. The data that a client application may be interested in is expressed as an 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 Geode makes defining and registering CQs along with an associated listener to handle and process CQ events without all the cruft of Apache Geode’s plumbing, a non-event (no pun intended). SDG’s new Annotation-based configuration for CQs builds on the 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 POJO 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 Geode’s Continuous Query support can be found here.

More details on Apache Geode’s Continuous Queries can be found here.

With Spring Data Geode, Apache Geode 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 Geode, a Spring Cache corresponds directly to a Region. The Region must exist before any @Cacheable application service methods are 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 Geode and Apache Geode 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 Geode’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 application, caching annotated service components to identify all the caches that will be needed by the application at runtime and creates Regions in Apache Geode 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 Apache Geode 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 Geode.

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 Apache Geode will remember the configuration pushed by the client, when using HTTP. 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, manually. Except now, with Spring Data Geode, 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 Geode, already contains all the configuration meta-data needed 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 needed by the application’s service components. 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 point is, users can focus on their application business logic along with using the framework provided services and supporting infrastructure (e.g. Spring Data Repositories, Spring’s Transaction Management, Spring Caching, and so on) and Spring Data Geode will take care of all the Apache Geode 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 Apache Geode’s Cluster Configuration service. Apache Geode’s Cluster Configuration service is also the same service used by Gfsh to record schema-related changes (e.g. gfsh> create region --name=Example --type=PARTITION) 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 Geode 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 instance.

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

An application developer instantly gets a Spring Boot, Apache Geode ClientCache application using Spring Data Repositories with Spring’s Cache Abstraction, using Apache Geode 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 simple queryies for each of the entity types, define the service components containing the business logic transacting 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. Apache Geode). Database users have similar features. Now Spring, Apache Geode developers can too!

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

Then, this application is really going to start to take flight, with very minimal effort.

See the @EnableClusterConfiguration annotation Javadoc for more details.

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

Recently, Apache Geode 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 Geode can simplify Apache Geode’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 Apache Geode and/or Spring Data Geode 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 Apache Geode, 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 Geode'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 Apache Geode 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 Geode 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 Apache Geode 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.GatewayReceiverFactoryBean and org.springframework.data.gemfire.wan.GatewaySenderFactoryBean API classes in Java configuration of 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.

We hope you will enjoy these new capabilities!

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

The template class requires a Geode 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 Geode Region without having to deal with checked exceptions, threading or resource management concerns:

For accessing the full power of the Apache Geode 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 Geode 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 Apache Geode, Spring Data Geode provides a dedicated, per-cache, PlatformTransactionManager that, once declared, allows Region operations to be executed atomically through Spring:

Currently, Apache Geode 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 Apache Geode 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), Apache Geode is not an XA compliant resource. Therefore, Apache Geode 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 Apache Geode 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 Apache Geode 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. Apache Geode) in such an arrangement.

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

2) Referring to Step 5 in Geode’s documentation, Spring Data Geode’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 Geode’s documentation and let Spring Data Geode work its magic. All you need do is annotate your Spring @Configuration class with Spring Data Geode’s new @EnableGemFireAsLastResource annotation and a combination of Spring’s Transaction Management infrastructure and Spring Data Geode’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 Geode’s @EnableGemFireAsLastResource annotation imports configuration containing 2 Aspect bean definitions that handles the Geode 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 + Geode API yourself, as shown in the Geode 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 Geode’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 Apache Geode in JTA transactions, see here.

For more details on configuring Apache Geode as a "Last Resource", see here.

A powerful functionality offered by Apache Geode 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 Geode matches the query predicate. Spring Data Geode 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 Geode 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 Geode 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 Apache Geode.

Apache Geode 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 Geode. Using native Geode 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 Geode 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 Geode offers a base class (WiringDeclarableSupport) that allows Geode 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 Geode provides an implementation of the Spring Cache Abstraction to position Apache Geode as a caching provider in Spring’s caching infrastructure.

To use Apache Geode 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 Geode 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 Geode offers a special Instantiator that performs wiring for each new instance created by Geode 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 Geode serialization system and perform wiring on all instances of SomeDataSerializableClass created by Geode 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, Geode 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 Geode 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 Geode, under user id 1025 and 1026. The two Instantiators avoid the use of reflection and create the instances directly through Java code.

Spring Data Geode provides support to map entities that will be stored in a Region in the Geode 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 Geode Region, as defined with the Spring Data Geode XML namespace using the id or name attributes of the <*-region> element.

Spring Data Geode 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 Geode provides support to use the Spring Data Repository abstraction to easily persist entities into Geode 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 Geode 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 Apache Geode is when performing Joins. Joins are not supported by SDG Repositories OOTB. With an Apache Geode PARTITION Region, the Join must be performed on collocated PARTITION Regions even, since Apache Geode does not support "distributed" Joins. In addition, the Equi-Join OQL Query must be performed inside a Geode Function. See here for more details on Apache Geode 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 Geode Repositories enable the definition of query methods to easily execute Geode 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 Apache Geode’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 Geode’s OQL Query language extensions and preserve portability across different data stores, Spring Data Geode 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 Geode’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 Geode OQL Query language extensions that are supported by Spring Data Geode include:

As an example, suppose you have a Customers application domain class and corresponding Geode 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 Geode’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.

Using the Spring Data Repository abstraction, query method convention for defining data store specific queries (e.g. OQL) is easy and convenient. However, it is sometimes desirable to still want to inspect or even possibly modify the query "generated" from the Repository query method.

Since 2.0.x, Spring Data Geode introduces the o.s.d.gemfire.repository.query.QueryPostProcessor functional interface. The interface is loosely defined as follows…​

There are additional default methods provided to allow users to compose instances of QueryPostProcessor very similar to how java.util.function.Function.andThen(:Function) and java.util.function.Function.compose(:Function) work.

Additionally, you will notice that the QueryPostProcessor interface implements the org.springframework.core.Ordered interface, which is useful when multiple QueryPostProcessors are declared and registered in the Spring context and used to create a pipeline of processing for a group of generated query method queries.

Finally, the QueryPostProcessor accepts type arguments corresponding to the type parameters, T and QUERY, respectively. Type of T extends the Spring Data Commons marker interface, org.springframework.data.repository.Repository. We will discuss this further below. All QUERY type parameter arguments in Spring Data Geode’s case will be of type java.lang.String.

As user may implement this interface to receive a callback with the query that was generated from the application Repository interface method when the method is called.

For example, I might want to log all queries from all application Repository interface definitions. I could do so using the following QueryPostProcessor implementation…​

The LoggingQueryPostProcessor was typed to the Spring Data org.springframework.data.repository.Repository marker interface, and therefore, will log all application Repository interface query method "generated" queries.

You could limit the scope of this logging to queries only from certain types of application Repository interfaces, such as, say, an CustomerRepository…​

Then, I could have typed the LoggingQueryPostProcessor specifically to the CustomerRepository, like so…​

As result, only queries defined in the CustomerRepository interface (e.g. findByAccountNumber) would be logged.

I might want to create a QueryPostProcessor for a specific query defined by a Repository query method. For example, say I want to “LIMIT” the OQL query generated from the CustomerRepository.findByLastNameLike(:String) query method to only return 5 results and I want to order the Customers by firstName, ascending. Well, then, I can define a custom QueryPostProcessor like so…​

While this works, it possible to achieve the same affect just using the Spring Data Repository convention and extensions provided by Spring Data Geode. For instance, the same query could be defined as…​

However, if you do not have control over the application CustomerRepository interface definition, then the QueryPostProcessor (i.e. OrderedLimitedCustomerByLastNameQueryPostProcessor) is convenient.

If I want to ensure the LoggingQueryPostProcessor always comes after the other application-defined QueryPostProcessors that I may have declared and registered in the Spring ApplicationContext, then I can set the order property by overriding the o.s.core.Ordered.getOrder() method.

This ensures that I will always see the affects of the post processing applied by my other QueryPostProcessors before my LoggingQueryPostProcessor logs the query.

You can define as many QueryPostProcessors in the Spring ApplicationContext as you like and apply them in any order, to all or specific application Repository interfaces, and be a granular as yuo like using the provided arguments to the postProcess(..) method callback.

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

Functions can execute in parallel, distributed among multiple Geode 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 Apache Geode 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 Geode, 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 Geode introduces annotations to declaratively register public methods of a POJO class as Geode 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 Geode 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 Geode, 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 Geode’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 Geode’s Function annotation support combined with Apache Geode’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 Geode Functions using POJO classes annotated with Spring Data Geode 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' Geode 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 Geode 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 Geode server(s)…​

Or from a Geode 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.

Geode will only serialize application domain object types that you have specifically configured (registered), with either Geode’s ReflectionBasedAutoSerializer, or specifically (and recommended) using a "custom" Geode PdxSerializer. If you are using Spring Data Geode’s Repository extension to Spring Data Common’s Repository abstraction and infrastructure, you might even want to consider using Spring Data Geode’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 Geode 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" Geode PdxSerializer), despite the fact that Java Enums implement java.io.Serializable.

So, when a developer sets pdx-read-serialized to true on Geode Servers where the Geode Functions (including Spring Data Geode 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 Geode 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 Geode 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 Geode’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 Geode 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 Geode PdxSerializer on the Geode Servers where Spring Data Geode Function annotated POJOs are registered and used, e.g. …​

Alternatively, a developer my use Geode’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 Geode is careful not to convert your Function arguments if you treat your Function arguments generically, or as one of Geode’s PDX types…​

Spring Data Geode 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 Geode PdxSerializers as well as appropriate POJO Function parameter type handling based on the method signatures, see Spring Data Geode’s ClientCacheFunctionExecutionWithPdxIntegrationTest class.

Spring Data Geode 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 Apache Geode Lucene types.

The operations in the LuceneOperations interface match the operations provided by the Apache Geode’s LuceneQuery interface. However, SDG has the added value of translating proprietary Geode 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 Apache Geode 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 Apache Geode and Apache Lucene data types (e.g. Geode’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 Geode provides Annotation configuration support for LuceneIndexes. Eventually, the SDG Lucene support will find its way into the Repository infrastructure extension for Apache Geode 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 Apache Geode using Spring Data Geode’s. Just by specifying a <gfe:cache/> element using the _Spring Data Geode XML namespace, a single, embedded Geode 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 Geode be fully managed and operated using the provided Apache Geode tool suite, such as with Gfsh. By using Gfsh, Geode 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, Geode does the bootstrapping and will host your application.

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

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

An Initializer is declared within an initializer element using a minimal snippet of Geode’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 Geodes’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 Geode 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 Geode 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 Geode 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 Geode already provides existing support for wiring Geode components, such as CacheListeners, CacheLoaders, CacheWriters and so on, that are declared and created by Geode 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 Geode).

When your Spring application context is bootstrapped by Geode, then these Geode application components go unnoticed since the Spring application context does not even exist yet! The Spring application context will not get created until Geode calls the Initializer block, which only occurs after all the other Geode 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 Geode once the Initializer is called. In essence, this give your Geode defined application components a chance to be configured and auto-wired with Spring beans defined in the Spring application context.

In order for your Geode 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 Geode 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 Geode REPLICATE Region on start.

The Hello World sample application demonstrates the core functionality of the Spring Data Geode project. It bootstraps Geode, 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.