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

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

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

To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components. It is also possible to configure beans directly using Spring’s standard <bean> definition. However, as of Spring Data GemFire 1.2.0, 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 this appendix in the Spring Framework reference documentation.

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

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

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

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

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

Starting with Spring Data GemFire v1.2.0, a GemFire Cache can be fully configured using Spring. However, GemFire’s native XML configuration file, cache.xml, is also supported. For situations in which the GemFire cache needs to be configured natively, simply provide a reference to the GemFire XML configuration file using the cache-xml-location attribute:

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

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

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

The latter approach is recommended for externalizing environment specific settings outside the application configuration.

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

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

GemFire implements the following types of regions:

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

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

Before creating an Index, Spring Data GemFire will verify whether an Index with the same name already exists. If an Index with the same name does exist, by default, SDG will "override" the existing Index by removing the old Index first followed by creating a new Index with the same name based on the new definition, regardless if the old definition was the same or not. To prevent the named Index definition change, especially when the old and new Index definitions may not match, set the override property to false, which effectively returns the existing Index definition by name.

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

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

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

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

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

Spring Data GemFire’s support for GemFire’s Snapshot Service begins with the <gfe-data:snapshot-service> element from the GFE Data Access Namespace. For example, I might define Cache-wide snapshots to be loaded as well as saved with a couple snapshot imports and a single data export definition as follows:

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

This is a pretty simple example and the snapshot service defined in this case refers to the GemFire Cache, having a default name of gemfireCache (as described in Configuring a GemFire Cache). If you name your cache bean definition something different, 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 GemFire Region by specifying the region-ref attribute:

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

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

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

Using a new data access technology requires not only accommodating a new API but also handling exceptions specific to that technology. To accommodate this case, Spring Framework provides a technology agnostic, consistent exception hierarchy that abstracts the application from proprietary (and usually checked) exceptions to a set of focused runtime exceptions. As mentioned in the Spring Framework documentation, exception translation can be applied transparently to your data access objects through the use of the @Repository annotation and AOP by defining a PersistenceExceptionTranslationPostProcessor bean. The same exception translation functionality is enabled when using GemFire as long as at least a CacheFactoryBean is declared, e.g. using a <gfe:cache/> declaration, as it acts as an exception translator which is automatically detected by the Spring infrastructure and used accordingly.

As with many other high-level abstractions provided by the Spring projects, Spring Data GemFire provides a template that simplifies GemFire data access. The class provides several one-line methods, for common region operations but also the ability to execute code against the native GemFire API without having to deal with GemFire checked exceptions for example through the GemfireCallback.

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

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

For accessing the full power of the GemFire query language, one can use the find and findUnique 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.

Since 1.1, Spring Data GemFire provides an implementation of the Spring 3.1 cache abstraction. To use GemFire as a backing implementation, simply add GemfireCacheManager to your configuration:

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 GemFire, Spring Data GemFire provides a dedicated, per-cache, transaction manager that, once declared, allows Region operations to be executed atomically through Spring:

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

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

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

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

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

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

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

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

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

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

Peer Cache XML:

Peer Cache JavaConfig:

Client Cache XML:

Client Cache JavaConfig:

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

The configuration looks like this…​

The only requirements are…​

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

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

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

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

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

Specifically, the correct sequence of events are…​

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

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

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

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

#3 of course is the responsibility of your application.

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

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

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

A powerful functionality offered by GemFire is continuous querying (or CQ). In short, CQ allows one to create a query and automatically be notified when new data that gets added to GemFire matches the query. Spring GemFire provides dedicated support for CQs through the org.springframework.data.gemfire.listener package and its listener container; very similar in functionality and naming to the JMS integration in Spring Framework; in fact, users familiar with the JMS support in Spring, should feel right at home. Basically Spring Data GemFire allows methods on POJOs to become end-points for CQ - simply define the query and indicate the method that should be notified when there is a match - Spring Data GemFire takes care of the rest. This is similar Java EE’s message-driven bean style, but without any requirement for base class or interface implementations, based on GemFire.

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

In this section we describe how you can configure these pluggable components 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 collaboration objects.

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

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

To simplify the task of parsing, converting the parameters and initializing the object, Spring Data GemFire offers a base class (WiringDeclarableSupport) that allows GemFire user objects to be wired through a template bean definition or, in case that is missing, perform autowiring through the Spring 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.

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

Through such a mechanism, one can rely on the Spring container to inject (and manage) certain dependencies making it easy to split transient from persistent data and have rich domain objects in a transparent manner (Spring users might find this approach similar to that of @Configurable). The WiringInstantiator works just like WiringDeclarableSupport, trying to first locate a bean definition as a wiring template and following to autowiring otherwise. Please refer to the previous section (Wiring Declarable components) for more details on wiring functionality.

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

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

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

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

Spring Data GemFire provides support to map entities that will be stored in a GemFire data grid. The mapping metadata is defined using annotations at the domain classes just like this:

The first thing you see here is the @Region annotation that can be used to customize the Region in which the Person class is stored in. The @Id annotation can be used to annotate the property that shall be used as the Cache key. The @PersistenceConstructor annotation actually helps disambiguating multiple potentially available constructors taking parameters and explicitly marking the one annotated as the one to be used to create entities. With none or only a single constructor you can omit the annotation.

In addition to storing entities in top-level Regions, entities can be stored in GemFire Sub-Regions, as so:

Be sure to use the full-path of the GemFire Region, as defined in Spring Data GemFire XML namespace configuration meta-data, as specified in the id or name attributes of the <*-region> bean definition.

As alternative to specifying the Region in which the entity will be stored using the @Region annotation on the entity class, you can also specify the @Region annotation on the entity’s Repository abstraction. See GemFire Repositories for more details.

However, let’s say you want to store a Person in multiple GemFire Regions (e.g. People and Customers), then you can define your corresponding Repository interface abstractions like so:

Spring Data GemFire provides a custom PDXSerializer implementation that uses the mapping information to customize entity serialization. Beyond that it allows customizing the entity instantiation by using the Spring Data EntityInstantiator abstraction. By default the serializer uses a ReflectionEntityInstantiator that will use the persistence constructor of the mapped entity (either the single declared one or explicitly annoted with @PersistenceConstructor). To provide values for constructor parameters it will read fields with name of the constructor parameters from the PDXReader supplied.

The entity annotated as such will get the field foo read from the PDXReader and handed as constructor parameter value for firstname. The value for lastname will be the Spring bean with name bean.

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

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

This configuration snippet will look for interfaces below the configured base package and create Repository instances for those interfaces backed by a SimpleGemFireRepository. Note that you have to have your domain classes correctly mapped to configured Regions or the bootstrap process will fail otherwise.

The GemFire Repositories allow the definition of query methods to easily execute OQL Queries against the Region the managed entity is mapped to.

The first method listed here will cause the following query to be derived: SELECT x FROM /MyRegion x WHERE x.emailAddress = $1. The second method works the same way except it’s returning all entities found whereas the first one expects a single result value. In case the supported keywords are not sufficient to declare your query or the method name gets to verbose you can annotate the query methods with @Query as seen for methods 3 and 4.

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

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

To support GemFire’s OQL Query language extensions and maintain portability across data stores, Spring Data GemFire adds support for OQL Query extensions by way of Java Annotations. These new Annotations will be ignored by other Spring Data Repository implementations (e.g. Spring Data Redis) that don’t have similar query language extensions.

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

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

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

This will result in the following OQL Query:

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

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

For instance, 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 c WHERE c.reputation > $1 ORDER BY c.reputation DESC LIMIT 5

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

Spring Data GemFire 1.3.0 introduces annotation support to simplify working with GemFire Function Execution. The GemFire API provides classes to implement and register Functions deployed to Cache servers that may be invoked remotely by member applications, typically cache clients. Functions may execute in parallel, distributed among multiple servers, combining results in a map-reduce pattern, or may be targeted at a single server. A Function execution may be also be targeted to a specific Region.

GemFire also provides APIs to support remote execution of Functions targeted to various defined scopes (Region, member groups, servers, etc.) and the ability to aggregate results. The API also provides certain runtime options. The implementation and execution of remote Functions, as with any RPC protocol, requires some boilerplate code. Spring Data GemFire, true to Spring’s core value proposition, aims to hide the mechanics of remote Function execution and allow developers to focus on POJO programming and business logic. To this end, Spring Data GemFire introduces annotations to declaratively register public methods as GemFire Functions, and the ability to invoke registered Functions remotely via annotated interfaces.

There are two separate concerns to address. First is the Function implementation (server) which must interact with the FunctionContext to obtain the invocation arguments, the ResultsSender and other execution context information. The Function implementation typically accesses the Cache and or Region and is typically registered with the FunctionService under a unique Id. The application invoking a Function (the client) does not depend on the implementation. To invoke a Function remotely, the application instantiates an Execution providing the Function ID, invocation arguments, the Function target or scope (Region, server, servers, member, members). If the Function produces a result, the invoker uses a ResultCollector to aggregate and acquire the execution results. In certain scenarios, a custom ResultCollector implementation is required and may be registered with the Execution.

Using GemFire APIs, the FunctionContext provides a runtime invocation context including the client’s calling arguments and a ResultSender interface to send results back to the client. Additionally, if the Function is executed on a Region, the FunctionContext is an instance of RegionFunctionContext which provides additional context such as the target Region and any Filter (set of specific keys) associated with the Execution. 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 enable 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 the client’s execution arguments. However, in the case of a Region execution, the Region data must 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 may 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 that the client and server share a common interface, but this is not 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 by the FunctionContext as an array:

Object[] args = new Object[]{"hello", 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 calling parameters. The method’s return type must be void or a type that may be serialized (either java.io.Serializable, DataSerializable, or PDX serializable). 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 calling arguments, a Function id, the execution target (onRegion, onServers, onServer, onMember, onMembers) and optionally a Filter set. 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 a defined return type, if necessary. This technique is very similar to the way Spring Data Repositories work, 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 annotated interface as described in the previous section, simply wire your interface into a bean that will invoke the Function:

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

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 itself. The first parameter is the Function id. The Filter argument is optional. The following arguments are a variable argument List.

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

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

Your Order and OrderSource enum might be as follows…​

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

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

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

<gfe:cache …​ pdx-read-serialized="true"/>

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, include, but not limited to Function arguments.

GemFire will only serialize application domain object types that you have specifically configured (registered), either using GemFire’s ReflectionBasedAutoSerializer, or specifically (and recommended) using a "custom" GemFire PdxSerializer for your application domain types.

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

So, when a developer has pdx-read-serialized set to true on the GemFire Servers on which the GemFire Functions (including Spring Data GemFire registered, Function annotated POJO classes), 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, in actuality, what GemFire executes the Function on the Server is…​

Notice that the Order and OrderSource have passed to the Function as PDX instances. Again, this is all because read-serialized is set to true on the GemFire Server, which may be necessary in cases where the GemFire Servers are interacting with multiple different client types (e.g. native clients).

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

So, as of Spring Data GemFire (SDG) 1.6, SDG introduces enhanced Function support to automatically convert method arguments that are of type PDX to the desired application domain object types when the developer of the Function expects his Function arguments to be "strongly-typed".

However, this also requires the developer to explicitly register a GemFire PdxSerializer on the GemFire Servers where the SDG annotated POJO Function is registered and used, e.g. …​

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

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

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

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

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

However, sometimes it is a requirement, perhaps imposed by your IT operations team, that GemFire must be fully managed and operated using the provided GemFire tool suite, such as with Gfsh. Using Gfsh, even though the application and GemFire will share the same JVM process, GemFire will bootstrap your Spring application context rather than the other way around. So, using this approach GemFire, instead of an application server, or a Java main class using Spring Boot, will bootstrap and host your application.

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

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

An Initializer is specified within an initializer element using a minimal snippet of GemFire’s native configuration meta-data inside a cache.xml file. 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="…​"/>)

As of Spring Data GemFire 1.4, such an Initializer is already conveniently provided by the framework, the org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer. The typical, yet minimal configuration for this class inside GemFire’s cache.xml file will look like the following:

The SpringContextBootstrappingInitializer class follows similar conventions as Spring’s ContextLoaderListener class for bootstrapping a Spring 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 package containing the appropriately annotated application components that the Spring container will search using component scanning and create Spring beans for:

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

The application-context.xml can be any valid Spring context configuration meta-data including all the SDG namespace elements. The only limitation with this approach is that the GemFire Cache cannot be configured using the Spring Data GemFire namespace. In other words, none of the <gfe:cache/> element attributes, such as cache-xml-location, properties-ref, critical-heap-percentage, pdx-serializer-ref, lock-lease, etc can be specified. If used, these attributes will be ignored. The main reason for this is that GemFire itself has already created an initialized the Cache before the Initializer gets invoked. As such, the Cache will already exist and since it is a "Singleton", it cannot be re-initialized or have any of it’s configuration augmented.

Spring Data GemFire already provides existing support for wiring GemFire components (such as CacheListeners, CacheLoaders or CacheWriters) that are declared and created by GemFire in cache.xml using the WiringDeclarableSupport class as described in Configuration using auto-wiring and annotations. However, this only works when Spring does the bootstrapping (i.e. bootstraps GemFire). When your Spring application context is the one bootstrapped by GemFire, then these GemFire components go unnoticed since the Spring application context does not even exist yet! The Spring application context will not get created until GemFire calls the Initializer, which occurs after all the other GemFire components and configuration have already been created and initialized.

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

In order for your GemFire application component to be auto-wired by the Spring container, create a 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 by the CacheLoader example above, you might necessarily (although, rare) have defined both a Region and CacheListener component in GemFire cache.xml. The CacheLoader may need access to an application DAO, or perhaps Spring application context defined JDBC Data Source for loading "Users" into a GemFire Cache REPLICATE Region on start. Of course, one should be careful in mixing the different life-cycles of GemFire and the Spring Container together in this manner as not all use cases and scenarios are supported. The GemFire cache.xml configuration would be similar to the following (which comes from SDG’s test suite):

The Hello World sample demonstrates the core functionality of the Spring GemFire project. It bootstraps GemFire, configures it, executes arbitrary commands against it and shuts it down when the application exits. Multiple instances can be started at the same time as they will work with each other 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.