diff --git a/pom.xml b/pom.xml index f5bf49ad..62b838f3 100644 --- a/pom.xml +++ b/pom.xml @@ -31,14 +31,14 @@ - - apache-snapshots - https://repository.apache.org/content/repositories/snapshots - spring-libs-snapshot https://repo.spring.io/libs-snapshot + + apache-snapshots + https://repository.apache.org/content/repositories/snapshots + @@ -253,10 +253,34 @@ ${project.basedir}/src/main/asciidoc book + true + true + 2 ${project.version} + + + html + generate-resources + + process-asciidoc + + + html5 + ${project.root}/target/site/reference/html + false + prettify + + true + font + true + spring.css + + + + diff --git a/src/main/asciidoc/appendix/appendix-schema.adoc b/src/main/asciidoc/appendix/appendix-schema.adoc index 76c2f0b0..d6eb30f8 100644 --- a/src/main/asciidoc/appendix/appendix-schema.adoc +++ b/src/main/asciidoc/appendix/appendix-schema.adoc @@ -1,19 +1,18 @@ [[appendix-schema]] [appendix] -= Spring Data GemFire Schema += Spring Data Geode Schema :resourcesDir: {basedocdir}/../resources -== Spring Data GemFire Core Schema (gfe) +== Spring Data Geode Core Schema (gfe) [source,xml] ---- -include::{resourcesDir}/org/springframework/data/gemfire/config/spring-gemfire-1.0.xsd[] +include::{resourcesDir}/org/springframework/data/gemfire/config/spring-geode-2.0.xsd[] ---- -== Spring Data GemFire Data Access Schema (gfe-data) +== Spring Data Geode Data Access Schema (gfe-data) [source,xml] ---- -include::{resourcesDir}/org/springframework/data/gemfire/config/spring-data-gemfire-1.0.xsd[] +include::{resourcesDir}/org/springframework/data/gemfire/config/spring-data-geode-2.0.xsd[] ---- - diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 6c0f97df..86172010 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -1,64 +1,73 @@ -= Spring Data Geode Reference Guide -Costin Leau , David Turanski , John Blum , Oliver Gierke -:baseDir: . += Spring Data for Apache Geode - Reference Guide +Costin Leau; David Turanski; John Blum; Oliver Gierke :revnumber: {version} :revdate: {localdate} -:toc: -:toc-placement!: :spring-data-commons-docs: {basedocdir}/../../../../spring-data-commons/src/main/asciidoc +:toc: +:!toc-placement: (C) 2010-2017 The original authors. -NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not -charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed -in print or electronically. +NOTE: Copies of this document may be made for your own use and for distribution to others provided that you do not +charge any fee for such copies and further provided that each copy contains this Copyright Notice +whether distributed in print or electronically. toc::[] -[[spring-gemfire-reference]] -include::{baseDir}/preface.adoc[] +[[preface]] +include::{basedocdir}/preface.adoc[] + +ifndef::leveloffset[:leveloffset: 0] -:leveloffset: 0 :leveloffset: +1 -include::{baseDir}/introduction/introduction.adoc[] -include::{baseDir}/introduction/requirements.adoc[] -include::{baseDir}/introduction/new-features.adoc[] + +include::{basedocdir}/introduction/introduction.adoc[] +include::{basedocdir}/introduction/requirements.adoc[] +include::{basedocdir}/introduction/new-features.adoc[] + :leveloffset: -1 [[reference]] = Reference Guide :leveloffset: +1 -include::{baseDir}/reference/introduction.adoc[] -include::{baseDir}/reference/bootstrap.adoc[] -include::{baseDir}/reference/data.adoc[] -include::{baseDir}/reference/serialization.adoc[] -include::{baseDir}/reference/mapping.adoc[] -include::{baseDir}/reference/repositories.adoc[] -include::{baseDir}/reference/function-annotations.adoc[] + +include::{basedocdir}/reference/introduction.adoc[] +include::{basedocdir}/reference/bootstrap.adoc[] +include::{basedocdir}/reference/data.adoc[] +include::{basedocdir}/reference/serialization.adoc[] +include::{basedocdir}/reference/mapping.adoc[] +include::{basedocdir}/reference/repositories.adoc[] +include::{basedocdir}/reference/function-annotations.adoc[] include::{basedocdir}/reference/lucene.adoc[] -include::{baseDir}/reference/gemfire-bootstrap.adoc[] -include::{baseDir}/reference/samples.adoc[] +include::{basedocdir}/reference/gemfire-bootstrap.adoc[] +include::{basedocdir}/reference/samples.adoc[] + :leveloffset: -1 [[resources]] -= Other Resources += Resources In addition to this reference documentation, there are a number of other resources that may help you learn -how to use GemFire with the Spring Framework. These additional, third-party resources are enumerated in this section. +how to use Apache Geode with the _Spring Framework_. These additional, third-party resources are enumerated +in this section. :leveloffset: +1 -include::{baseDir}/links.adoc[] + +include::{basedocdir}/links.adoc[] + :leveloffset: -1 [[appendices]] = Appendices -:numbered!: +:!sectnums: :leveloffset: +1 + include::{spring-data-commons-docs}/repository-namespace-reference.adoc[] include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[] include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[] include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[] -include::{baseDir}/appendix/appendix-schema.adoc[] +include::{basedocdir}/appendix/appendix-schema.adoc[] + :leveloffset: -1 diff --git a/src/main/asciidoc/introduction/introduction.adoc b/src/main/asciidoc/introduction/introduction.adoc index 5bf6e1d1..3d317875 100644 --- a/src/main/asciidoc/introduction/introduction.adoc +++ b/src/main/asciidoc/introduction/introduction.adoc @@ -1,9 +1,6 @@ [[introduction]] = Introduction -This reference guide for Spring Data GemFire explains how to use the Spring Framework to configure -and develop applications with Pivotal GemFire. It presents the basic concepts, semantics and provides numerous examples +This reference guide for _Spring Data Geode_ explains how to use the _Spring Framework_ to configure and develop +applications with Apache Geode. It presents the basic concepts, semantics and provides numerous examples to help you get started. - -NOTE: Spring Data GemFire started as a top-level Spring project called Spring GemFire (SGF) and since then -has been moved under the Spring Data umbrella project and renamed accordingly. diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index 94d7226a..815e9ae7 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -1,121 +1,46 @@ [[new-features]] = New Features -NOTE: As of the 1.2.0 release, this project, formerly known as Spring GemFire, has been renamed to Spring Data GemFire -to reflect that it is now a component of the http://projects.spring.io/spring-data/[Spring Data] project. +NOTE: As of version `2.0.0`, _Spring Data Geode_ is now a top-level module in the +http://projects.spring.io/spring-data/[Spring Data] project. -[[new-in-1-2-0]] -== New in the 1.2 Release +[[new-in-1-0-0]] +== New in the 1.0.0.RELEASE -* Full support for GemFire configuration via the SDG *gfe* namespace. Now GemFire components may be configured completely without requiring a native *cache.xml* file. -* WAN Gateway support for GemFire 6.6.x. See <>. -* Spring Data Repository support using a dedicated SDG namespace, *gfe-data*. See <> -* Namespace support for registering GemFire Functions. See <> -* A top-level `` element has been added to the SDG *gfe* namespace to allow sharing of persist stores among Regions, -and other components that support persistent backup or overflow. See <> -+ -WARNING: The `<*-region>` elements no longer allow a nested `` element. -+ -* GemFire Sub-Regions are supported via nested `<*-region>` elements. -* A `` element has been added to configure a Local Region. -* Support for the re-designed WAN Gateway in GemFire 7.0. +* Upgrades to Apache Geode 1.0.0-incubating (GA) release. +* Upgrades to Spring Framework 4.3.4.RELEASE. +* Significant additions to the new Annotation-based configuration model. +* Support for CDI. +* Ability to configure Apache Geode's Off-Heap memory support. +* Fix for premature destruction of client Pools before the Region's configured to use these Pools. +* Support Repositories with multiple SD modules on the classpath. +* Support for `forwardExpirationDestroy` in the `AsyncEventQueueFactoryBean` API and XML namespace. +* Handle case-insensitive OQL queries defined as Repository query methods. +* Enable explicit Cache names referring to Regions to be specified when using GemfireCacheManager. +* Fix for ordered GemfireRepository.findAll(Sort) queries. +* GemfireCache.evict(key) now calls Region.remove(key). +* Fix RegionNotFoundException when executing Repository queries on client Regions configured with a Pool +targeted for a specific server group. +* Geode package namespace changed from com.gemstone.gemfire to org.apache.geode. +* Support for the Geode Integrated Security framework. -[[new-in-1-3-0]] -== New in the 1.3 Release -* Annotation support for GemFire Functions. It is now possible to declare and register Functions written as POJOs using annotations. In addition, Function executions are defined as -annotated interfaces, similar to the way Spring Data Repositories work. See <>. -* Added a `` element to the SDG *gfe-data* namespace to simplify establishing a basic <> to a GemFire data grid. -* Added a `` element to the SDG *gfe-data* namespace to <> features introduced -in GemFire 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations. -* Upgraded to GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes. -* Added support for setting subscription interest policy on Regions. -* Support for void returns on Function executions. See <> for complete details. -* Support for persisting Local Regions. See <> and <>. -* Support for entry time-to-live and entry idle-time on a GemFire Client Cache. See <>. -* Support for multiple Spring Data GemFire web-based applications using a single GemFire cluster, operating concurrently inside tc Server. -* Support for concurrency-checks-enabled on all GemFire Cache Region definitions using the SDG *gfe* namespace. See <>. -* Support for Cache Loaders and Cache Writers on Client, Local Regions. See <>. -* Support for registering CacheListeners, AsyncEventQueues and Gateway Senders on GemFire Cache Sub-Regions. -* Support for PDX persistent keys in GemFire Regions. -* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the *colocated-with* attribute. -* Full support for GemFire Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG *gfe* namespace. -* Upgraded Spring Data GemFire to Spring Framework 3.2.8. -* Upgraded Spring Data GemFire to Spring Data Commons 1.7.1. +[[new-in-1-1-0]] +== New in the 1.1.0.RELEASE -[[new-in-1-4-0]] -== New in the 1.4 Release +* Upgrades to Aapche Geode 1.1.0 (GA) release. +* Upgrades to Spring Framework 4.3.7.RELEASE. +* Upgrades to Spring Data Commons Ingalls-SR1. +* Additional improvements in the new Annotation-based configuration model. +* Support Apache Geode's Apache Lucene Integration. -* Upgrades Spring Data GemFire to GemFire 7.0.2. -* Upgrades Spring Data GemFire to Spring Data Commons 1.8.0. -* Upgrades Spring Data GemFire to Spring Framework 3.2.9. -* Integrates Spring Data GemFire with Spring Boot, which includes both a *spring-boot-starter-data-gemfire* POM -along with a Spring Boot sample application demonstrating GemFire Cache Transactions configured with SDG -and bootstrapped with Spring Boot. -* Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh. -See <> for more details. -* Support for persisting application domain object/entities to multiple GemFire Cache Regions. -See <> for more details. -* Support for persisting application domain object/entities to GemFire Cache Sub-Regions, avoiding collisions -when Sub-Regions are uniquely identifiable, but identically named. -See <> for more details. -* Adds strict XSD type rules to, and full support for, Data Policies and Region Shortcuts on all GemFire -Cache Region types. -* Changed the default behavior of SDG `<*-region>` elements from lookup to always create a new Region -along with an option to restore old behavior using the *ignore-if-exists* attribute. -See <> and <> -for more details. -* Enables Spring Data GemFire to be fully built and ran on JDK 7 and JDK 8 (Note, however, GemFire has not yet -been fully tested and supported on JDK 8; -See http://gemfire.docs.pivotal.io/docs-gemfire/supported_configs/supported_configs_and_system_reqs.html[GemFire User Guide] -for additional details. -[[new-in-1-5-0]] -== New in the 1.5 Release +[[new-in-2-0-0]] +== New in the 2.0.0.RELEASE -* Upgrades Spring Data GemFire to Spring Data Commons 1.9.0 -* Upgrades Spring Data GemFire to Spring Framework 4.0.7 -* Reference Guide migrated to Asciidoc -* Renewed support for deploying Spring Data GemFire in an OSGi container. -* Removed all default values in the Spring Data GemFire XML namespace Region-type elements, relying on GemFire defaults -instead. -* Added convenience to automatically create Disk Store directory locations without the need to create them manually, -as required by GemFire. -* SDG annotated Functions can now be executed from Gfsh. -* Enable GemFire GatewayReceivers to be started manually. -* Support for Auto Region Lookups. See <> for further details. -* Support for Region Templates See <> for further details. - -[[new-in-1-6-0]] -== New in the 1.6 Release - -* Upgrades Spring Data GemFire to GemFire 8.0. -* Adds support for GemFire 8's new Cluster-based Configuration. -* Enables 'auto-reconnect' functionality to be employed in Spring-configured GemFire Servers. -* Allows the creation of concurrent and parallel Async Event Queues and Gateway Senders. -* Adds support for GemFire 8's Region data compression. -* Adds attributes to set both critical and warning percentages on Disk Store usage. -* Supports the capability to add the new EventSubstitutionFilters to GatewaySenders. - -[[new-in-1-7-0]] -== New in the 1.7 Release - -* Upgrades Spring Data GemFire to GemFire 8.1.0. -* Early Access support for Apache Geode. -* Support for adding Spring defined Cache Listeners, Loaders and Writers on "existing" GemFire Regions configured in Spring XML, -`cache.xml` or even with GemFire's _Cluster Config_. -* Spring JavaConfig support added to `SpringContextBootstrappingInitializer`. -* Support for custom `ClassLoaders` in `SpringContextBootstrappingInitializer` to load Spring-defined bean classes. -* Support for `LazyWiringDeclarableSupport` re-initialization and complete replacement for `WiringDeclarableSupport`. -* Adds `locators` and `servers` attributes to the `` element allowing variable Locator/Server -endpoint lists configured with Spring's property placeholders. -* Enables the use of `` element with non-Spring configured GemFire Servers. -* Multi-Index definition and creation support. -* <> -* <> -* <> - -[[new-in-1-8-0]] -== New in the 1.8 Release - -* Upgrades Spring Data GemFire to GemFire 8.2.0. +* Upgrades to Apache Geode 1.2.0 (GA) release. +* Upgrades to Spring Framework 5.0.0.RELEASE. +* Upgrades to Spring Data Commons Kay. +* Spring Data Geode joins the Spring Data Release Train (Kay) as a new Spring Data module. +* Additional improvements in the new Annotation-based configuration model. +* Support Apache Geode's Apache Lucene Integration. diff --git a/src/main/asciidoc/introduction/requirements.adoc b/src/main/asciidoc/introduction/requirements.adoc index 7547cdb4..0b0aaa02 100644 --- a/src/main/asciidoc/introduction/requirements.adoc +++ b/src/main/asciidoc/introduction/requirements.adoc @@ -1,5 +1,5 @@ [[requirements]] = Requirements -Spring Data GemFire requires JDK 6.0 or above, http://projects.spring.io/spring-framework[Spring Framework] 3 -and http://www.pivotal.io/big-data/pivotal-gemfire[Pivotal GemFire] 6.6 or above (version 7 or above is recommended). +_Spring Data Geode_ requires JDK 8.0, http://projects.spring.io/spring-framework[Spring Framework] 5 +and http://geode.apache.org/[Apache Geode] 1.2.0. diff --git a/src/main/asciidoc/links.adoc b/src/main/asciidoc/links.adoc index b8a193e4..c5a092a4 100644 --- a/src/main/asciidoc/links.adoc +++ b/src/main/asciidoc/links.adoc @@ -1,12 +1,14 @@ [[sgf-links]] = Useful Links -* http://projects.spring.io/spring-data-gemfire[Spring Data GemFire Home Page] -* http://www.pivotal.io/big-data/pivotal-gemfire[Pivotal GemFire Home Page] -* http://gemfire.docs.pivotal.io/index.html[Pivotal GemFire Documentation] -* https://support.pivotal.io/hc/en-us/categories/200072748-Pivotal-GemFire-Knowledge-Base[Pivotal GemFire Knowledge Base] -* https://support.pivotal.io/hc/communities/public/topics/200053218-Pivotal-GemFire-General[Pivotal GemFire Community Home Page] -* http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire[VMWare vFabric GemFire Community Home Page] -* http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data GemFire Forum (StackOverflow)] -* http://forum.spring.io/forum/spring-projects/data/gemfire[Spring Data GemFire Forum (spring.io archive)] - +* http://projects.spring.io/spring-data-gemfire[Spring Data GemFire Project Page] +* https://github.com/spring-projects/spring-data-geode[Spring Data Geode source code] +* https://jira.spring.io/browse/DATAGEODE[Spring Data Geode JIRA] +* http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data GemFire on StackOverflow] +* http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the Spring Data GemFire Forum on Spring IO] +* http://geode.apache.org/[Apache Geode Home Page] +* http://geode.apache.org/docs/[Apache Geode Documentation] +* http://geode.apache.org/community/[Apache Geode Community] +* https://github.com/apache/geode[Apache Geode source code] +* https://issues.apache.org/jira/browse/GEODE/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel[Apache Geode JIRA] +* http://stackoverflow.com/search?q=Apache%20Geode[Apache Geode on StackOverflow] diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 11d79b3f..dc397e7b 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,6 +1,16 @@ = Preface -Spring Data GemFire focuses on integrating the Spring Framework's powerful, non-invasive programming model and concepts with Pivotal GemFire, simplifying configuration, development and providing high-level abstractions. This document assumes the reader already has a basic familiarity with the Spring Framework and Pivotal GemFire concepts and APIs. +_Spring Data Geode_ focuses on integrating the _Spring Framework's_ powerful, non-invasive programming model +and concepts with Apache Geode to simplify configuration and development of Java applications using Geode. -While every effort has been made to ensure this documentation is comprehensive and there are no errors, some topics might require more explanation and some typos might have crept in. If you do spot any mistakes or even more serious errors and you can spare a few cycles, please do bring the errors to the attention of the Spring Data GemFire team by raising an https://jira.spring.io/browse/SGF[issue]. Thank you. +This document assumes the reader already has a basic familiarity with the _Spring Framework_ and Apache Geode +concepts and APIs. +While every effort has been made to ensure this documentation is comprehensive and complete, with no errors, +some topics are beyond the scope of this document and may require more explanation (e.g. data distribution management +with partitioning for HA while still preserving consistency). Additionally, some typos might have crept in. +If you do spot mistakes or even more serious errors and you can spare a few cycles, please do bring these issues +to the attention of the _Spring Data Geode_ team by raising an appropriate +https://jira.spring.io/browse/DATAGEODE[issue]. + +Thank you. diff --git a/src/main/asciidoc/reference/bootstrap.adoc b/src/main/asciidoc/reference/bootstrap.adoc index eac60f06..278aa4a9 100644 --- a/src/main/asciidoc/reference/bootstrap.adoc +++ b/src/main/asciidoc/reference/bootstrap.adoc @@ -1,58 +1,58 @@ [[bootstrap]] -= Bootstrapping GemFire with the Spring container += Bootstrapping Apache Geode with the Spring container -Spring Data GemFire provides full configuration and initialization of the Pivotal GemFire In-Memory Data Grid -using the Spring IoC container. The framework includes several classes to help simplify the configuration of -Pivotal GemFire components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup +_Spring Data Geode_ provides full configuration and initialization of the Apache Geode In-Memory Data Grid (IMDG) +using the _Spring_ IoC container. The framework includes several classes to help simplify the configuration of +Apache Geode components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup along with several other Distributed System components in order to support a variety of use cases with minimal effort. -NOTE: This section assumes basic familiarity with Pivotal GemFire. For more information, -see the http://www.pivotal.io/big-data/pivotal-gemfire[product documentation]. +NOTE: This section assumes basic familiarity with Apache Geode. For more information, +see the Apache Geode http://geode.apache.org/docs/[product documentation]. -[[bootstrap:region:spring:config]] -== Advantages of using Spring over GemFire `cache.xml` +[[bootstrap:namespace:xml]] +== Advantages of using Spring over Apache Geode `cache.xml` -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. +_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. -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 <> to see how you can still use `Declarables` within Spring's IoC/DI container). +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 <> 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. +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. [[bootstrap:namespace]] -== Using the Core Spring Data GemFire Namespace +== Using the Core Namespace -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 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 -http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[this] appendix -in the Spring Framework reference documentation. +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 `` 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 +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[appendix] +in the _Spring Framework_ reference documentation. -NOTE: Spring Data Repository support uses a separate XML namespace. See <> for more information -on how to configure Spring Data GemFire Repositories. +NOTE: _Spring Data Repository_ support uses a separate XML namespace. See <> for more information +on how to configure _Spring Data Geode_ Repositories. -To use the Spring Data GemFire XML namespace, simply declare it in your Spring XML configuration meta-data: +To use the _Spring Data Geode_ XML namespace, simply declare it in your _Spring_ XML configuration meta-data: [source,xml] ---- + xmlns:gfe="http://www.springframework.org/schema/geode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"> + http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd"> @@ -60,26 +60,28 @@ To use the Spring Data GemFire XML namespace, simply declare it in your Spring X ---- -<1> Spring GemFire namespace prefix. Any name will do but through out the reference documentation, `gfe` will be used. -<2> The namespace URI. -<3> The namespace URI location. Note that even though the location points to an external address (which exists and is valid), Spring will resolve the schema locally as it is included in the Spring Data GemFire library. -<4> Declaration example for the GemFire namespace. Notice the prefix usage. +<1> _Spring Data Geode_ XML namespace prefix. Any name will do but through out this reference documentation, +`gfe` will be used. +<2> The XML namespace prefix is mapped to the URI. +<3> The XML namespace URI location. Note that even though the location points to an external address (which does exist +and is valid), _Spring_ will resolve the schema locally as it is included in the _Spring Data Geode_ library. +<4> Example declaration using the XML namespace with the `gfe` prefix. [NOTE] ==== -It is possible to change the default namespace, for example from `beans` to `gfe`. This is useful for configuration -composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace +It is possible to change the default namespace from `beans` to `gfe`. This is useful for XML configuration +composed mainly of Geode components as it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above: [source,xml] ---- - - xmlns:beans="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + + xmlns:beans="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"> + http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd"> @@ -87,19 +89,21 @@ prefix declaration above: ---- -<1> The default namespace declaration for this XML file points to the Spring Data GemFire namespace. -<2> The `beans` namespace prefix declaration. +<1> The default namespace declaration for this XML document points to the _Spring Data Geode_ XML namespace. +<2> The `beans` namespace prefix declaration for _Spring's_ raw bean definitions. <3> Bean declaration using the `beans` namespace. Notice the prefix. -<4> Bean declaration using the `gfe` namespace. Notice the lack of prefix (as the default namespace is used). +<4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace. ==== :leveloffset: +1 -include::{basedocdir}/reference/cache.adoc[] + include::{basedocdir}/reference/data-access.adoc[] +include::{basedocdir}/reference/cache.adoc[] include::{basedocdir}/reference/region.adoc[] include::{basedocdir}/reference/indexing.adoc[] include::{basedocdir}/reference/diskstore.adoc[] include::{basedocdir}/reference/snapshot.adoc[] include::{basedocdir}/reference/function.adoc[] include::{basedocdir}/reference/gateway.adoc[] + :leveloffset: -1 diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index 50569b28..bbe32801 100644 --- a/src/main/asciidoc/reference/cache.adoc +++ b/src/main/asciidoc/reference/cache.adoc @@ -1,16 +1,17 @@ [[bootstrap:cache]] -= Configuring a GemFire Cache += Configuring a Cache -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. +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. -NOTE: This section describes the creation and configuration of a cache member, appropriate in peer-to-peer topologies -and cache servers. A cache member is also commonly used for standalone applications, integration tests and proof of -concepts. In typical production systems, most application processes will act as cache clients, creating a `ClientCache` -instance instead. This is described in the sections <> and <>. +NOTE: This section describes the creation and configuration of a peer cache member, appropriate in +peer-to-peer (P2P) topologies and cache servers. A cache member can also be used in standalone applications +and integration tests. However, in most typical production systems, most application processes will act as +cache clients, creating a `ClientCache` instance instead. This is described in the sections <> +and <>. -A cache with default configuration can be created with a very simple declaration: +A peer cache with default configuration can be created with a very simple declaration: [source,xml] ---- @@ -18,39 +19,38 @@ 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. +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 GemFire_ components that depend on the cache respect this naming convention, so there is no need +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 namespace elements. Also, you can easily override the cache's bean name using +attribute provided by various SDG XML namespace elements. Also, you can easily override the cache's bean name using the `id` attribute: [source,xml] ---- - + ---- -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: +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: [source,xml] ---- - + ---- -In this example, if the cache needs to be created, it will use the file named `cache.xml` located in the classpath root +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. NOTE: The configuration makes use of Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#resources[`Resource`] abstraction to locate the file. This allows various search patterns to be used, depending on the runtime environment or the prefix specified (if any) in the resource location. -In addition to referencing an external XML configuration file, a developer may also specify GemFire System -http://gemfire.docs.pivotal.io/docs-gemfire/reference/topics/gemfire_properties.html[properties] +In addition to referencing an external XML configuration file, a developer may also specify Geode System +http://geode.apache.org/docs/guide/11/reference/topics/gemfire_properties.html[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` @@ -60,21 +60,23 @@ directly or load properties from a properties file: ---- - + ---- -The latter approach is recommended for externalizing environment specific settings outside the application configuration. +Using a properties file is recommended for externalizing environment specific settings outside +the application configuration. NOTE: Cache settings apply only if a new cache needs to be created. If an open cache already exists in the VM, these settings are ignored. @@ -89,10 +91,12 @@ or child elements: ---- lock-lease="120" lock-timeout="60" @@ -103,204 +107,220 @@ or child elements: pdx-read-serialized="false" pdx-ignore-unread-fields="true" search-timeout="300" - use-cluster-configuration="false" - lazy-init="true"> + use-bean-factory-locator="true" + use-cluster-configuration="false" +> - + - - + + - + - + - + - ---- -<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, please consult the GemFire http://gemfire.docs.pivotal.io/index.html[product documentation]. -The `close` attribute determines if the cache should be closed when the Spring application context is closed. The default is `true` however for cases in which multiple application contexts use the cache (common in web applications), set this value to `false`. -The `lazy-init` attribute determines if the cache should be initialized before another bean references it. The default is `true` however in some cases it may be convenient to set this value to `false`. -<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected GemFire member to automatically reconnect and rejoin a GemFire cluster. -See the GemFire http://gemfire.docs.pivotal.io/docs-gemfire/latest/managing/autoreconnect/member-reconnect.html[product documentation] for more details. -<3> Setting the `use-cluster-configuration` attribute to true (default is false) to enable a GemFire member to retrieve the common, shared Cluster-based configuration from a Locator. -See the GemFire http://gemfire.docs.pivotal.io/docs-gemfire/configuring/cluster_config/gfsh_persist.html[product documentation] for more details. -<4> An example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement -http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionListener.html[TransactionListener]. -`TransactionListener(s)` can be implemented to handle transaction related events. -<5> An example of a `TransactionWriter` callback declaration using an inner bean declaration this time. The bean must implement -http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionWriter.html[TransactionWriter]. -`TransactionWriter` is a callback that is allowed to veto a transaction. -<6> An example of a `GatewayConflictResolver` declaration using a bean reference. The referenced bean must implement -http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/util/GatewayConflictResolver.html[GatewayConflictResolver]. -GatewayConflictResolver is a Cache-level plugin that is called upon to decide what to do with events that originate in other systems and arrive through the WAN Gateway. -<7> Enable GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/DynamicRegionFactory.html[DynamicRegionFactory], -which provides a distributed region creation service. -<8> Declares a JNDI binding to enlist an external DataSource in a GemFire transaction. - -NOTE: The `use-bean-factory-locator` attribute (not shown) deserves a mention. The factory bean responsible for -creating the cache uses an internal Spring type called a `BeanFactoryLocator` to enable user classes declared in -GemFire's native `cache.xml` to be registered as Spring beans. The `BeanFactoryLocator` implementation also permits -only one bean definition for a cache with a given id. In certain situations, such as running JUnit integration tests -from within Eclipse, it is necessary to disable the `BeanFactoryLocator` by setting this value to false to prevent -an exception. This exception may also arise during JUnit tests running from a build script. In this case the test runner -should be configured to fork a new JVM for each test (in maven, set `always`) . Generally, there is -no harm in setting this value to false. +<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, +please consult the Geode http://geode.apache.org/docs/[product documentation]. +The `close` attribute determines whether the cache should be closed when the Spring application context is closed. +The default is `true`, however, for use cases in which multiple application contexts use the cache +(common in web applications), set this value to `false`. +<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected Geode member to +automatically reconnect and rejoin the Geode cluster. +See the Geode http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation] +for more details. +<3> Setting the `use-bean-factory-locator` attribute to `true` (defaults to `false`) is only applicable when both +Spring (XML) configuration meta-data and Geode `cache.xml` is used to configure the Geode cache node +(whether client or peer). This option allows Geode components (e.g. `CacheLoader`) expressed in `cache.xml` +to be auto-wired with beans (e.g. `DataSource`) defined in the Spring application context. This option is typically +used in conjunction with `cache-xml-location`. +<4> Setting the `use-cluster-configuration` attribute to `true` (default is `false`) enables a Geode member to +retrieve the common, shared Cluster-based configuration from a Locator. +See the Geode http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation] +for more details. +<5> Example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/TransactionListener.html[TransactionListener]. +A `TransactionListener` can be implemented to handle transaction related events (e.g. afterCommit, afterRollback). +<6> Example of a `TransactionWriter` callback declaration using an inner bean declaration. The bean must implement +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/TransactionWriter.html[TransactionWriter]. +The `TransactionWriter` is a callback that is allowed to veto a transaction. +<7> Example of a `GatewayConflictResolver` callback declaration using a bean reference. The referenced bean +must implement http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/util/GatewayConflictResolver.html +[GatewayConflictResolver]. +A `GatewayConflictResolver` is a Cache-level plugin that is called upon to decide what to do with events that originate +in other systems and arrive through the WAN Gateway. +<8> Enable Geode's http://geode.apache.org/docs/guide/11/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], +which provides a distributed Region creation service. +<9> Declares a JNDI binding to enlist an external DataSource in a Geode transaction. +[[bootstrap:cache:pdx-serialization]] === Enabling PDX Serialization -The example above includes a number of attributes related to GemFire's enhanced serialization framework, PDX. +The example above includes a number of attributes related to Geode's enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX -is enabled by registering a PDX serializer which is done via the `pdx-serializer` attribute. GemFire provides -an implementation class `org.apache.geode.pdx.ReflectionBasedAutoSerializer`, however it is common for developers -to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements -the required interface. More information on serialization support can be found in <> +is enabled by registering a `PdxSerializer` which is specified via the `pdx-serializer` attribute. Geode provides +an implementing class `org.apache.geode.pdx.ReflectionBasedAutoSerializer` that uses Java Reflection, however, it is +common for developers to provide their own implementation. The value of the attribute is simply a reference to +a Spring bean that implements the `PdxSerializer` interface. + +More information on serialization support can be found in <> [[boostrap:cache:auto-reconnect]] === Enabling auto-reconnect -Setting the `` attribute to `true` should be done with care. -Generally, enabling 'auto-reconnect' should only be done in cases where _Spring Data GemFire's_ XML namespace is used to -configure and bootstrap a new GemFire Server data node to add to the cluster. In other words, 'auto-reconnect' -should not be used when _Spring Data GemFire_ is used to develop and build an GemFire application that also happens -to be a peer cache member of the GemFire cluster. +Generally, 'auto-reconnect' should only be enabled in cases where _Spring Data Geode's_ XML namespace is used to +configure and bootstrap a new, non-application Geode Server to add to a cluster. In other words, 'auto-reconnect' +should not be enabled when _Spring Data Geode_ is used to develop and build an Geode application that also happens +to be a peer cache member of the Geode cluster. -The main reason is most GemFire applications use references to the GemFire cache or regions in order to perform -data access operations. The references are "injected" by the Spring container into application components (e.g. DAOs -or Repositories) for use by the application. When a member (such as the application) is forcefully disconnected -from the rest of the cluster, presumably because the member (the application) has become unresponsive for -a period of time, or network partition separates one or more members (along with the application peer cache member) into -a group that is too small to act as the distributed system, the member will shutdown and all GemFire component references -(e.g. Cache, Regions, etc) become invalid. +The main reason for this is that most Geode applications use references to the Geode cache or Regions in order to +perform data access operations. These references are "injected" by the Spring container into application components +(e.g. DAOs or Repositories) for use by the application. When a peer member is forcefully disconnected from the rest +of the cluster, presumably because the peer member has become unresponsive or a network partition separates one or more +peer members into a group too small to function as an independent distributed system, the peer member will shutdown +and all Geode component references (e.g. Cache, Regions, etc) become invalid. -Essentially, the current forced-disconnect processing in each member dismantles the system from the ground up. -It shuts down the JGroups stack, puts the Distributed System in a shut-down state and then closes the Cache. -This effectively loses all in-memory information. +Essentially, the current forced-disconnect processing logic in each peer member dismantles the system from the ground up. +The JGroups stack shuts down, the Distributed System is put in a shutdown state and finally, the Cache is closed. +Effectively, all memory references become stale and are lost. -After being disconnected from a distributed system and successfully shutting down, the GemFire member then restarts in a -"reconnecting" state, while periodically attempting to rejoin the distributed system. If the member succeeds in reconnecting, -the member rebuilds its "view" of the distributed system from existing members and receives a new distributed system ID. +After being disconnected from the Distributed System a peer member enters a "reconnecting" state and periodically +attempts to rejoin the Distributed System. If the peer member succeeds in reconnecting, the member rebuilds +its "view" of the Distributed System from existing members and receives a new Distributed System ID. Additionally, all +Cache, Regions and other Geode components are reconstructed. Therefore, all old references, which may have been +injected into application by the Spring container are now stale and no longer valid. -This means the cache, regions and other GemFire components are reconstructed and all old references that may have been -injected into application are now stale and no longer valid. +Geode makes no guarantee, even when using the Geode public Java API, that application Cache, Region or other +component references will be automatically refreshed by the reconnect operation. As such, Geode applications +must take care to refresh their own references. -GemFire makes no guarantee, even when using the GemFire public Java API, that application cache, region or other -component references will be automatically refreshed by the reconnect operation. As such, applications must take care -to refresh their own references. +Unfortunately, there is no way to be notified of a disconnect event, and subsequently, a reconnect event. +If that were the case, the application developer would have a clean way to know when to call +`ConfigurableApplicationContext.refresh()`, if even applicable for an application to do so, which is why +this "feature" of Apache Geode is not recommended for peer cache Geode applications. -Unfortunately there is no way to be "notified" of a disconnect and subsequently a reconnect event. If so, the application -developer would then have a clean way to know when to call ConfigurableApplicationContext.refresh(), if even applicable -for an application to do so, which is why this "feature" of GemFire 8 is not recommended for peer cache GemFire applications. - -For more information about 'auto-reconnect', see GemFire's http://gemfire.docs.pivotal.io/docs-gemfire/latest/managing/autoreconnect/member-reconnect.html[product documentation]. +For more information about 'auto-reconnect', see Geode's +http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation]. [[bootstrap:cache:cluster-configuration]] === Using Cluster-based Configuration -GemFire 8's new Cluster-based Configuration Service is a convenient way for a member joining the cluster to get a -"consistent view" of the cluster, by using the shared, persistent configuration maintained by a Locator, ensuring -the member's configuration will be compatible with the GemFire distributed system when the member joins. +Apache Geode's Cluster Configuration Service is a convenient way for any peer member joining the cluster to get +a "consistent view" of the cluster by using the shared, persistent configuration maintained by a Locator. +Using the Cluster-based Configuration ensures the peer member's configuration will be compatible with +the Geode Distributed System when the member joins. -This feature of Spring Data GemFire (setting the `use-cluster-configuration` attribute to true) works in the same way -as the `cache-xml-location` attribute, except the source of the GemFire configuration meta-data comes from a network -Locator as opposed to a native `cache.xml` file. +This feature of _Spring Data Geode_ (setting the `use-cluster-configuration` attribute to `true`) works in the same way +as the `cache-xml-location` attribute, except the source of the Geode configuration meta-data comes from the network +via a Locator as opposed to a native `cache.xml` file residing in the local file system. -All GemFire native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service, -gets applied before any Spring XML configuration meta-data. As such, Spring's config serves to "augment" the -native GemFire configuration meta-data, which would most likely be specific to the application. +All Geode native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service, +gets applied before any _Spring_ (XML) configuration meta-data. As such, _Spring's_ config serves to "augment" the +native Geode configuration meta-data and would most likely be specific to the application. -Again, to enable this feature, just specify the following in the Spring XML config: +Again, to enable this feature, just specify the following in the _Spring_ XML config: [source,xml] ---- ---- -NOTE: While certain GemFire tools, like Gfsh, have their actions "recorded" when any schema-like change is made -(e.g. `gfsh>create region --name=Example --type=PARTITION`) to the cluster, Spring Data GemFire's configuration meta-data -specified with the XML namespace is not recorded. The same is true when using GemFire's public Java API directly; -it too is not recorded. +NOTE: While certain Geode tools, like _Gfsh_, have their actions "recorded" when schema-like changes are made +(e.g. `gfsh>create region --name=Example --type=PARTITION`), _Spring Data Geode's_ configuration meta-data +is not recorded. The same is true when using Geode's public Java API directly; it too is not recorded. -For more information on GemFire's Cluster Configuration Service, see the -http://gemfire.docs.pivotal.io/docs-gemfire/configuring/cluster_config/gfsh_persist.html[product documentation]. +For more information on Geode's Cluster Configuration Service, see the +http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation]. [[bootstrap:cache:server]] -== Configuring a GemFire Cache Server +== Configuring a Geode CacheServer -_Spring Data GemFire_ includes dedicated support for configuring a http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/server/CacheServer.html[CacheServer], +_Spring Data Geode_ includes dedicated support for configuring a +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/server/CacheServer.html[CacheServer], allowing complete configuration through the Spring container: [source,xml] ---- + xmlns:gfe="http://www.springframework.org/schema/geode" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd + http://www.springframework.org/schema/geode http://www.springframework.org/schema/geode/spring-geode.xsd +"> - + - + + bind-address="localhost" host-name-for-clients="localhost" port="${geode.cache.server.port}" + load-poll-interval="2000" max-connections="22" max-message-count="1000" max-threads="16" + max-time-between-pings="30000" groups="test-server"> + + - + ---- The configuration above illustrates the `cache-server` element and the many options available. -NOTE: Rather than hard-coding the port, this configuration uses Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config-body-schemas-context[context] namespace to declare a `property-placeholder`. +NOTE: Rather than hard-coding the port, this configuration uses _Spring's_ +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config-body-schemas-context[context] +namespace to declare a `property-placeholder`. http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-factory-placeholderconfigurer[property placeholder] reads one or more properties files and then replaces property placeholders with values at runtime. This allows administrators -to change values without having to touch the main application configuration. Spring also provides the http://docs.spring.io/spring/docs/3.2.11.RELEASE/spring-framework-reference/htmlsingle/#new-feature-el[SpEL] and the http://docs.spring.io/spring/docs/3.2.11.RELEASE/spring-framework-reference/htmlsingle/#new-in-3.1-environment-abstraction[environment abstraction] -to support externalization of environment-specific properties from the main codebase, easing deployment across multiple machines. +to change values without having to touch the main application configuration. _Spring_ also provides the +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#expressions[SpEL] +and the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-environment[environment abstraction] +to support externalization of environment-specific properties from the main codebase, easing deployment +across multiple machines. -NOTE: To avoid initialization problems, the `CacheServer` started by _Spring Data GemFire_ will start *after* the container -has been fully initialized. This allows potential regions, listeners, writers or instantiators defined declaratively -to be fully initialized and registered before the server starts accepting connections. Keep this in mind when -programmatically configuring these elements as the server might start after your components and thus not be seen -by the clients connecting right away. +NOTE: To avoid initialization problems, the `CacheServer` started by _Spring Data Geode_ will start *after* +the _Spring_ container has been fully initialized. This allows potential Regions, Listeners, Writers or Instantiators +defined declaratively to be fully initialized and registered before the server starts accepting connections. +Keep this in mind when programmatically configuring these elements as the server might start after your components +and thus not be seen by the clients connecting right away. [[bootstrap:cache:client]] -== Configuring a GemFire ClientCache +== Configuring a Geode ClientCache -In addition to defining a GemFire peer http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/Cache.html[Cache], -_Spring Data GemFire_ also supports the definition of a GemFire http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientCache.html[ClientCache] -in a Spring context. A `ClientCache` definition is very similar in configuration and use to the GemFire peer <> -and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. +In addition to defining a Geode peer http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Cache.html[Cache], +_Spring Data Geode_ also supports the definition of a Geode http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html[ClientCache] +in a _Spring_ context. A `ClientCache` definition is very similar in configuration and use to +the Geode peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. -The simplest definition of a GemFire cache client with default configuration can be accomplished with the following +The simplest definition of a Geode cache client using default configuration can be accomplished with the following declaration: [source,xml] ---- - + ---- -`client-cache` supports much of the same options as the <> element. However, as opposed -to a *full-fledged* cache member, a client cache connects to a remote cache server through a Pool. By default, a Pool -is created to connect to a server running on `localhost`, listening to port `40404`. The default Pool is used -by all client Regions unless the Region is configured to use a different Pool. +`client-cache` supports many of the same options as the <> element. However, as opposed +to a *full-fledged* peer cache member, a cache client connects to a remote cache server through a Pool. By default, +a Pool is created to connect to a server running on `localhost`, listening to port `40404`. The default Pool is used +by all client Regions unless the Region is configured to use a specific Pool. Pools can be defined with the `pool` element. This client-side Pool can be used to configure connectivity directly to -a server for individual entities or to the entire cache through one or more Locators. +a server for individual entities or the entire cache through one or more Locators. For example, to customize the default Pool used by the `client-cache`, the developer needs to define a Pool and wire it to the cache definition: @@ -308,23 +328,23 @@ to the cache definition: [source,xml] ---- - + - - - + + + ---- -The `` element also includes the `ready-for-events` attribute. If set to `true`, the client cache -initialization will include a call to http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientCache.html#readyForEvents()[ClientCache.readyForEvents()]. +The `` element also has a `ready-for-events` attribute. If set to `true`, the client cache +initialization will include a call to http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html#readyForEvents--[ClientCache.readyForEvents()]. Client-side configuration is covered in more detail in <>. [[bootstrap:cache:client:pool]] -=== GemFire's DEFAULT Pool and Spring Data GemFire Pool Definitions +=== Geode's DEFAULT Pool and Spring Data Geode Pool Definitions -If a GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: +If a Geode `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: [source,xml] ---- @@ -334,14 +354,14 @@ If a GemFire `ClientCache` is local-only, then no Pool definition is required. ---- In this case, the "Example" Region is `LOCAL` and no data is distributed between the client and a server, therefore, -no Pool is necessary. This is true for any client-side, local-only Region, as defined by the GemFire's -http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientRegionShortcut.html[ClientRegionShortcut] +no Pool is necessary. This is true for any client-side, local-only Region, as defined by the Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientRegionShortcut.html[ClientRegionShortcut] (all `LOCAL_*` shortcuts). -However, if the client Region is a (caching) proxy to a server-side Region, then a Pool is required. There are several +However, if a client Region is a (caching) proxy to a server-side Region, then a Pool is required. There are several ways to define and use a Pool in this case. -When a client cache, Pool and proxy-based Region are all defined, but not explicitly identified, _Spring Data GemFire_ +When a client cache, Pool and proxy-based Region are all defined, but not explicitly identified, _Spring Data Geode_ will resolve the references automatically for you. For example: @@ -351,31 +371,31 @@ For example: - + ---- -In this case, the client cache is identified as `gemfireCache`, the Pool as `gemfirePool` and the client Region as, -well, "Example". However, the client cache will initialize GemFire's DEFAULT Pool from the `gemfirePool` -and the client Region will use the `gemfirePool` when distributing data between the client and the server. +In the example above, the client cache is identified as `gemfireCache`, the Pool as `gemfirePool` and the client Region +as "Example". However, the client cache will initialize Geode's DEFAULT Pool from `gemfirePool` and the client Region +will use the `gemfirePool` when distributing data between the client and the server. -_Spring Data GemFire_ basically resolves the above configuration to the following: +Basically, _Spring Data Geode_ resolves the above configuration to the following: [source,xml] ---- - + ---- -GemFire still creates a Pool called "DEFAULT". _Spring Data GemFire_ will just cause the "DEFAULT" Pool to be -initialized from `gemfirePool`. This is useful in situations where multiple Pools are defined and client Regions +Geode still creates a Pool called "DEFAULT". _Spring Data Geode_ will just cause the "DEFAULT" Pool to be +initialized from the `gemfirePool`. This is useful in situations where multiple Pools are defined and client Regions are using separate Pools. Consider the following: @@ -385,11 +405,11 @@ Consider the following: - + - + @@ -399,12 +419,12 @@ Consider the following: ---- -In this setup, the GemFire client cache's "DEFAULT" Pool is initialized from "locatorPool" as specified with the -`pool-name` attribute. There is no _Spring Data GemFire_-defined `gemfirePool` since both Pools were explicitly +In this setup, the Geode client cache's "DEFAULT" Pool is initialized from "locatorPool" as specified with the +`pool-name` attribute. There is no _Spring Data Geode_-defined `gemfirePool` since both Pools were explicitly identified (named) "locatorPool" and "serverPool", respectively. The "Example" Region explicitly refers to and uses the "serverPool" exclusively. The "AnotherExample" Region uses -GemFire's "DEFAULT" Pool, which was configured from the "locatorPool" based on the client cache bean definition's +Geode's "DEFAULT" Pool, which was configured from the "locatorPool" based on the client cache bean definition's `pool-name` attribute. Finally, the "YetAnotherExample" Region will not use a Pool since it is `LOCAL`. diff --git a/src/main/asciidoc/reference/cq-container.adoc b/src/main/asciidoc/reference/cq-container.adoc index cbbcfe18..8c3f83d5 100644 --- a/src/main/asciidoc/reference/cq-container.adoc +++ b/src/main/asciidoc/reference/cq-container.adoc @@ -1,25 +1,56 @@ -[[apis:cq-container]] -= GemFire Continuous Query Container +[[apis:continuous-query]] += Continuous Query (CQ) -A powerful functionality offered by GemFire is http://community.gemstone.com/display/gemfire/Continuous+Querying[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. +A powerful functionality offered by Apache Geode is +http://geode.apache.org/docs/guide/11/developing/continuous_querying/chapter_overview.html[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. -NOTE: Currently, continuous queries are supported by GemFire only in client/server topologies. Additionally the pool used is required to have the `subscription` property enabled. Please refer to the documentation for more information. +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. -[[apis:cq-container:containers]] +NOTE: Currently, Continuous Query is only supported in Geode's client/server topology. Additionally, the client Pool +used is required to have the subscription enabled. Please refer to the Geode +http://geode.apache.org/docs/guide/11/developing/continuous_querying/implementing_continuous_querying.html[documentation] +for more information. + +[[apis:continuous-query:container]] == Continuous Query Listener Container -Spring Data GemFire simplifies the creation, registration, life-cycle and dispatch of CQs by taking care of the infrastructure around them through `ContinuousQueryListenerContainer` which does all the heavy lifting on behalf of the user - users familiar with EJB and JMS should find the concepts familiar as it is designed as close as possible to the support in Spring Framework and its message-driven POJOs (MDPs) +_Spring Data Geode_ simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of +the infrastructure around CQ with the use of SDG's `ContinuousQueryListenerContainer`, which does all the heavy lifting +on behalf of the user. Users familiar with EJB and JMS should find the concepts familiar as it is designed +as close as possible to the support provided in the _Spring Framework_ with its Message-driven POJOs (MDPs). -`ContinuousQueryListenerContainer` acts as an event (or message) listener container; it is used to receive the events from the registered CQs and drive the POJOs that are injected into it. The listener container is responsible for all threading of message reception and dispatches into the listener for processing. It acts as the intermediary between an EDP (Event Driven POJO) and the event provider and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and the like. This allows you as an application developer to write the (possibly complex) business logic associated with receiving an event (and reacting to it), and delegates boilerplate GemFire infrastructure concerns to the framework. +The SDG `ContinuousQueryListenerContainer` acts as an event (or message) listener container; it is used to +receive the events from the registered CQs and invoke the POJOs that are injected into it. The listener container +is responsible for all threading of message reception and dispatches into the listener for processing. It acts as +the intermediary between an EDP (Event-driven POJO) and the event provider and takes care of creation and registration +of CQs (to receive events), resource acquisition and release, exception conversion and the like. This allows you, +as an application developer, to write the (possibly complex) business logic associated with receiving an event +(and reacting to it), and delegate the boilerplate Geode infrastructure concerns to the framework. -The container is fully customizable - one can chose either to use the CQ thread to perform the dispatch (synchronous delivery) or a new thread (from an existing pool for examples) for an asynchronous approach by defining the suitable `java.util.concurrent.Executor` (or Spring's `TaskExecutor`). Depending on the load, the number of listeners or the runtime environment, one should change or tweak the executor to better serve her needs - in particular in managed environments (such as app servers), it is highly recommended to pick a a proper `TaskExecutor` to take advantage of its runtime. +The listener container is fully customizable. A developer can chose either to use the CQ thread to perform the dispatch +(synchronous delivery) or a new thread (from an existing pool) for an asynchronous approach by defining the suitable +`java.util.concurrent.Executor` (or _Spring's_ `TaskExecutor`). Depending on the load, the number of listeners +or the runtime environment, the developer should change or tweak the executor to better serve her needs. In particular, +in managed environments (such as app servers), it is highly recommended to pick a proper `TaskExecutor` +to take advantage of its runtime. -[[apis:cq-container:adapter]] -== The `ContinuousQueryListenerAdapter` and `ContinuousQueryListener` +[[apis:continuous-query:adapter]] +== The `ContinuousQueryListener` and `ContinuousQueryListenerAdapter` -The `ContinuousQueryListenerAdapter` class is the final component in Spring Data GemFire CQ support: in a nutshell, it allows you to expose almost *any* class as a EDP (there are of course some constraints) - it implements `ContinuousQueryListener`, a simpler listener interface similar to GemFire http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/query/CqListener.html[CqListener]. +The `ContinuousQueryListenerAdapter` class is the final component in _Spring Data Geode_ CQ support. In a nutshell, +class allows you to expose almost *any* implementing class as an EDP with minimal constraints. +`ContinuousQueryListenerAdapter` implements the `ContinuousQueryListener` interface, a simple listener interface +similar to Geode's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/query/CqListener.html[CqListener]. -Consider the following interface definition. Notice the various event handling methods and their parameters: +Consider the following interface definition. Notice the various event handling methods and their parameters: [source,java] ---- @@ -28,7 +59,7 @@ public interface EventDelegate { void handleEvent(Operation baseOp); void handleEvent(Object key); void handleEvent(Object key, Object newValue); - void handleEvent(Throwable th); + void handleEvent(Throwable throwable); void handleQuery(CqQuery cq); void handleEvent(CqEvent event, Operation baseOp, byte[] deltaValue); void handleEvent(CqEvent event, Operation baseOp, Operation queryOp, Object key, Object newValue); @@ -37,43 +68,55 @@ public interface EventDelegate { [source,java] ---- -public class DefaultEventDelegate implements EventDelegate { +package example; + +class DefaultEventDelegate implements EventDelegate { // implementation elided for clarity... } ---- -In particular, note how the above implementation of the `EventDelegate` interface (the above `DefaultEventDelegate` class) has *no* GemFire dependencies at all. It truly is a POJO that we will make into an EDP via the following configuration (note that the class doesn't have to implement an interface, one is present only to better show case the decoupling between contract and implementation). +In particular, note how the above implementation of the `EventDelegate` interface has *no* Geode dependencies at all. +It truly is a POJO that we can and will make into an EDP via the following configuration. + +NOTE: the class does not have to implement an interface; an interface is only used to better showcase the decoupling +between the contract and the implementation. [source,xml] ---- + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd +"> - + - + - - + + - - + + ... ---- -NOTE: The example above shows some of the various forms that a listener can have; at its minimum the listener reference and the actual query definition are required. It's possible however to specify a name for the resulting continuous query (useful for monitoring) but also the name of the method (the default is `handleEvent`). The specified method can have various argument types, the `EventDelegate` interface lists the allowed types. +NOTE: The example above shows a few of the various forms that a listener can have; at its minimum, the listener +reference and the actual query definition are required. It's possible, however, to specify a name for +the resulting Continuous Query (useful for monitoring) but also the name of the method (the default is `handleEvent`). +The specified method can have various argument types, the `EventDelegate` interface lists the allowed types. -The example above uses the Spring Data GemFire namespace to declare the event listener container and automatically register the listeners. The full blown, *beans* definition is displayed below: +The example above uses the _Spring Data Geode_ namespace to declare the event listener container +and automatically register the listeners. The full blown, *beans* definition is displayed below: [source,xml] ---- @@ -88,16 +131,17 @@ The example above uses the Spring Data GemFire namespace to declare the event li - + - - + + ---- -Each time an event is received, the adapter automatically performs type translation between the GemFire event and the required method argument(s) transparently. Any exception caused by the method invocation is caught and handled by the container (by default, being logged). - +Each time an event is received, the adapter automatically performs type translation between the Geode event +and the required method argument(s) transparently. Any exception caused by the method invocation is caught +and handled by the container (by default, being logged). diff --git a/src/main/asciidoc/reference/data-access.adoc b/src/main/asciidoc/reference/data-access.adoc index 55601170..f45717df 100644 --- a/src/main/asciidoc/reference/data-access.adoc +++ b/src/main/asciidoc/reference/data-access.adoc @@ -1,30 +1,39 @@ [[data-access]] -= Using the GemFire Data Access Namespace += Using the Data Access Namespace -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 <> and function <> and a `` tag that offers a convenient way to connect to the data grid. +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 <> and function <> as well as +includes a `` tag that offers a convenient way to connect to the Apache Geode data grid. [[data-access:datasource]] -== An Easy Way to Connect to GemFire +== An Easy Way to Connect to Geode -For many applications, A basic connection to a GemFire grid, using default values is sufficient. Spring Data GemFire's `` tag provides a simple way to access data. The data source creates a client cache and connection pool. In addition, it will query the member servers for all existing root regions and create a proxy (empty) client region for each one. +For many applications, a basic connection to a Geode data grid using default values is sufficient. +_Spring Data Geode's_ `` tag provides a simple way to access data. The data source creates +a `ClientCache` and connection `Pool`. In addition, it will query the cluster servers for all existing root Regions +and create an (empty) client Region proxy for each one. [source,xml] ---- - + ---- -The datasource tag is syntactically similar to ``. It may be configured with one or more locator or server tags to connect to an existing data grid. Additionally, all attributes available to configure a pool are supported. This configuration will automatically create ClientRegion beans for each region defined on members connected to the locator, so they may be seamlessly referenced by Spring Data mapping annotations, GemfireTemplate, and wired into application classes. +The `` tag is syntactically similar to ``. It may be configured with one or more nested `locator` +or `server` tags to connect to an existing data grid. Additionally, all attributes available to configure a Pool +are supported. This configuration will automatically create client Region beans for each Region defined on +cluster members connected to the Locator, so they may be seamlessly referenced by _Spring Data_ mapping annotations, +`GemfireTemplate`, and wired into application classes. -Of course, you can explicitly configure client regions. For example, if you want to cache data in local memory: +Of course, you can explicitly configure client Regions. For example, if you want to cache data in local memory: [source,xml] ---- - + - + ---- - diff --git a/src/main/asciidoc/reference/data.adoc b/src/main/asciidoc/reference/data.adoc index c82e2591..5090b2e2 100644 --- a/src/main/asciidoc/reference/data.adoc +++ b/src/main/asciidoc/reference/data.adoc @@ -1,105 +1,135 @@ [[apis]] -= Working with GemFire APIs += Working with Apache Geode APIs -Once the GemFire Cache and Regions have been configured they can be injected and used inside application objects. This chapter describes the integration with Spring's Transaction Management functionality and `DaoException` hierarchy. It also covers support for dependency injection of GemFire managed objects. - -[[apis:exception-translation]] -== Exception Translation - -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 http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[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, http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#orm-exception-translation[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 `` declaration, as it acts as an exception translator which is automatically detected by the Spring infrastructure and used accordingly. +Once the Apache Geode Cache and Regions have been configured, they can be injected and used inside application objects. +This chapter describes the integration with _Spring's_ Transaction Management functionality and DAO exception hierarchy. +This chapter also covers support for dependency injection of Geode managed objects. [[apis:template]] == GemfireTemplate -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`. +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 GemFire `Region` instance and once configured is thread-safe and should be reused across multiple classes: +The template class requires a Geode `Region` instance, and once configured, is thread-safe and can be reused +across multiple application classes: [source,xml] ---- - + ---- -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: +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: [source,java] ---- template.execute(new GemfireCallback>() { - public Iterable doInGemfire(Region reg) throws GemFireCheckedException, GemFireException { - // working against a Region of String - Region region = reg; + public Iterable doInGemfire(Region region) throws GemFireCheckedException, GemFireException { + Region localRegion = (Region) region; - region.put("1", "one"); - region.put("3", "three"); + localRegion.put("1", "one"); + localRegion.put("3", "three"); - return region.query("length < 5"); + return localRegion.query("length < 5"); } }); ---- -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. +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. -[[apis:spring-cache-abstraction]] -== Support for Spring Cache Abstraction +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 http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[cache abstraction]. To use GemFire as a backing implementation, simply add `GemfireCacheManager` to your configuration: +[[apis:exception-translation]] +== Exception Translation -[source,xml] ----- - +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 +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[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, +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#orm-exception-translation[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 `` +or `` declaration, which acts as an exception translator and is automatically detected by +the _Spring_ infrastructure and used accordingly. - - - ----- - -[[apis:tx-mgmt]] +[[apis:transaction-management]] == Transaction Management -One of the most popular features of Spring Framework is http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction[transaction management]. If you are not familiar with it, we strongly recommend http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction-motivation[reading] about it 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). +One of the most popular features of the _Spring Framework_ is +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction[Transaction Management]. -For GemFire, Spring Data GemFire provides a dedicated, per-cache, transaction manager that, once declared, allows Region operations to be executed atomically through Spring: +If you are not familiar with _Spring's_ transaction abstraction then we strongly recommend +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction-motivation[reading] +about it 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_: [source,xml] ---- - + ---- -NOTE: The example above can be simplified even more by eliminating the `cache-ref` attribute if the GemFire Cache is defined under the default name`gemfireCache`. As with the other Spring Data GemFire namespace elements, if the Cache bean name is not configured, the aforementioned naming convention will used. Additionally, the transaction manager name is`gemfireTransactionManager` if not explicitly specified. +NOTE: The example above can be simplified even further by eliminating the `cache-ref` attribute if the GemFire cache +is defined under the default name, `gemfireCache`. As with the other _Spring Data Geode_ namespace elements, +if the cache bean name is not configured, the aforementioned naming convention will be used. +Additionally, the transaction manager name is `"gemfireTransactionManager"` if not explicitly specified. -Currently, 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, 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 of the underlying GemFire transaction manager, see the GemFire http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/CacheTransactionManager.html[documentation]. +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, +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 bevior of the underlying Geode transaction manager, please refer to the Geode +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheTransactionManager.html[CacheTransactionManager Javadoc] +as well as the http://geode.apache.org/docs/guide/11/developing/transactions/chapter_overview.html[documentation]. -:leveloffset: +1 include::{basedocdir}/reference/cq-container.adoc[] -:leveloffset: -1 [[apis:declarable]] -== Wiring `Declarable` components +== Wiring `Declarable` Components -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. +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 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. +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 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. +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. .Eliminate `Declarable` components **** -One can configure custom types entirely through Spring as mentioned in <>. That way, one does not have to implement the `Declarable` interface and also benefits from all the features of the Spring IoC container (not just dependency injection but also life-cycle and instance management). +A developer can configure custom types entirely through _Spring_ as mentioned in <>. +That way, a developer does not have to implement the `Declarable` interface, and also benefits from +all the features of the _Spring_ IoC container (not just dependency injection but also life-cycle +and instance management). **** -As an example of configuring a `Declarable` component using Spring, consider the following declaration (taken from the `Declarable` javadoc): +As an example of configuring a `Declarable` component using _Spring_, consider the following declaration +(taken from the `Declarable` http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Declarable.html[Javadoc]): [source,xml] ---- @@ -111,25 +141,34 @@ As an example of configuring a `Declarable` component using Spring, consider the ---- -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. +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. .Why is a base class needed? **** -In the current GemFire release there is no concept of an *object factory* and the types declared are instantiated and used as is. In other words, there is no easy way to manage object creation outside GemFire. +In the current Geode release there is no concept of an *object factory* and the types declared are instantiated +and used as is. In other words, there is no easy way to manage object creation outside Apache Geode. **** [[apis:declarable:template-wiring]] -=== Configuration using *template* definitions +=== Configuration using *template* bean definitions -When used, `WiringDeclarableSupport` tries to first locate an existing bean definition and use that as wiring template. Unless specified, the component class name will be used as an implicit bean definition name. Let's see how our `DBLoader` declaration would look in that case: +When used, `WiringDeclarableSupport` tries to first locate an existing bean definition and use that +as the wiring template. Unless specified, the component class name will be used as an implicit bean definition name. + +Let's see how our `DBLoader` declaration would look in that case: [source,java] ---- -public class DBLoader extends WiringDeclarableSupport implements CacheLoader { +class DBLoader extends WiringDeclarableSupport implements CacheLoader { + private DataSource dataSource; - public void setDataSource(DataSource ds){ - this.dataSource = ds; + public void setDataSource(DataSource dataSource){ + this.dataSource = dataSource; } public Object load(LoaderHelper helper) { ... } @@ -140,8 +179,7 @@ public class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- com.company.app.DBLoader - + ---- @@ -149,26 +187,28 @@ public class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd +"> - - + + ---- -In the scenario above, as no parameter was specified, a bean with the id/name `com.company.app.DBLoader` was used as a template for wiring the instance created by GemFire. For cases where the bean name uses a different convention, one can pass in the `bean-name` parameter in the GemFire configuration: +In the scenario above, as no parameter was specified, a bean with the id/name `com.company.app.DBLoader` was used +as a template for wiring the instance created by Geode. For cases where the bean name uses a different convention, +one can pass in the `bean-name` parameter in the Geode configuration: [source,xml] ---- com.company.app.DBLoader - + template-bean @@ -179,31 +219,43 @@ In the scenario above, as no parameter was specified, a bean with the id/name `c ---- + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd +"> - - + + ---- -NOTE: The *template* bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..). +NOTE: The *template* bean definitions do not have to be declared in XML. +Any format is allowed (Groovy, annotations, etc). [[apis:declarable:autowiring]] === Configuration using auto-wiring and annotations -If no bean definition is found, by default, `WiringDeclarableSupport` will http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-factory-autowire[autowire] the declaring instance. This means that unless any dependency injection *metadata* is offered by the instance, the container will find the object setters and try to automatically satisfy these dependencies. However, one can also use JDK 5 annotations to provide additional information to the auto-wiring process. We strongly recommend reading the dedicated http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[chapter] in the Spring documentation for more information on the supported annotations and enabling factors. +By default, if no bean definition is found, `WiringDeclarableSupport` will +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-factory-autowire[autowire] +the declaring instance. This means that unless any dependency injection *metadata* is offered by the instance, +the container will find the object setters and try to automatically satisfy these dependencies. +However, a developer can also use JDK 5 annotations to provide additional information to the auto-wiring process. -For example, the hypothetical `DBLoader` declaration above can be injected with a Spring-configured `DataSource` in the following way: +TIP: We strongly recommend reading the dedicated +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[chapter] +in the _Spring_ documentation for more information on the supported annotations and enabling factors. + +For example, the hypothetical `DBLoader` declaration above can be injected with a Spring-configured `DataSource` +in the following way: [source,java] ---- -public class DBLoader extends WiringDeclarableSupport implements CacheLoader { +class DBLoader extends WiringDeclarableSupport implements CacheLoader { + // use annotations to 'mark' the needed dependencies @javax.inject.Inject private DataSource dataSource; @@ -216,8 +268,7 @@ public class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- com.company.app.DBLoader - + ---- @@ -225,12 +276,12 @@ public class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd +"> @@ -238,5 +289,128 @@ public class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- -By using the JSR-330 annotations, the cache loader code has been simplified since the location and creation of the DataSource has been externalized and the user code is concerned only with the loading process. The `DataSource` might be transactional, created lazily, shared between multiple objects or retrieved from JNDI - these aspects can be easily configured and changed through the Spring container without touching the `DBLoader` code. +By using the JSR-330 annotations, the `CacheLoader` code has been simplified since the location and creation +of the `DataSource` has been externalized and the user code is concerned only with the loading process. +The `DataSource` might be transactional, created lazily, shared between multiple objects or retrieved from JNDI. +These aspects can easily be configured and changed through the _Spring_ container without touching +the `DBLoader` code. +[[apis:spring-cache-abstraction]] +== Support for Spring Cache Abstraction + +_Spring Data Geode_ provides an implementation of the _Spring_ +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[Cache Abstraction] +to position Apache Geode as a _caching provider_ in Spring's caching infrastructure. + +To use Apache Geode as a backing implementation, simply add `GemfireCacheManager` to your configuration: + +[source,xml] +---- + + + + + + + + + + + +---- + +NOTE: The `cache-ref` attribute on the `CacheManager` bean definition is not necessary if the default cache bean name +is used (i.e. "gemfireCache"), that is, `` without an explicit ID. + +When the `GemfireCacheManager` (Singleton) bean instance is declared and declarative caching is enabled +(either in XML with `` 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 does caching... + +[source,java] +---- +@Service +class CustomerService { + +@Cacheable(cacheNames="Accounts", key="#customer.id") +Account createAccount(Customer customer) { + ... +} +---- + +Then you will need the following config. + +XML: + +[source,xml] +---- + + + + + + + + + + + ... + + +---- + +JavaConfig: + +[source,java] +---- +@Configuration +@EnableCaching +class ApplicationConfiguration { + + @Bean + CacheFactoryBean gemfireCache() { + return new CacheFactoryBean(); + } + + @Bean + GemfireCacheManager cacheManager() { + return new GemfireCacheManager(gemfireCache()); + } + + @Bean("Accounts") + PartitionedRegionFactoryBean accountsRegion() { + PartitionedRegionFactoryBean accounts = new PartitionedRegionFactoryBean(); + + accounts.setCache(gemfireCache()); + accounts.setClose(false); + accounts.setPersistent(true); + + return accounts; + } +} +---- + +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 +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[documentation]. diff --git a/src/main/asciidoc/reference/diskstore.adoc b/src/main/asciidoc/reference/diskstore.adoc index 6e68d706..402097f8 100644 --- a/src/main/asciidoc/reference/diskstore.adoc +++ b/src/main/asciidoc/reference/diskstore.adoc @@ -1,14 +1,9 @@ [[bootstrap:diskstore]] = Configuring a DiskStore -As of Release 1.2.0, _Spring Data GemFire_ supports `DiskStore` configuration via the `disk-store` element. +_Spring Data Geode_ supports `DiskStore` configuration via the `disk-store` element. -NOTE: Prior to Release 1.2.0, `disk-store` was a child element of the `\*-region` elements. -If you have Regions configured with disk storage using a prior release of _Spring Data GemFire_ -and want to upgrade to the latest release, move all `disk-store` element(s) to the top-level, -assign an `id` and use the `*-region` element's `disk-store-ref` attribute. - -Also, `disk-synchronous` is now a `*-region` attribute. +For example: [source,xml] ---- @@ -19,8 +14,9 @@ Also, `disk-synchronous` is now a `*-region` attribute. ---- -`DiskStores` are used by Regions for file system persistent backup or overflow storage of evicted entries, -and persistent backup of WAN Gateways. Multiple components may share the same `DiskStore`. -Additionally, multiple directories may be defined for a single `DiskStore`. +`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 Pivotal GemFire's documentation for an explanation of the configuration options. +Please refer to Apache Geode's documentation for a complete explanation of the +http://geode.apache.org/docs/guide/11/developing/storing_data_on_disk/chapter_overview.html[configuration options]. diff --git a/src/main/asciidoc/reference/function-annotations.adoc b/src/main/asciidoc/reference/function-annotations.adoc index 7ac2cc32..661e9581 100644 --- a/src/main/asciidoc/reference/function-annotations.adoc +++ b/src/main/asciidoc/reference/function-annotations.adoc @@ -3,88 +3,105 @@ == Introduction -Spring Data GemFire 1.3.0 introduces annotation support to simplify working with -http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/function_exec/chapter_overview.html[GemFire Function Execution]. -The GemFire API provides classes to implement and register http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/Function.html[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. +_Spring Data Geode_ includes annotation support to simplify working with Geode +http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[Function Execution]. +Under-the-hood, the Apache Geode API provides classes to implement and register Geode +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] +that are deployed on Geode servers, which may then be invoked by other peer member applications +or remotely from cache clients. -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. +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. == Implementation vs Execution -There are two separate concerns to address. First is the Function implementation (server) which must interact with -the http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/FunctionContext.html[FunctionContext] -to obtain the invocation arguments, the http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/ResultSender.html[ResultsSender] -and other execution context information. The Function implementation typically accesses the Cache and or Region -and is typically registered with the http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/FunctionService.html[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 http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/Execution.html[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 http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/ResultCollector.html[ResultCollector] -to aggregate and acquire the execution results. In certain scenarios, a custom ResultCollector implementation -is required and may be registered with the Execution. +There are two separate concerns to address implementation and execution. -NOTE: 'Client' and 'Server' are used here in the context of Function execution which may have a different meaning -than client and server in a client-server Cache topology. While it is common for a member with a Client Cache -to invoke a Function on one or more Cache Server members it is also possible to execute Functions in a peer-to-peer -(P2P) configuration +First is Function implementation (server-side), which must interact with the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionContext.html[FunctionContext] +to access the invocation arguments, +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultSender.html[ResultsSender] +as well as other execution context information. The Function implementation typically accesses the Cache and/or Regions +and is registered with the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[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 +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Execution.html[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 +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[ResultCollector] +to aggregate and acquire the execution results. In certain cases, a custom `ResultCollector` implementation +is required and may be registered with the `Execution`. + +NOTE: 'Client' and 'Server' are used here in the context of Function execution, which may have a different meaning +than client and server in Geode's client-server topology. While it is common for an application using a `ClientCache` +to invoke a Function on one or more Geode servers in a cluster, it is also possible to execute Functions +in a peer-to-peer (P2P) configuration, where the application is a member of the cluster hosting a peer `Cache`. +Keep in mind that a peer member cache application is subject to all the same constraints of being a peer member +of the cluster. + +[[function-implementation]] == Implementing a Function -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 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 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. +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 -by the FunctionContext as an array: +in the `FunctionContext` as an array: -`Object[] args = new Object[]{"hello", 123}` +`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: +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: [source,java] ---- public Object method1(String s1, int i2) {...} -public Object method2(Map data, String s1, int i2) {...} -public Object method3(String s1, Mapdata, int i2) {...} -public Object method4(String s1, Map data, Set filter, int i2) {...} +public Object method2(Map data, String s1, int i2) {...} +public Object method3(String s1, Map data, int i2) {...} +public Object method4(String s1, Map data, Set filter, int i2) {...} public void method4(String s1, Set filter, int i2, Region data) {...} public void method5(String s1, ResultSender rs, int i2); -public void method6(FunctionContest fc); +public void method6(FunctionContest context); ---- 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 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. +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. === Annotations for Function Implementation -The following example illustrates how annotations are used to expose a POJO as a GemFire Function: +The following example illustrates how SDG's Function annotations are used to expose POJO methods +as GemFire Functions: [source,java] ---- @@ -92,10 +109,10 @@ The following example illustrates how annotations are used to expose a POJO as a public class ApplicationFunctions { @GemfireFunction - public String function1(String value, @RegionData Map data, int i2) { ... } + public String function1(String value, @RegionData Map data, int i2) { ... } - @GemfireFunction("myFunction", HA=true, optimizedForWrite=true, batchSize=100) - public List function2(String value, @RegionData Map data, int i2, @Filter Set keys) { ... } + @GemfireFunction("myFunction", batchSize=100, HA=true, optimizedForWrite=true) + public List function2(String value, @RegionData Map data, int i2, @Filter Set keys) { ... } @GemfireFunction(hasResult=true) public void functionWithContext(FunctionContext functionContext) { ... } @@ -103,178 +120,198 @@ public class ApplicationFunctions { } ---- -Note that the class itself must be registered as a Spring bean. Here the `@Component` annotation is used, but you may -register the bean by any method provided by Spring (e.g. XML configuration or Java configuration class). This allows -the Spring container to create an instance of this class and wrap it in a -https://github.com/spring-projects/spring-data-gemfire/blob/master/src/main/java/org/springframework/data/gemfire/function/PojoFunctionWrapper.java[PojoFunctionWrapper] (PFW). -Spring creates one PFW instance for each method annotated with `@GemfireFunction`. Each will all share the same -target object instance to invoke the corresponding method. +Note, the class itself must be registered as a _Spring_ bean and each Geode Function is annotated +with `@GemfireFunction`. In this example, _Spring's_ `@Component` annotation was used, but you may register the bean +by any method supported by _Spring_ (e.g. XML configuration or with a Java configuration class using _Spring Boot_). +This allows the _Spring_ container to create an instance of this class and wrap it in a +http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/PojoFunctionWrapper.html[PojoFunctionWrapper]. +_Spring_ creates a wrapper instance for each method annotated with `@GemfireFunction`. Each wrapper instance shares +the same target object instance to invoke the corresponding method. -NOTE: The fact that the Function class is a Spring bean may offer other benefits since it shares the ApplicationContext -with GemFire components such as a Cache and Regions. These may be injected into the class if necessary. +TIP: The fact that the POJO Function class is a _Spring_ bean may offer other benefits since it shares +the `ApplicationContext` with Geode components such as the Cache and Regions. These may be injected into the class +if necessary. -Spring creates the wrapper class and registers the Function with GemFire's Function Service. The Function id used -to register the Functions must be unique. By convention it defaults to the simple (unqualified) method name. Note that -this annotation also provides configuration attributes, `HA` and `optimizedForWrite` which correspond to properties -defined by GemFire's Function interface. If the method's return type is void, then the `hasResult` property -is automatically set to `false`; otherwise it is set to `true`. +_Spring_ creates the wrapper class and registers the Function(s) with Geode's Function Service. The Function id used +to register the Functions must be unique. Using convention it defaults to the simple (unqualified) method name. +The name can be explicitly defined using the `id` attribute of the `@GemfireFunction` annotation. +The `@GemfireFunction` annotation also provides other configuration attributes, `HA` and `optimizedForWrite`, +which correspond to properties defined by Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Function] interface. +If the method's return type is void, then the `hasResult` property is automatically set to `false`; +otherwise, if the method returns a value the `hasResult` attributes is set to `true`. -For `void` return types, the annotation provides a `hasResult` attribute that can be set to true to override -this convention, as shown in the `functionWithContext` method above. Presumably, the intention is to use the -ResultSender directly to send results to the caller. +Even for `void` return types, the annotation's `hasResult` attribute can be set to `true` to override this convention, +as shown in the `functionWithContext` method above. Presumably, the intention is to use the `ResultSender` directly +to send results to the caller. -The PFW implements GemFire's Function interface, binds the method parameters, and invokes the target method in -its `execute()` method. It also sends the method's return value using the ResultSender. +The `PojoFunctionWrapper` implements Geode's `Function` interface, binds method parameters and invokes the target method +in its `execute()` method. It also sends the method's return value using the `ResultSender`. -==== Batching Results +=== Batching Results -If the return type is a Collection or Array, then some consideration must be given to how the results are returned. -By default, the PFW returns the entire Collection at once. If the number of items is large, this may incur -a performance penalty. To divide the payload into small sections (sometimes called chunking), you can set -the `batchSize` attribute, as illustrated in `function2`, above. +If the return type is an array or Collection, then some consideration must be given to how the results are returned. +By default, the `PojoFunctionWrapper` returns the entire array or Collection at once. If the number of elements +in the array or Collection quite is large, it may incur a performance penalty. To divide the payload into smaller, +more maneable chunks, you can set the `batchSize` attribute, as illustrated in `function2`, above. -NOTE: If you need more control of the ResultSender, especially if the method itself would use too much memory -to create the Collection, you can pass the ResultSender, or access it via the FunctionContext, to use it directly -within the method. +TIP: If you need more control of the `ResultSender`, especially if the method itself would use too much memory +to create the Collection, you can pass the `ResultSender`, or access it via the `FunctionContext` and use it directly +within the method to sends results back to the caller. -==== Enabling Annotation Processing +=== Enabling Annotation Processing -In accordance with Spring standards, you must explicitly activate annotation processing for @GemfireFunction using XML: +In accordance with _Spring_ standards, you must explicitly activate annotation processing for `@GemfireFunction` +annotations. + +Using XML: [source,xml] ---- ---- -or by annotating a Java configuration class: +Or by annotating a Java configuration class: [source,java] ---- +@Configuration @EnableGemfireFunctions +class ApplicationConfiguration { .. } ---- [[function-execution]] == Executing a Function -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. +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. === Annotations for Function Execution -To support client-side Function execution, the following annotations are provided: `@OnRegion`, `@OnServer`, -`@OnServers`, `@OnMember`, `@OnMembers`. These correspond to the Execution implementations GemFire's FunctionService -provides. Each annotation exposes the appropriate attributes. These annotations also provide an optional -`resultCollector` attribute whose value is the name of a Spring bean implementing -http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/ResultCollector.html[ResultCollector] +To support client-side Function execution, the following SDG Function annotations are provided: `@OnRegion`, +`@OnServer`, `@OnServers`, `@OnMember`, `@OnMembers`. These annotations correspond to the `Execution` implementations +prodided by Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[FunctionService]. +Each annotation exposes the appropriate attributes. These annotations also provide an optional +`resultCollector` attribute whose value is the name of a _Spring_ bean implementing the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[ResultCollector] to use for the execution. -NOTE: The proxy interface binds all declared methods to the same execution configuration. Although it is expected +CAUTION: The proxy interface binds all declared methods to the same execution configuration. Although, it is expected that single method interfaces will be common, all methods in the interface are backed by the same proxy instance and therefore all share the same configuration. -Here are some examples: +Here are a few examples: [source,java] ---- -@OnRegion(region="someRegion", resultCollector="myCollector") +@OnRegion(region="SomeRegion", resultCollector="myCollector") public interface FunctionExecution { - @FunctionId("function1") - String doIt(String s1, int i2); + @FunctionId("function1") + String doIt(String s1, int i2); - String getString(Object arg1, @Filter Set keys) ; + String getString(Object arg1, @Filter Set keys); } ---- -By default, the Function id is the simple (unqualified) method name. `@FunctionId` is used to bind this invocation -to a different Function id. +By default, the Function ID is the simple (unqualified) method name. The `@FunctionId` annotation can be used +to bind this invocation to a different Function ID. -==== Enabling Annotation Processing +=== Enabling Annotation Processing -The client-side uses Spring's component scanning capability to discover annotated interfaces. To enable -Function execution annotation processing, you can use XML: +The client-side uses _Spring's_ classpath component scanning capability to discover annotated interfaces. To enable +Function execution annotation processing in XML: [source,xml] ---- - + ---- -Note that the `function-executions` element is provided in the `gfe-data` namespace. The `base-package` attribute -is required to avoid scanning the entire classpath. Additional filters are provided as described in the Spring -http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-scanning-filters[reference]. +The `function-executions` element is provided in the `gfe-data` namespace. The `base-package` attribute is required +to avoid scanning the entire classpath. Additional filters are provided as described in the _Spring_ +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-scanning-filters[reference documentation]. Optionally, a developer can annotate her Java configuration class: [source,java] ---- -@EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.functions") +@EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.geode.functions") ---- +[[function-execution-programmatic]] == Programmatic Function Execution -Using the annotated interface as described in the previous section, simply wire your interface into a bean -that will invoke the Function: +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: [source,java] ---- @Component - public class MyApp { +public class MyApplication { - @Autowired FunctionExecution functionExecution; + @Autowired + FunctionExecution functionExecution; public void doSomething() { functionExecution.doIt("hello", 123); } - } ---- -Alternately, you can use a Function Execution template directly. For example `GemfireOnRegionFunctionTemplate` creates -an `onRegion` Function execution. For example: +Alternately, you can use a Function execution template directly. For example, `GemfireOnRegionFunctionTemplate` +creates an `onRegion` Function `Execution`. +.Using the `GemfireOnRegionFunctionTemplate` +==== [source,java] ---- -Set myFilter = getFilter(); -Region myRegion = getRegion(); +Set myFilter = getFilter(); +Region myRegion = getRegion(); GemfireOnRegionOperations template = new GemfireOnRegionFunctionTemplate(myRegion); -String result = template.executeAndExtract("someFunction",myFilter,"hello","world",1234); +String result = template.executeAndExtract("someFunction", myFilter, "hello", "world", 1234); ---- +==== -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. +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`. +[[function-execution-pdx]] == Function Execution with PDX -When using Spring Data GemFire's Function annotation support combined with GemFire's http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/data_serialization/gemfire_pdx_serialization.html[PDX serialization], +When using _Spring Data Geode's_ Function annotation support combined with Apache Geode's +http://geode.apache.org/docs/guide/11/developing/data_serialization/gemfire_pdx_serialization.html[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 http://docs.spring.io/spring-data-gemfire/docs/1.6.0.M1/api/org/springframework/data/gemfire/function/annotation/package-frame.html[Function annotations] -as so... +As explained above, and by way of example, typically developers will define Geode Functions using POJO classes +annotated with Spring Data Geode +http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[Function annotations] +like so... [source,java] ---- public class OrderFunctions { @GemfireFunction(...) - Order process(@RegionData data, Order order, OrderSource orderSourceEnum, Integer count); + Order process(@RegionData data, Order order, OrderSource orderSourceEnum, Integer count) { ... } } ---- -NOTE: the Integer count parameter is an arbitrary argument as is the separation of the Order and OrderSource Enum, +NOTE: The Integer type, count parameter is arbitrary as is the separation of the `Order` class and `OrderSource` Enum, which might be logical to combine. However, the arguments were setup this way to demonstrate the problem with Function executions in the context of PDX. -Your Order and OrderSource enum might be as follows... +Your `Order` and `OrderSource` enum might be as follows... [source,java] ---- @@ -297,7 +334,7 @@ public enum OrderSource { } ---- -Of course, a developer may define a Function Execution interface to call the 'process' GemFire Server Function... +Of course, a developer may define a Function `Execution` interface to call the 'process' Geode Server Function... [source,java] ---- @@ -307,75 +344,93 @@ public interface OrderProcessingFunctions { } ---- -Clearly, this `process(..)` Order Function is being called from a client-side, 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. +Clearly, this `process(..)` `Order` Function is being called from a client-side with a `ClientCache` +(i.e. ``) based application. This implies that the Function arguments must also be serializable. +The same is true when invoking peer-to-peer member Functions (e.g. `@OnMember(s)) between peers in the cluster. +Any form of `distribution` requires the data transmitted between client and server, or peers, to be serialized. -Now, if the developer has configured GemFire to use PDX for serialization (instead of Java serialization, for instance) -it is common for developers to set the `read-serialized` attribute to *true* on the GemFire server(s)... +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)... -`` +[source,xml] +---- + +---- -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. +Or from a Geode cache client application... -GemFire will only serialize application domain object types that you have specifically configured (registered), -either using GemFire's http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/data_serialization/auto_serialization.html[ReflectionBasedAutoSerializer], -or specifically (and recommended) using a "custom" GemFire http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/data_serialization/use_pdx_serializer.html[PdxSerializer] -for your application domain types. +[source,xml] +---- + +---- -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`. +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. -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. +Geode will only serialize application domain object types that you have specifically configured (registered), +with either Geode's +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer], +or specifically (and recommended) using a "custom" Geode +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[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_ +http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[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... [source,java] ---- - orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400); +orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400); ---- -But, in actuality, what GemFire executes the Function on the Server is... +But, what the Geode Function on the Server gets is... [source,java] ---- - process(regionData, order:PdxInstance, :PdxInstanceEnum, 400); +process(regionData, order:PdxInstance, :PdxInstanceEnum, 400); ---- -Notice that the `Order` and `OrderSource` have passed to the Function as http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/pdx/PdxInstance.html[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). +The `Order` and `OrderSource` have been passed to the Function as +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxInstance.html[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 GemFire's, "strongly-typed", Function annotated POJO class method signatures, -as the developer is expecting application domain object types (not PDX serialized objects). +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, 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". +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 GemFire `PdxSerializer` on the GemFire Servers -where the SDG annotated POJO Function is registered and used, e.g. ... +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. ... [source,java] ---- - - + ---- -Alternatively, a developer my use GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer]. -Of course, it is recommend to use a "custom" `PdxSerializer` where possible to maintain finer grained control over your -serialization strategy. +Alternatively, a developer my use Geode's +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer] +for convenience. Of course, it is recommended that you use a "custom" `PdxSerializer` where possible to maintain +finer grained control over your serialization strategy. -Finally, Spring Data GemFire is careful not to convert your Function arguments if you really want to treat your -Function arguments generically, or as one of GemFire's PDX types... +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... [source,java] ---- @@ -385,10 +440,9 @@ public Object genericFunction(String value, Object domainObject, PdxInstanceEnum } ---- -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. +_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 GemFire `PdxSerializers` as well as appropriate -POJO Function parameter type handling based on the method signature, see Spring Data GemFire's -https://github.com/spring-projects/spring-data-gemfire/blob/master/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[ClientCacheFunctionExecutionWithPdxIntegrationTest] class. +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 +https://github.com/spring-projects/spring-data-gemfire/blob/1.0.0.APACHE-GEODE-INCUBATING-RELEASE/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[ClientCacheFunctionExecutionWithPdxIntegrationTest] class. diff --git a/src/main/asciidoc/reference/function.adoc b/src/main/asciidoc/reference/function.adoc index 33ef3b12..d43a2762 100644 --- a/src/main/asciidoc/reference/function.adoc +++ b/src/main/asciidoc/reference/function.adoc @@ -1,17 +1,29 @@ [[bootstrap:function]] = Configuring the Function Service -As of Release 1.3.0, Spring Data GemFire provides <> support for implementing and registering functions. Spring Data GemFire also provides namespace support for registering GemFire http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/execute/Function.html[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 `org.apache.geode.cache.execute.Function` interface or extend `org.apache.geode.cache.execute.FunctionAdapter`. The namespace uses a familiar pattern to declare functions: +_Spring Data Geode_ provides <> support for implementing and registering +Apache Geode Functions. + +_Spring Data Geode_ also provides namespace support for registering Apache Geode +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] +for remote Function execution. + +Please refer to Apache Geode' http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[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: [source,xml] ---- - + - + ---- - diff --git a/src/main/asciidoc/reference/gateway.adoc b/src/main/asciidoc/reference/gateway.adoc index 00ccb51f..1eaefe6d 100644 --- a/src/main/asciidoc/reference/gateway.adoc +++ b/src/main/asciidoc/reference/gateway.adoc @@ -1,91 +1,65 @@ [[bootstrap:gateway]] = Configuring WAN Gateways -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: +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. == WAN Configuration in GemFire 7.0 -GemFire 7.0 introduces new APIs for WAN configuration. While the original APIs provided in GemFire 6 are still supported, it is recommended that you use the new APIs if you are using GemFire 7.0. The Spring Data GemFire namespace supports either. In the example below, `GatewaySender`s are configured for a partitioned region by adding child elements to the region (`gateway-sender` and `gateway-sender-ref`). The `GatewaySender` may register `EventFilter`s and `TransportFilters`. Also shown below is an example configuration of an `AsyncEventQueue` which must also be wired into a region (not shown). +In the example below, `GatewaySenders` are configured for a PARTITION Region by adding child elements to the Region +(`gateway-sender` and `gateway-sender-ref`). + +A `GatewaySender` may register `EventFilters` and `TransportFilters`. Also shown below is an example configuration +of an `AsyncEventQueue` which must also be wired into a Region (not shown). [source,xml] ---- - - - - - - - - + + + + + + + + + maximum-queue-memory="50"> - + - - - + + - - - + + + ---- -On the other end of a `GatewaySender` is a corresponding `GatewayReceiver` to receive gateway events. The `GatewayReceiver` may also be configured with `EventFilter`s and `TransportFilter`s. +On the other end of a `GatewaySender` is a corresponding `GatewayReceiver` to receive Gateway events. +The `GatewayReceiver` may also be configured with `EventFilters` and `TransportFilters`. [source,xml] ---- - - - - + + + + ---- -Please refer to the GemFire product document for a detailed explanation of all the configuration options. - -== WAN Configuration in GemFire 6.6 - -[source,xml] ----- - - - - - - - - - - - - - - - - - ----- - -A region may synchronize all or part of its contents to a gateway hub used to access one or more remote systems. The region must set `enable-gateway` to `true` and specify the `hub-id`. - -NOTE: If just a hub-id is specified, Spring Data GemFire automatically assumes that the gateway should be enabled. - -Please refer to the GemFire product document for a detailed explanation of all the configuration options. - +Please refer to the Apache Geode +http://geode.apache.org/docs/guide/11/topologies_and_comm/multi_site_configuration/chapter_overview.html[documentation] +for a detailed explanation of all the configuration options. diff --git a/src/main/asciidoc/reference/gemfire-bootstrap.adoc b/src/main/asciidoc/reference/gemfire-bootstrap.adoc index 97b21260..aaccaea8 100644 --- a/src/main/asciidoc/reference/gemfire-bootstrap.adoc +++ b/src/main/asciidoc/reference/gemfire-bootstrap.adoc @@ -1,78 +1,132 @@ [[gemfire-bootstrap]] -= Bootstrapping a Spring ApplicationContext in GemFire += Bootstrapping a Spring ApplicationContext in Apache Geode == Introduction -Normally, a Spring-based application will <> using Spring Data GemFire's XML namespace. Just by specifying a `` 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. +Normally, a _Spring_-based application will <> using _Spring Data Geode's. +Just by specifying a `` 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, 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 http://gemfire.docs.pivotal.io/docs-gemfire/latest/tools_modules/gfsh/chapter_overview.html[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. +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 +http://geode.apache.org/docs/guide/11/tools_modules/gfsh/chapter_overview.html[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 GemFire is not an application server. In addition, there are limitations to using this approach where GemFire Cache configuration is concerned. +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. -== Using GemFire to Bootstrap a Spring Context Started with Gfsh +[[gemfire-bootstrap-gfsh]] +== Using Apache Geode to Bootstrap a Spring Context Started with Gfsh -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 http://gemfire.docs.pivotal.io/docs-gemfire/latest/basic_config/the_cache/setting_cache_initializer.html[Initalizer] functionality. An *Initializer* can be used to specify a callback application that is launched after the Cache is initialized by GemFire. +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 +http://geode.apache.org/docs/guide/11/basic_config/the_cache/setting_cache_initializer.html[Initalizer] functionality. +An Initializer block can declare a callback application that is launched after the cache is initialized by Geode. -An *Initializer* is specified within an http://gemfire.docs.pivotal.io/docs-gemfire/latest/reference/topics/cache_xml.html#initializer[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. ``) +An Initializer is declared within an +http://geode.apache.org/docs/guide/11/reference/topics/cache_xml.html#initializer[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. ``) -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: +Fortunately, such an Initializer is already conveniently provided by the framework, the +http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/support/SpringContextBootstrappingInitializer.html[SpringContextBootstrappingInitializer]. +A typical, yet very minimal configuration for this class inside Geodes's `cache.xml` file will look like this: [source,xml] ---- - - + + - org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer classpath:application-context.xml + ---- -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: +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: [source,xml] ---- - - + + - org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer org.mycompany.myapp.services,org.mycompany.myapp.dao,... + ---- -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: +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: [source] ---- gfsh>start server --name=Server1 --log-level=config ... - --classpath="/path/to/spring-data-gemfire-1.4.0.jar:/path/to/application/classes.jar" - --cache-xml-file="/path/to/gemfire/cache.xml" + --classpath="/path/to/application/classes.jar:/path/to/spring-data-geode-...RELEASE.jar" + --cache-xml-file="/path/to/geode/cache.xml" ---- -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 `` 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. +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 `` 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. + +[[gemfire-bootstrap-lazywiring]] == Lazy-Wiring GemFire Components -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 <>. 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. +_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 <>. However, this only works +when _Spring_ is the one doing the bootstrapping (i.e. bootstrapping Geode). -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. +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. -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: +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: [source,java] ---- -public static final class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport implements CacheLoader { +public class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport + implements CacheLoader { @Autowired private DataSource userDataSource; @@ -81,30 +135,41 @@ public static final class UserDataSourceCacheLoader extends LazyWiringDeclarable } ---- -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): +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. + +CAUTION: Be careful when mixing the different life-cycles of Apache Geode and the _Spring_ Container together +in this manner as not all use cases and scenarios are supported. The Geode `cache.xml` configuration would be +similar to the following (which comes from SDG's test suite): [source,xml] ---- - - + + - java.lang.String org.springframework.data.gemfire.repository.sample.User - org.springframework.data.gemfire.support.SpringContextBootstrappingInitializerIntegrationTest$UserDataStoreCacheLoader + + org.springframework.data.gemfire.support.SpringContextBootstrappingInitializerIntegrationTest$UserDataStoreCacheLoader + + org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer org.springframework.data.gemfire.support.sample + ---- - diff --git a/src/main/asciidoc/reference/indexing.adoc b/src/main/asciidoc/reference/indexing.adoc index 2071036d..6447c169 100644 --- a/src/main/asciidoc/reference/indexing.adoc +++ b/src/main/asciidoc/reference/indexing.adoc @@ -1,25 +1,25 @@ [[bootstrap:indexing]] -= Creating an Index += Configuring an Index -Pivotal GemFire allows Indexes (or Indices) to be created to improve the performance of OQL queries. +Apache Geode allows Indexes (or Indices) to be created to improve the performance of OQL queries. -In _Spring Data GemFire_, Indices can be declared with the `index` element: +In _Spring Data Geode_, Indexes are declared with the `index` element: [source,xml] ---- - + ---- -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 using the new bean definition, -regardless if the old `Index` definition was the same or not. +Before creating the `Index`, _Spring Data Geode_ will verify whether an `Index` with the same name already exists. +By default, SDG overrides an existing `Index` if an `Index` with the same name already exists. The existing Index +is overridden by removing the old `Index` first followed by creating a new `Index` with the same name defined by +the new bean definition, regardless if the old `Index` definition was the same or not. To prevent the named `Index` definition change, especially when the old and new `Index` definitions differ -in a significant way, then set the `override` attribute to `false`, which effectively returns the existing +in a significant way, then set the `override` attribute to *false*, which effectively returns the existing `Index` definition given the same name. `Index` declarations are not bound to a Region but rather are top-level elements (just like `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 +- an improvement over Geode'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 XML schema for a full set of options. diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc index b17dd29b..f9d56c55 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -1,26 +1,24 @@ [[ref-introduction]] = Document Structure -The following chapters explain the core functionality offered by Spring Data GemFire for Pivotal GemFire. - -This reference guide is equally applicable to Spring Data Geode for Apache Geode. +The following chapters explain the core functionality offered by _Spring Data Geode_ for Apache Geode. <> describes the configuration support provided for bootstrapping, configuring, initializing -and accessing GemFire Caches, Cache Servers, Regions, and related Distributed System components. +and accessing Apache Geode Caches, Regions, and related Distributed System components. -<> explains the integration between the GemFire APIs and the various data access features available in Spring, -such as transaction management and exception translation. +<> explains the integration between the Apache Geode APIs and the various data access features +available in _Spring_, such as transaction management and exception translation. -<> describes the enhancements for GemFire (de)serialization and management of associated objects. +<> describes the enhancements for Apache Geode (de)serialization and management of associated objects. -<> describes persistence mapping for POJOs stored in GemFire or Geode using Spring Data. +<> describes persistence mapping for POJOs stored in Apache Geode using _Spring Data_. -<> describes how to create and use GemFire Repositories using Spring Data. +<> describes how to create and use _Spring Data Repositories_ to access data in Apache Geode. -<> describes how to create and use GemFire Functions using annotations. +<> describes how to create and use Apache Geode Functions using Annotations. -<> describes how to bootstrap a Spring ApplicationContext running in a GemFire or Geode Server -using Gfsh. +<> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Apache Geode server +using _Gfsh_. -<> describes the samples provided with the distribution to illustrate the various features -available in Spring Data GemFire and/or Spring Data Geode. +<> describes the examples provided with the distribution to illustrate the various features +available in _Spring Data Geode_. diff --git a/src/main/asciidoc/reference/lucene.adoc b/src/main/asciidoc/reference/lucene.adoc index 4344241e..2967fce2 100644 --- a/src/main/asciidoc/reference/lucene.adoc +++ b/src/main/asciidoc/reference/lucene.adoc @@ -81,7 +81,7 @@ to stick to strongly-typed objects. Now that we have a `LuceneIndex` we can perform Lucene based data access operations, such as queries. -#### Lucene Template Data Accessors +== Lucene Template Data Accessors _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. @@ -233,7 +233,7 @@ that uses https://github.com/cglib/cglib[CGLIB] to generate proxy classes as the A custom `ProjectionFactory` can be set on a Lucene template using `setProjectionFactory(:ProjectionFactory)`. -#### Annotation configuration support +== Annotation configuration support 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 diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 421d54db..02c6680c 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -4,9 +4,10 @@ [[mapping.entities]] == Entity Mapping -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: +_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: -.Mapping a domain class to a GemFire Region +.Mapping a domain class to a Geode Region ==== [source,java] ---- @@ -14,6 +15,7 @@ Spring Data GemFire provides support to map entities that will be stored in a Ge public class Person { @Id Long id; + String firstname; String lastname; @@ -27,9 +29,16 @@ public class Person { ---- ==== -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. +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 GemFire Sub-Regions, as so: +In addition to storing entities in top-level Regions, entities can be stored in Sub-Regions as well. + +For instance: [source,java] ---- @@ -44,11 +53,39 @@ public class Guest extends User { } ---- -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. +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. -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 <> for more details. +[[mapping.entities.region]] +=== Entity Mapping by Region Type -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: +In addition to the `@Region` annotation, _Spring Data Geode_ also recognizes the Region type-specific +mapping annotations: `@ClientRegion`, `@LocalRegion`, `@PartitionRegion` and `@ReplicateRegion`. + +Functionally, these annotations are treated exactly the same as the generic `@Region` annotation in the SDG +mapping infrastructure. However, these additional mapping annotations are useful in _Spring Data Geode's` +Annotation configuration model. When combined with the `@EnableEntityDefinedRegions` configuration annotation +on _Spring_ `@Configuration` annotated class, it is possible to generate Regions in the local cache, whether +the application is a client or peer. + +These annotations allow you, the developer, to be more specific about what type of Region that your application +entity class should be mapped to, and also has an impact on the data management policies of the Region +(e.g. partition (a.k.a. sharding) vs. just replicating data). + +Using these Region type-specific mapping annotations with the SDG Annotation config model saves you from having to +explicitly define these Regions in config. + +The details of the new Annotation configuration model will be discussed in more detail in a subsequent releaase. + +[[mapping.repositories]] +=== Repository Mapping + +As an 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`. +See <> for more details. + +However, let's say you want to store a `Person` in multiple Geode Regions (e.g. `People` and `Customers`), +then you can define your corresponding `Repository` interface extensions like so: [source,java] ---- @@ -63,10 +100,40 @@ public interface CustomerRepository extends GemfireRepository { } ---- +Then, using each Repository individually, you can store the entity in multiple Geode Regions. + +[source,java] +---- +@Service +class CustomerService { + + CustomerRepository customerRepo; + + PersonRepository personRepo; + + Customer update(Customer customer) { + customerRepo.save(customer); + personRepo.save(customer); + return customer; + } +---- + +It is not difficult to imagine wrapping the `update` service method in a _Spring_ managed transaction, +either as a local cache transaction or a global transaction. + [[mapping.pdx-serializer]] == Mapping PDX Serializer -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. +_Spring Data Geode_ provides a custom +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxSerializer.html[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 http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxReader.html[PdxReader]. .Using @Value on entity constructor parameters ==== @@ -77,10 +144,9 @@ public class Person { public Person(@Value("#root.foo") String firstname, @Value("bean") String lastname) { // … } - } ---- ==== -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`. - +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`. diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index 60065511..c15defc1 100644 --- a/src/main/asciidoc/reference/region.adoc +++ b/src/main/asciidoc/reference/region.adoc @@ -1,97 +1,115 @@ [[bootstrap:region]] -= Configuring a GemFire Region += Configuring a Region -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. +A Region is required to store and retrieve data from the cache. `org.apache.geode.cache.Region` is an interface +extending `java.util.Map` and enables basic data access using familiar key-value semantics. The `Region` interface +is wired into application classes that require it so the actual Region type is decoupled from the programming model. +Typically, each Region is associated with one domain object, similar to a table in a relational database. -GemFire implements the following types of regions: +Geode implements the following types of Regions: -* *Replicated* - Data is replicated across all cache members that define the region. This provides very high read performance but writes take longer to perform the replication. -* *Partioned* - Data is partitioned into buckets among cache members that define the region. This provides high read and write performance and is suitable for very large data sets that are too big for a single node. -* *Local* - Data only exists on the local node. -* *Client* - Technically a client region is a local region that acts as a proxy to a replicated or partitioned region hosted on cache servers. It may hold data created or fetched locally. Alternately, it can be empty. Local updates are synchronized to the cache server. Also, a client region may subscribe to events in order to stay synchronized with changes originating from remote processes that access the same region. +* *REPLICATE* - Data is replicated across all cache members that define the Region. This provides very high +read performance but writes take longer to perform the replication. +* *PARTITION* - Data is partitioned into buckets (sharded) among cache members that define the Region. This provides +high read and write performance and is suitable for large data sets that are too big for a single node. +* *LOCAL* - Data only exists on the local node. +* *Client* - Technically, a client Region is a LOCAL Region that acts as a PROXY to a REPLICATE or PARTITION Region +hosted on cache servers in a cluster. It may hold data created or fetched locally. Alternately, it can be empty. +Local updates are synchronized to the cache server. Also, a client Region may subscribe to events in order to +stay up-to-date (synchronized) with changes originating from remote processes that access the same server Region. -For more information about the various region types and their capabilities as well as configuration options, please refer to the GemFire Developer's http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/book_intro.html[Guide] and community http://www.pivotal.io/big-data/pivotal-gemfire[site]. +For more information about the various Region types and their capabilities as well as configuration options, +please refer to Apache Geode's documentation on +http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. [[bootstrap:region:lookup]] == Using an externally configured Region -For referencing Regions already configured through GemFire `cache.xml` file, use the `lookup-region` element. Simply declare the target Region name with the`name` attribute; -for example, to declare a bean definition named `region-bean` for an existing region named `Orders` one can use the following bean definition: +To reference Regions already configured in a Geode native `cache.xml` file, use the `lookup-region` element. +Simply declare the target Region name with the `name` attribute. For example, to declare a bean definition identified +as `ordersRegion` for an existing Region named `Orders`, you can use the following bean definition: [source,xml] ---- - + ---- -If the `name` is not specified, the bean's `id` will be used. The example above becomes: +If `name` is not specified, the bean's `id` will be used as the name of the Region. +The example above becomes: [source,xml] ---- - + ---- -NOTE: If the Region does not exist, an initialization exception will be thrown. For configuring new GemFire Regions, proceed to the appropriate sections below. +CAUTION: If the Region does not exist, an initialization exception will be thrown. To configure new Regions, +proceed to the appropriate sections below. -Note, in the previous examples, since no cache name was defined, the default naming convention (`gemfireCache`) was used. Alternately, one can reference the cache bean through the `cache-ref` attribute: +In the previous examples, since no cache name was explicitly defined, the default naming convention (`gemfireCache`) +was used. Alternately, one can reference the cache bean with the `cache-ref` attribute: [source,xml] ---- - - + + ---- -`lookup-region` provides a simple way of retrieving existing, pre-configured Regions without exposing the Region semantics or setup infrastructure. +`lookup-region` provides a simple way of retrieving existing, pre-configured Regions without exposing +the Region semantics or setup infrastructure. -[[bootstrap:region:auto-lookup]] +[[bootstrap:region:lookup:auto]] == Auto Region Lookup -New, as of Spring Data GemFire 1.5, is the ability to "auto-lookup" all Regions defined in GemFire's native cache.xml file, and imported into Spring config -using the`cache-xml-location` attribute on the `` element in the GFE XML namespace. +"auto-lookup" allows all Regions defined in a Geode native `cache.xml` file to be imported into a _Spring_ +application context when using the`cache-xml-location` attribute on the `` element. -For instance, given a GemFire `cache.xml` file of... +For instance, given a `cache.xml` file of... [source,xml] ---- - - - - - - + + + + + + + ---- -A user may import the `cache.xml` file as follows... +A developer may import the `cache.xml` file as follows... [source,xml] ---- ---- -A user can then use the `` element (e.g. ``) to reference specific -GemFire Regions as beans in the Spring context, or the user may choose to import all GemFire Regions defined -in `cache.xml` with the new... +The developer may then use the `` element (e.g. ``) to reference +specific Regions as beans in the _Spring_ context, or the user may choose to import all Regions defined in `cache.xml` +with: [source,xml] ---- ---- -Spring Data GemFire will automatically create Spring beans referencing all GemFire Regions defined in `cache.xml` -that have not been explicitly added to the Spring context with `` bean declarations. +_Spring Data Geode_ will automatically create beans for all Geode Regions defined in `cache.xml` that have not been +explicitly added to the _Spring_ context with explicit `` bean declarations. -It is important to realize that Spring Data GemFire uses a Spring http://docs.spring.io/spring/docs/4.0.7.RELEASE/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor] -to post process the Cache after it is both created and initialized to determine the Regions defined in GemFire to add -as beans in the Spring context. +It is important to realize that _Spring Data Geode_ uses a _Spring_ +http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor] +to post process the cache after it is both created and initialized to determine the Regions defined in Geode to add +as beans in the _Spring_ application context. -You may inject these "auto-looked-up" Regions like any other bean defined in the Spring context with 1 exception; you -may need to define a `depends-on` association with the '`gemfireCache`' bean as follows... +You may inject these "auto-looked-up" Regions like any other bean defined in the _Spring_ application context with +1 exception; you may need to define a `depends-on` association with the '`gemfireCache`' bean as follows... [source,java] ---- - package example; import ... @@ -100,44 +118,45 @@ import ... @DependsOn("gemfireCache") public class ApplicationDao extends DaoSupport { - @Resource(name = "Parent") - private Region parent; + @Resource(name = "Parent") + private Region parent; - @Resource(name = "/Parent/Child") - private Region child; + @Resource(name = "/Parent/Child") + private Region child; - ... + ... } ---- -The above Java example is applicable when using the Spring context's `component-scan` functionality. +The example above is applicable when using _Spring's_ `component-scan` functionality. -If you are declaring your components using Spring XML, then you would do... +If you are declaring your components using _Spring_ XML config, then you would do... [source,xml] ---- ---- -This ensures the GemFire Cache and all the Regions defined in `cache.xml` get created before any components +This ensures the Geode cache and all the Regions defined in `cache.xml` get created before any components with auto-wire references when using the new `` element. [[bootstrap:region:overview]] == Configuring Regions -Spring Data GemFire provides comprehensive support for configuring any type of GemFire Region via the following elements: +_Spring Data Geode_ provides comprehensive support for configuring any type of Region via the following elements: -* Local Region `` -* Replicated Region `` -* Partitioned Region `` -* Client Region `` +* LOCAL Region: `` +* PARTITION Region: `` +* REPLICATE Region: `` +* Client Region: `` -For a comprehensive description of http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/region_options/region_types.html[Region types] please consult the GemFire product documentation. +Please see the Apache Geode documentation for a comprehensive description of +http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. -[[bootstrap:region:common:attributes]] +[[bootstrap:region:attributes]] === Common Region Attributes -The following table(s) list attributes available for various region types: +The following table lists attributes available for all Region types: [cols="1,2,2", options="header"] .Common Region Attributes @@ -147,192 +166,244 @@ The following table(s) list attributes available for various region types: | Description | cache-ref -| *GemFire Cache bean name* -| The name of the bean defining the GemFire Cache (by default 'gemfireCache'). - -| close -| *boolean, default:false (Note: The default was true prior to 1.3.0)* -| Indicates whether the Region should be closed at shutdown. +| Geode Cache bean reference +| The name of the bean defining the Geode Cache (by default 'gemfireCache'). | cloning-enabled -| *boolean, default:false* +| boolean, default:false | When true, the updates are applied to a clone of the value and then the clone is saved to the cache. When false, the value is modified in place in the cache. +| close +| boolean, default:false +| Determines whether the Region should be closed at shutdown. + | concurrency-checks-enabled -| *boolean, default:true* +| boolean, default:true | Determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed Regions. | data-policy -| *See GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/821/javadocs/japi/index.html[Data Policy]* +| See Geode's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Data Policy] | The Region's Data Policy. Note, not all Data Policies are supported for every Region type. | destroy -| *boolean, default:false* -| Indicates whether the Region should be destroyed at shutdown. +| boolean, default:false +| Determines whether the Region should be destroyed at shutdown. | disk-store-ref -| *The name of a configured Disk Store.* +| The name of a configured Disk Store. | A reference to a bean created via the `disk-store` element. | disk-synchronous -| *boolean, default:true* -| Indicates whether Disk Store writes are synchronous. - -| enable-gateway -| *boolean, default:false* -| Indicates whether the Region will synchronize entries over a WAN Gateway. - -| hub-id -| *The name of the Gateway Hub.* -| This will automatically set enable-gateway to true. If enable-gateway is explicitly set to false, an exception will be thrown. +| boolean, default:true +| Determines whether Disk Store writes are synchronous. | id -| *Any valid bean name.* -| Will also be the Region name by default. +| Any valid bean name. +| Will be the Region name by default if no `name` attribute is specified. | ignore-if-exists -| *boolean, default:false* -| Ignores this bean definition configuration if the Region already exists in the GemFire Cache, resulting in a lookup instead. +| boolean, default:false +| Ignores this bean definition if the Region already exists in the cache, resulting in a lookup instead. | ignore-jta -| *boolean, default:false* -| Indicates whether the Region participates in JTA transactions. +| boolean, default:false +| Determines whether this Region will participate in JTA transactions. | index-update-type -| *synchronous or asynchronous, default:synchronous* -| Indicates whether indices will be updated synchronously or asynchronously on entry creation. +| synchronous or asynchronous, default:synchronous +| Determines whether Indices will be updated synchronously or asynchronously on entry creation. | initial-capacity -| *integer, default:16* -| The initial memory allocation for number of Region entries. +| integer, default:16 +| The initial memory allocation for the number of Region entries. | key-constraint -| *Any valid, fully-qualified Java class name.* -| The expected key type. +| Any valid, fully-qualified Java class name. +| Expected key type. | load-factor -| *float, default:.75* +| float, default:.75 | Sets the initial parameters on the underlying java.util.ConcurrentHashMap used for storing Region entries. | name -| *Any valid Region name.* -| The name of the Region definition. If not specified, it will assume the value of the id attribute (the bean name). +| Any valid Region name. +| The name of the Region. If not specified, it will assume the value of the `id` attribute (a.k.a. bean name). | persistent -| *boolean, default:false* -| Indicates whether the Region persists entries to a Disk Store (disk). +| *boolean, default:false +| Determines whether the Region will persist entries to local disk (Disk Store). -| shorcut -| *See http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/RegionShortcut.html -| The RegionShortcut for this Region. Allows easy initialization of the region based on pre-defined defaults. +| shortcut +| See http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/RegionShortcut.html +| The `RegionShortcut` for this Region. Allows easy initialization of the Region based on pre-defined defaults. | statistics -| *boolean, default:false* -| Indicates whether the Region reports statistics. +| boolean, default:false +| Determines whether the Region reports statistics. | template -| *The name of a Region Template.* +| The name of a Region Template. | A reference to a bean created via one of the `*region-template` elements. | value-constraint -| *Any valid, fully-qualified Java class name.* -| The expected value type. +| Any valid, fully-qualified Java class name. +| Expected value type. |=== -[[bootstrap:region:common:cache-listener]] -=== Cache Listeners +[[bootstrap:region:cache-listener]] +=== CacheListeners -`CacheListeners` are registered with a Region to handle Region events such as entries being created, updated, destroyed, -etc. A `CacheListener` can be any bean that implements the http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/CacheListener.html[`CacheListener`] interface. -A Region may have multiple listeners, declared using the `cache-listener` element enclosed in a `*-region` element. +`CacheListeners` are registered with a Region to handle Region events such as when entries are created, updated, +destroyed and so on. A `CacheListener` can be any bean that implements the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheListener.html[`CacheListener`] interface. +A Region may have multiple listeners, declared using the `cache-listener` element nested in the containing +`*-region` element. -In the example below, there are two `CacheListener's` declared. The first references a top-level named Spring bean; +In the example below, there are two `CacheListener's` declared. The first references a named, top-level _Spring_ bean; the second is an anonymous inner bean definition. [source,xml] ---- - - - - - - - + + + + + + + - + ---- -The following example uses an alternate form of the `cache-listener` element with a `ref` attribute. This allows for -more concise configuration for a single cache listener. Note that the namespace only allows a single `cache-listener` -element so either the style above or below must be used. +The following example uses an alternate form of the `cache-listener` element with the `ref` attribute. +This allows for more concise configuration when defining a single `CacheListener`. Note, the namespace only allows +a single `cache-listener` element so either the style above or below must be used. -WARNING: Using `ref` and a nested declaration in a `cache-listener`, or similar element, is illegal. The two options -are mutually exclusive and using both on the same element will result in an exception. +WARNING: Using `ref` and a nested declaration in the `cache-listener` element is illegal. The two options are +mutually exclusive and using both in the same element will result in an exception. [source,xml] ---- - - - - - - + + + + + ---- .Bean Reference Conventions [NOTE] ==== -The `cache-listener` element is an example of a common pattern used in the namespace anywhere GemFire provides +The `cache-listener` element is an example of a common pattern used in the namespace anywhere Geode provides a callback interface to be implemented in order to invoke custom code in response to Cache or Region events. -Using Spring's IoC container, the implementation is a standard Spring bean. In order to simplify the configuration, +Using _Spring's_ IoC container, the implementation is a standard _Spring_ bean. In order to simplify the configuration, the schema allows a single occurrence of the `cache-listener` element, but it may contain nested bean references and inner bean definitions in any combination if multiple instances are permitted. The convention is to use the singular form (i.e., `cache-listener` vs `cache-listeners`) reflecting that the most common scenario will in fact -be a single instance. We have already seen examples of this pattern in the <> configuration example. +be a single instance. We have already seen examples of this pattern in the <> +configuration example. ==== -[[bootstrap:region:common:loaders-writers]] -=== Cache Loaders and Cache Writers +[[bootstrap:region:cache-loaders-writers]] +=== CacheLoaders and CacheWriters Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register -these respective components for a Region. A `CacheLoader` is invoked on a cache miss to allow an entry to be loaded -from an external data source, a database for example. A `CacheWriter` is invoked before an entry is created or updated, -intended for synchronizing to an external data source. The difference is GemFire only supports at most a single instance -of each for each Region. However, either declaration style may be used. +these Geode components respectively for a Region. -See http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/CacheLoader.html[`CacheLoader`] and http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/CacheWriter.html[`CacheWriter`] for more details. +A `CacheLoader` is invoked on a cache miss to allow an entry to be loaded from an external data source, such as a +database. A `CacheWriter` is invoked before an entry is created or updated, intended for synchronizing to +an external data source. The difference is Geode only supports at most a single instance `CacheLoader` and `CacheWriter` +per Region. However, either declaration style may be used. -[[bootstrap:region:common:subregions]] -=== Subregions +Example: -In Release 1.2.0, Spring Data GemFire added support for subregions, allowing regions to be arranged in a hierarchical relationship. For example, GemFire allows for a */Customer/Address* region and a different */Employee/Address* region. Additionally, a subregion may have it's own subregions and its own configuration. A subregion does not inherit attributes from the parent region. Regions types may be mixed and matched subject to GemFire constraints. A subregion is naturally declared as a child element of a region. The subregion's name attribute is the simple name. The above example might be configured as: [source,nonxml] +[source,xml] ---- + + + + + + - - - - - - - + + + + ---- -Note that the `Monospaced ([id])` attribute is not permitted for a subregion. The subregions will be created with bean names */Customer/Address* and */Employee/Address*, respectively. So they may be injected using the full path name into other beans that use them, such as `GemfireTemplate`. The full path should also be used in OQL query strings. +See http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheLoader.html[`CacheLoader`] +and http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheWriter.html[`CacheWriter`] +in the Apache Geode documentation for more details. -[[bootstrap:region:common:region-templates]] +[[bootstrap:region:compression]] +== Compression + +Geode Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid +stop the world GCs. When you enable compression for a Region, all values stored in the Region, in-memory +are compressed while keys and indexes remain uncompressed. New values are compressed when put into Region +and all values are decompressed automatically when read back from the Region. Values are not compressed when +persisted to disk or when sent over the wire to other peer members or clients. + +Example: + +[source,xml] +---- + + + + + + + +---- + +Please refer to Apache Geode's documentation for more information on +http://gemfire.docs.pivotal.io/geode/managing/region_compression/region_compression.html[Region Compression]. + +[[bootstrap:region:subregions]] +== Subregions + +_Spring Data Geode_ also supports Subregions, allowing Regions to be arranged in a hierarchical relationship. + +For example, Geode allows for a */Customer/Address* Region and a different */Employee/Address* Region. Additionally, +a Subregion may have it's own Subregions and its own configuration. A Subregion does not inherit attributes from +the parent Region. Regions types may be mixed and matched subject to Geode constraints. A Subregion is naturally +declared as a child element of a Region. The Subregion's name attribute is the simple name. The above example +might be configured as: + +[source,xml] +---- + + + + + + + + + +---- + +Note that the `Monospaced ([id])` attribute is not permitted for a Subregion. The Subregions will be created with +bean names */Customer/Address* and */Employee/Address*, respectively. So they may be injected using the full path name +into other application beans that need them, such as `GemfireTemplate`. The full path should also be used in +OQL query strings. + +[[bootstrap:region:templates]] == Region Templates -Also new as of Spring Data GemFire 1.5 is Region Templates. This feature allows developers to define common Region +_Spring Data Geode_ also supports Region Templates. This feature allows developers to define common Region configuration settings and attributes once and reuse the configuration among many Region bean definitions declared -in the Spring context. +in the _Spring_ application context. -Spring Data GemFire introduces 5 new tags to the SDG XML namespace (XSD): +_Spring Data Geode_ includes 5 Region template tags in namespace: [cols="1,2", options="header"] .Region Template Tags @@ -341,145 +412,134 @@ Spring Data GemFire introduces 5 new tags to the SDG XML namespace (XSD): | Description | `` -| Defines common, generic Region attributes; extends `regionType` in the SDG 1.5 XSD +| Defines common, generic Region attributes; extends `regionType` in the namespace. | `` -| Defines common, 'Local' Region attributes; extends `localRegionType` in the SDG 1.5 XSD +| Defines common, 'Local' Region attributes; extends `localRegionType` in the namespace. | `` -| Defines common, 'PARTITION' Region attributes; extends `partitionedRegionType` in the SDG 1.5 XSD +| Defines common, 'PARTITION' Region attributes; extends `partitionedRegionType` in the namespace. | `` -| Defines common, 'REPLICATE' Region attributes; extends `replicatedRegionType` in the SDG 1.5 XSD +| Defines common, 'REPLICATE' Region attributes; extends `replicatedRegionType` in the namespace. | `` -| Defines common, 'Client' Region attributes; extends `clientRegionType` in the SDG 1.5 XSD +| Defines common, 'Client' Region attributes; extends `clientRegionType` in the namespace. |=== -In addition to the new tags, `` elements along with the `` elements have -a `template` attribute used to define the Region Template from which to inherit the Region configuration. Even -Region templates may inherit from other Region Templates. +In addition to the tags, concrete `` elements along with the abstract `` elements +have a `template` attribute used to define the Region Template from which the Region will inherit its configuration. +Region Templates may even inherit from other Region Templates. Here is an example of 1 possible configuration... [source,xml] ---- - - - - - + + + + + + - - - - - - - - + + + + + + + + - - - - - - - - - - + + + + + + + + + - - - - - - + + + + + + - - - - - - - - - - + + ---- -Region Templates will even work for Subregions. Notice that 'TemplateBasedPartitionRegion' extends 'PartitionRegionTemplate' -which extends 'ExtendedRegionTemplate' which extends 'BaseRegionTemplate'. Attributes and sub-elements defined in -subsequent, inherited Region bean definitions override what is in the parent. +Region Templates work for Subregions as well. Notice that 'TemplateBasedPartitionRegion' +extends 'PartitionRegionTemplate', which extends 'ExtendedRegionTemplate' that extends 'BaseRegionTemplate'. +Attributes and sub-elements defined in subsequent, inherited Region bean definitions override what is in the parent. -=== Under-the-hood... +=== How Templating Works -Spring Data GemFire applies Region Templates when the Spring application context configuration meta-data is *parsed*, -and therefore, must be declared in the order of inheritance, in other words, parent templates before children. This -ensures the proper configuration is applied, especially when element attributes or sub-elements are "overridden". +_Spring Data Geode_ applies Region Templates when the _Spring_ application context configuration meta-data is *parsed*, +and therefore, *must be declared in the order of inheritance*. In other words, parent templates must be defined +before children. This ensures the proper configuration is applied, especially when element attributes or sub-elements +are "overridden". IMPORTANT: It is equally important to remember the Region types must only inherit from other similar typed Regions. For instance, it is not possible for a `` to inherit from a ``. NOTE: Region Templates are single-inheritance. -[[bootstrap:region:common:regions-subregions-lookups-caution]] -== A Word of Caution on Regions, Subregions and Lookups +[[bootstrap:region:regions-subregions-lookups-caution]] +=== Caution concerning Regions, Subregions and Lookups -Prior to Spring Data GemFire 1.4, one of the underlying properties of the high-level `replicated-region`, -`partitioned-region`, `local-region` and `client-region` elements in Spring Data GemFire's XML namespace, -which correspond to GemFire's Region types based on Data Policy, is that these elements perform a lookup first -before attempting to create the region. This is done in case the region already exists, which might be the case -if the region was defined in GemFire's native configuration, e.g. `cache.xml`, thereby avoiding any errors. -This was by design, though subject to change. +Previously, one of the underlying properties of the `replicated-region`, `partitioned-region`, `local-region` +and `client-region` elements in the _Spring Data Geode_ XML namespace was to perform a lookup first before +attempting to create a Region. This was done in case the Region already existed, which would be the case +if the Region was defined in an imported Geode native `cache.xml` configuration file. Therefore, the lookup +was performed first to avoid any errors. This was by design and subject to change. -WARNING: The Spring team highly recommends that the `replicated-region`, `partitioned-region`, `local-region` -and `client-region` elements be strictly used only for defining new regions. One of the problems with these elements -doing a lookup first is, if the developer assumed that defining a bean definition for a REPLICATE region would create -a new region, however, consequently a region with the same name already exists having different semantics for -eviction, expiration, subscription and/or other attributes, this could adversely affect application logic -and/or expectations thereby violating application requirements. +This behavior has been altered and the default behavior is now to create the Region first. If the Region +already exists, then the creation logic fails-fast and an appropriate exception is thrown. However, much like the +`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the _Spring Data Geode_ `<*-region>` namespace elements now includes +a `ignore-if-exists` attribute, which re-instates the old behavior by performing a lookup of an existing Region +identified by name, first. If an existing Region by name is found and `ignore-if-exists` is set to `true`, then +the Region bean definition defined in _Spring_ config is ignored. -IMPORTANT: Recommended Practice - Only use the `replicated-region`, `partitioned-region`, `local-region` -and `client-region` XML namespace elements for defining new regions. +WARNING: The _Spring_ team highly recommends that the `replicated-region`, `partitioned-region`, `local-region` +and `client-region` namespace elements be strictly used for defining new Regions only. One problem that could arise +if the Regions defined by these elements already existed and the Region elements performed a lookup first is if +the developer defined different Region semantics and behaviors for eviction, expiration, subscription, etc in his/her +application config, then the Region definition may not match and could exhibit contrary behaviors to those required +by the application. Even worse, the application developer may want to define the Region as a distributed Region +(e.g. PARTITION) but in fact the existing Region definition is LOCAL. -However, because the high-level region elements perform a lookup first, this can cause problems for -dependency injected region resources to application code, like DAOs or Repositories. +IMPORTANT: Recommended Practice - Only use `replicated-region`, `partitioned-region`, `local-region` and `client-region` +namespace elements to define new Regions. -Take for instance the following native GemFire configuration file (e.g. `cachel.xml`)... +Consider the following native Geode `cache.xml` configuration file... [source,xml] ---- - - - - - - - - + + + + + + + + + ---- -Also, consider that you might have defined a DAO as follows... +Also consider that you may have defined an application DAO as follows... [source,java] ---- @@ -492,54 +552,69 @@ public class CustomerAccountDao extends GemDaoSupport { } ---- -Here, we are injecting a reference to the `Customers/Accounts` GemFire Region in our DAO. As such, it is not uncommon for a developer to define beans for all or some of these regions in Spring XML configuration meta-data as follows... +Here, we are injecting a reference to the `Customers/Accounts` Region in our application DAO. As such, it is +not uncommon for a developer to define beans for all or even some of these Regions in _Spring_ XML configuration +meta-data as follows... [source,xml] ---- + xmlns:gfe="http://www.springframework.org/schema/gemfire" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd +"> - + + + + - - ---- -Here the `Customers/Accounts` and `Customers/Accounts/Orders` GemFire Regions are referenced as beans in the Spring context as "Customers/Accounts" and "Customers/Accounts/Orders", respectively. The nice thing about using the `lookup-region` element and the corresponding syntax above is that it allows a developer to reference a subregion directly without unnecessarily defining a bean for the parent region (e.g. `Customers`). +The `Customers/Accounts` and `Customers/Accounts/Orders` Regions are referenced as beans in the _Spring_ +application context as "Customers/Accounts" and "Customers/Accounts/Orders", respectively. The nice thing about +using the `lookup-region` element and the corresponding syntax above is that it allows a developer +to reference a Subregion directly without unnecessarily defining a bean for the parent Region (i.e. `Customers`). However, if now the developer changes his/her configuration meta-data syntax to using the nested format, like so... [source,xml] ---- - - - + + + ---- -Or, perhaps the developer erroneously chooses to use the high-level `replicated-region` element, which will do a lookup first, as in... +Or, perhaps the developer erroneously chooses to use the top-level `replicated-region` element along with +the `ignore-if-exists` attribute set to perform a lookup first, as in... [source,xml] ---- - - - - + + + + ---- -Then the region beans defined in the Spring context will consist of the following: `{ "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }.` This means the dependency injected reference (i.e. `@Resource(name = "Customers/Accounts"))` is now broken since no bean with name "Customers/Accounts" is defined. +Then the Region beans defined in the _Spring_ application context will consist of the following: +`{ "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }.` This means the dependency injected reference +above (i.e. `@Resource(name = "Customers/Accounts"))` is now broken since no bean with name "Customers/Accounts" +is actually defined. -GemFire is flexible in referencing both parent regions and subregions. The parent can be referenced as "/Customers" or "Customers" and the child as "/Customers/Accounts" or just "Customers/Accounts". However, Spring Data GemFire is very specific when it comes to naming beans after regions, typically always using the forward slash (/) to represents subregions (e.g. "/Customers/Accounts"). +Geode is flexible in referencing both parent Regions and Subregions with or without the leading forward slash. +For example, the parent can be referenced as "/Customers" or "Customers" and the child as "/Customers/Accounts" +or just "Customers/Accounts". However, _Spring Data _Geode is very specific when it comes to naming beans after Regions, +typically always using the forward slash (/) to represent Subregions (e.g. "/Customers/Accounts"). -Therefore, it is recommended that users use either the nested `lookup-region` syntax as illustrated above, or define direct references with a leading forward slash (/) like so... +Therefore, it is recommended that users either use the nested `lookup-region` syntax as shown above, +or define direct references with a leading forward slash (/) like so... [source,xml] ---- @@ -547,122 +622,100 @@ Therefore, it is recommended that users use either the nested `lookup-region` sy ---- -The example above where the nested `replicated-region` elements were used to reference the subregions serves to illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? Not, since the regions were defined in native GemFire configuration (i.e. `cache.xml`) and will exist by the time the cache is initialized, or once the `` bean is created. Since the high-level region XML namespace abstractions, like `replicated-region`, perform the lookup first, it uses the regions as defined in the `cache.xml` configuration file. - -[[bootstrap:region:persistence]] -== Data Persistence - -Regions can be made persistent. GemFire ensures that all the data you put into a region that is configured for persistence will be written to disk in a way that it can be recovered the next time you create the region. This allows data to be recovered after a machine or process failure or after an orderly shutdown and restart of GemFire. - -To enable persistence with Spring Data GemFire, simply set the `persistent` attribute to true: - -[source,xml] ----- - ----- - -IMPORTANT: Persistence for partitioned regions is supported from GemFire 6.5 onwards - configuring this option on a previous release will trigger an initialization exception. - -Persistence may also be configured using the `data-policy` attribute, set to one of http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/DataPolicy.html[GemFire's data policy settings]. For instance... - -[source,xml] ----- - ----- - -The data policy must match the region type and must also agree with the `persistent` attribute if explicitly set. An initialization exception will be thrown if, for instance, the `persistent` attribute is set to false, yet a persistent data policy was specified. - -When persisting regions, it is recommended to configure the storage through the `disk-store` element for maximum efficiency. The diskstore is referenced using the disk-store-ref attribute. Additionally, the region may perform disk writes synchronously or asynchronously: - -[source,xml] ----- - ----- - -This is discussed further in <> - -[[bootstrap:region:subscription]] -== Subscription Interest Policy - -GemFire allows configuration of subscriptions to control http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/events/configure_p2p_event_messaging.html[peer to peer event handling]. Spring Data GemFire provides a `` to set the interest policy on replicated and partitioned regions to either `ALL` or `CACHE_CONTENT`. - -[source,xml] ----- - - - ----- +The example above where the nested `replicated-region` elements were used to reference the Subregions serves to +illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? +Not, since the Regions were defined in the native Geode `cache.xml` configuration file as `REPLICATES` and will exist +by the time the cache is initialized, or once the `` bean is processed. [[bootstrap:region:eviction]] -== Data Eviction and Overflowing +== Data Eviction (with Overflow) -Based on various constraints, each region can have an eviction policy in place for evicting data from memory. -Currently, in GemFire, eviction applies to the least recently used entry (also known as +Based on various constraints, each Region can have an eviction policy in place for evicting data from memory. +Currently, in Geode, eviction applies to the _Least Recently Used_ entry (also known as http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used[LRU]). Evicted entries are either destroyed -or paged to disk (also known as *overflow*). +or paged to disk (referred to as *overflow* to disk). -Spring Data GemFire supports all eviction policies (entry count, memory and heap usage) for both `partitioned-region` -and `replicated-region` as well as `client-region`, through the nested `eviction` element. For example, to configure -a partition to overflow to disk if its size is more then 512 MB, one could use the following configuration: +_Spring Data Geode_ supports all eviction policies (entry count, memory and heap usage) for PARTITION Regions, +REPLICATE Regions and client, local Regions using the nested `eviction` element. + +For example, to configure a PARTITION Region to overflow to disk if the memory size exceeds more than 512 MB, +a developer would specify the following configuration: [source,xml] ---- - - + + ---- -IMPORTANT: Replicas cannot use a `local destroy` eviction since that would invalidate them. See the GemFire docs -for more information. +IMPORTANT: Replicas cannot use `local destroy` eviction since that would invalidate them. +See the Geode docs for more information. -When configuring regions for overflow, it is recommended to configure the storage through the `disk-store` element +When configuring Regions for overflow, it is recommended to configure the storage through the `disk-store` element for maximum efficiency. -For a detailed description of eviction policies, see the GemFire documentation (such as -http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/eviction/how_eviction_works.html[this] page). +For a detailed description of eviction policies, please refer to the Geode documentation on +http://geode.apache.org/docs/guide/11/developing/eviction/chapter_overview.html[Eviction]. [[bootstrap:region:expiration]] == Data Expiration -GemFire allows you to control how long entries exist in the cache. Expiration is driven by elapsed time, as opposed to -Eviction, which is driven by memory usage. Once an entry expires it may no longer be accessed from the cache. +Apache Geode allows you to control how long entries exist in the cache. Expiration is driven by elapsed time, +as opposed to Eviction, which is driven by the entry count or heap/memory usage. Once an entry expires +it may no longer be accessed from the cache. -GemFire supports the following Expiration types: +Geode supports the following Expiration types: -* *Time-to-Live (TTL)* - The amount of time, in seconds, the object may remain in the cache after the last creation +* *Time-to-Live (TTL)* - The amount of time in seconds that an object may remain in the cache after the last creation or update. For entries, the counter is set to zero for create and put operations. Region counters are reset when the Region is created and when an entry has its counter reset. -* *Idle Timeout (TTI)* - The amount of time, in seconds, the object may remain in the cache after the last access. -The Idle Timeout counter for an object is reset any time its TTL counter is reset. In addition, an entry’s Idle Timeout -counter is reset any time the entry is accessed through a get operation or a netSearch . The Idle Timeout counter for a -Region is reset whenever the Idle Timeout is reset for one of its entries. +* *Idle Timeout (TTI)* - The amount of time in seconds that an object may remain in the cache after the last access. +The Idle Timeout counter for an object is reset any time its TTL counter is reset. In addition, an entry’s +_Idle Timeout_ counter is reset any time the entry is accessed through a get operation or a netSearch. +The _Idle Timeout_ counter for a Region is reset whenever the _Idle Timeout_ is reset for one of its entries. -Each of these may be applied to the Region itself or entries in the Region. Spring Data GemFire provides ``, +Each of these may be applied to the Region itself or entries in the Region. _Spring Data Geode_ provides ``, ``, `` and `` Region child elements to specify timeout values and expiration actions. -[[bootstrap:region:expiration:annotation]] -== Annotation-based Data Expiration +For example: -As of Spring Data GemFire 1.7, a developer now has the ability to define Expiration policies and settings on individual +[source,xml] +---- + + + + +---- + +For a detailed description of expiration policies, please refer to the Geode documentation on +http://geode.apache.org/docs/guide/11/developing/expiration/chapter_overview.html[Expiration]. + +[[bootstrap:region:expiration:annotation]] +=== Annotation-based Data Expiration + +With _Spring Data Geode_, a developer has the ability to define Expiration policies and settings on individual Region Entry values, or rather, application domain objects directly. For instance, a developer might define Expiration settings on a Session-based application domain object like so... [source,java] ---- @Expiration(timeout = "1800", action = "INVALIDATE") -public static class SessionBasedApplicationDomainObject { +public class SessionBasedApplicationDomainObject { + ... } ---- -In addition, a developer may also specify Expiration type specific settings on Region Entries using `@IdleTimeoutExpiration` -and `@TimeToLiveExpiration` for Idle Timeout (TTI) and Time-to-Live (TTL) Expiration, respectively... +In addition, a developer may also specify Expiration type specific settings on Region Entries using +`@IdleTimeoutExpiration` and `@TimeToLiveExpiration` annotations for Idle Timeout (TTI) and Time-to-Live (TTL) +Expiration, respectively... [source,java] ---- @TimeToLiveExpiration(timeout = "3600", action = "LOCAL_DESTROY") @IdleTimeoutExpiration(timeout = "1800", action = "LOCAL_INVALIDATE") @Expiration(timeout = "1800", action = "INVALIDATE") -public static class AnotherSessionBasedApplicationDomainObject { +public class AnotherSessionBasedApplicationDomainObject { + ... } ---- @@ -674,8 +727,8 @@ Expiration types, such as TTL and TTI, are configured. [NOTE] ==== All @Expiration-based annotations apply only to Region Entry values. Expiration for a "Region" is not covered -by Spring Data GemFire's Expiration annotation support. However, GemFire and Spring Data GemFire do allow you to set -Region Expiration using the SDG XML namespace, like so... +by _Spring Data Geode's_ Expiration annotation support. However, Apache Geode and _Spring Data Geode_ do allow you +to set Region Expiration using the SDG XML namespace, like so... [source,xml] ---- @@ -686,20 +739,22 @@ Region Expiration using the SDG XML namespace, like so... ---- ==== -Spring Data GemFire's @Expiration annotation support is implemented with GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/CustomExpiry.html[`CustomExpiry`] interface. -See http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/expiration/configuring_data_expiration.html[GemFire's User Guide] for more details +_Spring Data Geode's_ `@Expiration` annotation support is implemented with Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface. +Refer to Geode's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[Configuring Data Expiration] +for more details -The Spring Data GemFire `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is specifically responsible -for processing the SDG @Expiration annotations and applying the Expiration policy and settings appropriately +The _Spring Data Geode_ `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible +for processing the SDG `@Expiration` annotations and applying the Expiration policy and settings appropriately for Region Entry Expiration on request. -To use Spring Data GemFire to configure specific GemFire Regions to appropriately apply the Expiration policy -and settings applied to your application domain objects annotated with @Expiration-based annotations, you must... +To use _Spring Data Geode_ to configure specific Geode Regions to appropriately apply the Expiration policy +and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must... -1. Define a Spring bean in the Spring ApplicationContext of type `AnnotationBasedExpiration` using the appropriate +1. Define a bean in the _Spring_ `ApplicationContext` of type `AnnotationBasedExpiration` using the appropriate constructor or one of the convenient factory methods. When configuring Expiration for a specific Expiration type, -such as Idle Timeout or Time-to-Live, then you should use one of the factory methods of the `AnnotationBasedExpiration` -class, like so... +such as _Idle Timeout_ or _Time-to-Live_, then you should use one of the factory methods in the +`AnnotationBasedExpiration` class, like so... + [source,xml] ---- @@ -713,18 +768,18 @@ class, like so... + [NOTE] ==== -To configure Idle Timeout (TTI) Expiration instead, then you would of course use the `forIdleTimeout` factory method +To configure _Idle Timeout_ (TTI) Expiration instead, then you would of course use the `forIdleTimeout` factory method along with the `` element to set TTI. ==== 2. (optional) Annotate your application domain objects that will be stored in the Region with Expiration policies -and custom settings using one of Spring Data GemFire's @Expiration annotations: `@Expiration`, `@IdleTimeoutExpiration` -and/or `@TimeToLiveExpiration` +and custom settings using one of _Spring Data Geode's_ `@Expiration` annotations: `@Expiration`, +`@IdleTimeoutExpiration` and/or `@TimeToLiveExpiration` -3. (optional) In cases where particular application domain objects have not been annotated with Spring Data GemFire's -@Expiration annotations at all, but the GemFire Region is configured to use SDG's custom `AnnotationBasedExpiration` class -to determine the Expiration policy and settings for objects stored in the Region, then it is possible to set "default" -Expiration attributes on the `AnnotationBasedExpiration` bean by doing the following... +3. (optional) In cases where particular application domain objects have not been annotated with _Spring Data Geode's_ +`@Expiration` annotations at all, but the Geode Region is configured to use SDG's custom `AnnotationBasedExpiration` +class to determine the Expiration policy and settings for objects stored in the Region, then it is possible to set +"default" Expiration attributes on the `AnnotationBasedExpiration` bean by doing the following... [source,xml] ---- @@ -743,31 +798,32 @@ Expiration attributes on the `AnnotationBasedExpiration` bean by doing the follo ---- -You may have noticed that the Spring Data GemFire's @Expiration annotations use String as the attributes type, rather -than and perhaps more appropriately being strongly typed, i.e. `int` for 'timeout' and SDG'S `ExpirationActionType` +You may have noticed that _Spring Data Geode's_ `@Expiration` annotations use a String as the attributes type rather +than, and perhaps more appropriately, being strongly typed, i.e. `int` for 'timeout' and SDG'S `ExpirationActionType` for 'action'. Why is that? -Well, enter one of Spring Data GemFire's other features, leveraging Spring's core infrastructure -for configuration convenience: Property Placeholders and Spring Expression Language (SpEL). +Well, enter one of _Spring Data Geode's_ other features, leveraging _Spring's_ core infrastructure +for configuration convenience: _Property Placeholders_ and _Spring Expression Language_ (SpEL). -For instance, a developer can specify both the Expiration 'timeout' and 'action' using Property Placeholders -in the @Expiration annotation attributes... +For instance, a developer can specify both the Expiration 'timeout' and 'action' using _Property Placeholders_ +in the `@Expiration` annotation attributes... [source,java] ---- -@TimeToLiveExpiration(timeout = "${gemfire.region.entry.expiration.ttl.timeout}" - action = "${gemfire.region.entry.expiration.ttl.action}") +@TimeToLiveExpiration(timeout = "${geode.region.entry.expiration.ttl.timeout}" + action = "${geode.region.entry.expiration.ttl.action}") public class ExampleApplicationDomainObject { + ... } ---- -Then, in your Spring context XML or in JavaConfig, you would declare the following beans... +Then, in your _Spring_ XML config or in JavaConfig, you would declare the following beans... [source,xml] ---- - 600 - INVALIDATE + 600 + INVALIDATE ... @@ -778,16 +834,16 @@ This is both convenient when multiple application domain objects might share sim or when you wish to externalize the configuration. However, a developer may want more dynamic Expiration configuration determined by the state of the running system. -This is where the power of SpEL comes in and is the recommended approach. Not only can you refer to beans -in the Spring context and access bean properties, invoke methods, etc, the values for Expiration 'timeout' and 'action' -can be strongly typed. For example (building on the example above)... +This is where the power of SpEL comes in and is the recommended approach, actually. Not only can you refer to beans +in the _Spring_ context and access bean properties, invoke methods, etc, the values for Expiration 'timeout' +and 'action' can be strongly typed. For example (building on the example above)... [source,xml] ---- - 600 - #{T(org.springframework.data.gemfire.expiration.ExpirationActionType).DESTROY} - #{T(org.apache.geode.cache.ExpirationAction).INVALIDATE} + 600 + #{T(org.springframework.data.gemfire.expiration.ExpirationActionType).DESTROY} + #{T(org.apache.geode.cache.ExpirationAction).INVALIDATE} ... @@ -798,187 +854,377 @@ Then, on your application domain object... [source,java] ---- -@TimeToLiveExpiration(timeout = "@expirationSettings['gemfire.region.entry.expiration.ttl.timeout']" - action = "@expirationSetting['gemfire.region.entry.expiration.ttl.action']") +@TimeToLiveExpiration(timeout = "@expirationSettings['geode.region.entry.expiration.ttl.timeout']" + action = "@expirationSetting['geode.region.entry.expiration.ttl.action']") public class ExampleApplicationDomainObject { + ... } ---- You can imagine that the 'expirationSettings' bean could be a more interesting and useful object rather than a simple -instance of `java.util.Properties`. In this example, even the Properties ('expirationSettings') using using SpEL -to based the action value on the actual Expiration action enumerated types leading to more quickly identified failures +instance of `java.util.Properties`. In this example, even the Properties (`expirationSettings`) uses SpEL to base +the action value on the actual Expiration action enumerated type leading to more quickly identified failures if the types ever change. -All of this has been demonstrated and tested in the Spring Data GemFire test suite, by way of example. See the -https://github.com/spring-projects/spring-data-gemfire[source] for further details. +All of this has been demonstrated and tested in the _Spring Data Geode_ test suite, by way of example. See the +https://github.com/spring-projects/spring-data-geode[source] for further details. + +[[bootstrap:region:persistence]] +== Data Persistence + +Regions can be persistent. Geode ensures that all the data you put into a Region that is configured for persistence +will be written to disk in a way that is recoverable the next time you recreate the Region. This allows data +to be recovered after machine or process failure, or even after an orderly shutdown and subsequent restart of +the Geode data node. + +To enable persistence with _Spring Data Geode_, simply set the `persistent` attribute to `true` on +any of the `<*-region>` elements. For example... + +[source,xml] +---- + +---- + +Persistence may also be configured using the `data-policy` attribute; set the attribute's value to one of +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Geode's DataPolicy settings]. +For example... + +[source,xml] +---- + +---- + +The `DataPolicy` must match the Region type and must also agree with the `persistent` attribute if also explicitly set. +An initialization exception will be thrown if the `persistent` attribute is set to `false` yet a persistent `DataPolicy` +was specified (e.g. PERSISTENT_REPLICATE, PERSISTENT_PARTITION). + +When persisting Regions, it is recommended to configure the storage through the `disk-store` element +for maximum efficiency. The DiskStore is referenced using the `disk-store-ref` attribute. Additionally, the Region +may perform disk writes synchronously or asynchronously: + +[source,xml] +---- + +---- + +This is discussed further in <> + +[[bootstrap:region:subscription]] +== Subscription Policy + +Geode allows configuration of http://geode.apache.org/docs/guide/11/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging] +to control the entry events that the Region will receive. _Spring Data Geode_ provides the `` +sub-element to set the subscription policy on REPLICATE and PARTITION Regions to either `ALL` or `CACHE_CONTENT`. + +[source,xml] +---- + + + +---- [[bootstrap:region:local]] == Local Region -Spring Data GemFire offers a dedicated `local-region` element for creating local regions. Local regions, as the name -implies, are standalone meaning they do not share data with any other distributed system member. Other than that, -all common region configuration options are supported. A minimal declaration looks as follows (again, the example -relies on the Spring Data GemFire namespace naming conventions to wire the cache): +_Spring Data Geode_ offers a dedicated `local-region` element for creating local Regions. Local Regions, as the name +implies, are standalone, meaning they do not share data with any other distributed system member. Other than that, +all common Region configuration options apply. + +A minimal declaration looks as follows (again, the example relies on the _Spring Data Geode_ namespace +naming conventions to wire the cache): [source,xml] ---- - + ---- -Here, a local region is created (if one doesn't exist already). The name of the region is the same as the bean id -(myLocalRegion) and the bean assumes the existence of a GemFire cache named `gemfireCache`. +Here, a local Region is created (if one doesn't exist already). The name of the Region is the same as the bean id +(`myLocalRegion`) and the bean assumes the existence of a Geode cache named `gemfireCache`. [[bootstrap:region:replicate]] == Replicated Region -One of the common region types is a *replicated region* or *replica*. In short, when a region is configured to be -a replicated region, every member that hosts that region stores a copy of the region's entries locally. Any update to -a replicated region is distributed to all copies of the region. When a replica is created, it goes through -an initialization stage in which it discovers other replicas and automatically copies all the entries. While one replica -is initializing you can still continue to use the other replica. +One of the common Region types is a *REPLICATE* Region or *replica*. In short, when a Region is configured to be +a REPLICATE, every member that hosts the Region stores a copy of the Region's entries locally. Any update to +a REPLICATE Region is distributed to all copies of the Region. When a _replica_ is created, it goes through +an initialization stage in which it discovers other _replicas_ and automatically copies all the entries. +While one _replica_ is initializing you can still continue to use the other _replica_. -Spring Data GemFire offers a `replicated-region` element. A minimal declaration looks as follows. -All common configuration options are available for replicated regions. +_Spring Data Geode_ offers a `replicated-region` element. A minimal declaration looks as follows. +All common configuration options are available for REPLICATE Regions. [source,xml] ---- - + ---- +Refer to Geode's documentation on +http://geode.apache.org/docs/guide/11/developing/distributed_regions/chapter_overview.html[Distributed and Replicated Regions] +for more details. + [[bootstrap:region:partition]] == Partitioned Region -Another region type supported out of the box by the Spring Data GemFire namespace is the partitioned region. To quote the GemFire docs: +Another Region type supported out-of-the-box by the _Spring Data Geode_ namespace is the PARTITION Region. -"A partitioned region is a region where data is divided between peer servers hosting the region so that each peer stores a subset of the data. When using a partitioned region, applications are presented with a logical view of the region that looks like a single map containing all of the data in the region. Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of the operation. [...] GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster." +To quote the Geode docs: -A partition is created using the `partitioned-region` element. Its configuration options are similar to that of the `replicated-region` plus the partion specific features such as the number of redundant copies, total maximum memory, number of buckets, partition resolver and so on. Below is a quick example on setting up a partition region with 2 redundant copies: +"A partitioned region is a region where data is divided between peer servers hosting the region so that +each peer stores a subset of the data. When using a partitioned region, applications are presented with +a logical view of the region that looks like a single map containing all of the data in the region. +Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of +the operation. Geode divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, +but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster." + +A partition is created using the `partitioned-region` element. Its configuration options are similar to that of +the `replicated-region` plus the partition specific features such as the number of redundant copies, +total maximum memory, number of buckets, partition resolver and so on. + +Below is a quick example on setting up a PARTITION Region with 2 redundant copies: [source,xml] ---- - - - - - + + + + ---- -[[bootstrap:region:partition:options]] -=== `partitioned-region` Options +Refer to Geode's documentation on +http://geode.apache.org/docs/guide/11/developing/partitioned_regions/chapter_overview.html[Partitioned Regions] +for more details. -The following table offers a quick overview of configuration options specific to partitioned regions. These are in addition to the common region configuration options described above. +[[bootstrap:region:partition:attributes]] +=== Partitioned Region Attributes + +The following table offers a quick overview of configuration options specific to PARTITION Regions. +These are in addition to the common Region configuration options described <>. [cols="1,2,2", options="header"] -.partitioned-region options +.partitioned-region attributes |=== | Name | Values | Description -| partition-resolver -| *bean name* -| The name of the partitioned resolver used by this region, for custom partitioning. - -| partition-listener -| *bean name* -| The name of the partitioned listener used by this region, for handling partition events. - | copies | 0..4 -| The number of copies for each partition for high-availability. By default, no copies are created meaning there is no redundancy. Each copy provides extra backup at the expense of extra storage. +| The number of copies for each partition for high-availability. By default, no copies are created +meaning there is no redundancy. Each copy provides extra backup at the expense of extra storage. | colocated-with | *valid region name* -| The name of the partitioned region with which this newly created partitioned region is colocated. +| The name of the PARTITION Region with which this newly created PARTITION Region is collocated. | local-max-memory | *positive integer* -| The maximum amount of memory, in megabytes, to be used by the region in *this* process. +| The maximum amount of memory in megabytes used by the Region in *this* process. | total-max-memory | *any integer value* -| The maximum amount of memory, in megabytes, to be used by the region in *all* processes. +| The maximum amount of memory in megabytes used by the Region in *all* processes. + +| partition-listener +| *bean name* +| The name of the `PartitionListener` used by this Region, for handling partition events. + +| partition-resolver +| *bean name* +| The name of the `PartitionResolver` used by this Region, for custom partitioning. | recovery-delay | *any long value* -| The delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes. -1 (the default) indicates that redundancy will not be recovered after a failure. +| The delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes. +-1 (the default) indicates that redundancy will not be recovered after a failure. | startup-recovery-delay | *any long value* -| The delay in milliseconds that new members will wait before satisfying redundancy. -1 indicates that adding new members will not trigger redundancy recovery. The default is to recover redundancy immediately when a new member is added. - +| The delay in milliseconds that new members will wait before satisfying redundancy. +-1 indicates that adding new members will not trigger redundancy recovery. The default is to recover redundancy +immediately when a new member is added. |=== [[bootstrap:region:client]] == Client Region -GemFire supports various deployment topologies for managing and distributing data. The topic is outside the scope -of this documentation. However, to quickly recap, they can be classified in short as: peer-to-peer (p2p), client-server, -and wide area network (or WAN). In the last two configurations, it is common to declare *client* regions which connect -to a cache server. _Spring Data GemFire_ offers dedicated support for such configuration through -<>, `client-region` and `pool` elements. As the names imply, the former defines a client region -while the latter defines connection pools to be used/shared by the various client regions. +Apache Geode supports various deployment topologies for managing and distributing data. Geode topologies is outside +the scope of this documentation. However, to quickly recap, Geode's supported topologies can be classified in short as: +_peer-to-peer_ (p2p), _client-server_, and _wide area network_ (WAN). In the last two configurations, it is common +to declare *client* Regions which connect to a cache server. -Below is a typical client region configuration: +_Spring Data Geode_ offers dedicated support for such configuration through <>, +`client-region` and `pool` elements. As the names imply, the former defines a client Region while the latter defines +a Pool of connections to be used/shared by the various client Regions. + +Below is a typical client Region configuration: [source,xml] ---- - - - + + + + + - - - + + + - - - - - + + + ---- -As with the other region types, `client-region` supports `CacheListener``s` as well as a single `CacheLoader` or `CacheWriter`. It also requires a connection `pool` for connecting to a server. Each client can have its own pool or they can share the same one. +As with the other Region types, `client-region` supports `CacheListener``s` as well as a `CacheLoader` and `CacheWriter`. +It also requires a connection `Pool` for connecting to either a set of Locators or Servers. +Each client Region can have its own Pool or they can share the same one. -NOTE: In the above example, the pool is configured with a `locator`. The locator is a separate process used to discover cache servers in the distributed system and are recommended for production systems. It is also possible to configure the pool to connect directly to one or more cache servers using the `server` element. +NOTE: In the above example, the Pool is configured with `locator`. A Locator is a separate process used to discover +cache servers and peer data members in the distributed system and are recommended for production systems. It is also +possible to configure the Pool to connect directly to one or more cache servers using the `server` element. -For a full list of options to set on the client and especially on the pool, please refer to the Spring Data GemFire schema (<>) and the GemFire documentation. +For a full list of options to set on the client and especially on the Pool, please refer to +the _Spring Data Geode_ schema (<>) and Geode's documentation on +http://geode.apache.org/docs/guide/11/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server Configuration]. [[bootstrap:region:client:interests]] === Client Interests -To minimize network traffic, each client can define its own 'interest', pointing out to GemFire, the data it actually needs. In Spring Data GemFire, interests can be defined for each client, both key-based and regular-expression-based types being supported; for example: +To minimize network traffic, each client can separately define its own 'interests' policies, indicating to Geode +the data it actually requires. In _Spring Data Geode_, 'interests' can be defined for each client Region separately. +Both Key-based and Regular Expression-based interest types are supported. + +For example: [source,xml] ---- - + - + ---- -A special key `ALL_KEYS` means interest is registered for all keys (identical to a regex interest of `.*`). The `receive-values` attribute indicates whether or not the values are received for create and update events. If true, values are received; if false, only invalidation events are received - refer to the GemFire documentation for more details. +A special key, `ALL_KEYS`, means 'interest' is registered for all keys. The same can be accomplished using a regex +of `".\*"`. + +The `` _Key_ and _Regular Expression_ elements support 3 attributes: `durable`, `receive-values` +and `result-policy`. + +`durable` indicates whether the 'interest' policy and subscription queue created for the client when the client connects +to 1 or more servers in the cluster is maintained across client sessions. If the client goes away and comes back, +a "durable" subscription queue on the server(s) for the client is maintained while the client is disconnected, +and when the client reconnects, the client will receive any events that occurred while the client was disconnected +from the servers(s) in the cluster. + +A subscription queue on the servers in the cluster is maintained for each `Pool` of connections defined in the client +where subscription has also been "enabled" for that `Pool`. The subscription queue is used to store, and possibly +conflate, events sent to the client. If the subscription queue is durable, it persists between client sessions +(i.e. connections), potentially up to a specified timeout (if the client does not return within a given time frame +in order to reduce resource consumption on servers in the cluster). If the subscription queue is not "durable", +then it will be destroyed when the client disconnects. All you need to decide is, for your application use case, +is it important for the cache client to receive events while it is disconnected, or is it only important for +the application (cache client) to receive the "latest" events after it reconnects. + +The `receive-values` attribute indicates whether or not the entry values are received for create and update events. +If *true*, values are received; if *false*, only invalidation events are received. + +And finally, the 'result-policy` is an enumeration of: `KEYS`, `KEYS_VALUE` and `NONE`. The default is `KEYS_VALUES`. +The `result-policy` controls the initial dump when the client first connects to initialize the local cache, +essentially seeding the client with events for all the entries that match the interest policy. + +Client-side interests registration does not do much good without enabling subscription on the `Pool` as mentioned above. +In fact, it is an error to attempt interests registration without subscription enabled. To do so, you simply... + +[source,xml] +---- + + ... + +---- + +In addition to `subscription-enabled`, can you also set `subscription-ack-interval`, +`subscription-message-tracking-timeout` and `subscription-redundancy`. `subscription-redundancy` is used to control +how many copies of the subscription queue should be maintained by the servers in the cluster. If redundancy +is greater than 1, and the "primary" subscription queue (i.e. server) goes down, then a "secondary" subscription queue +will take over, keeping the client from missing events in a HA scenario. + +In addition to the `Pool` settings, the server-side Regions use an additional attribute, +`enable-subscription-conflation`, to control the conflation of events that will be sent to the clients. This can also +help further minimize network traffic and is useful in situations where the application only cares about +the latest value of an entry. However, in cases where the application is keeping a time series of events that occurred, +conflation is going to hinder that use case. The default value is *false*. An example Region configuration +on the server for which the client contains a corresponding client [CACHING_]PROXY Region with interests in Keys +in this server Region, would look like... + +[source,xml] +---- + + ... + +---- + +To control the amount of time in seconds that "durable" subscription queue is maintained after a client is disconnected +from the server(s) in the cluster, set the `durable-client-timeout` attribute on the `` element +like so... + +[source,xml] +---- + + ... + +---- + +A full, in-depth discussion of how client interests work and capabilities is beyond the scope of this document. + +Please refer to Apache Geode's documentation on +http://gemfire.docs.pivotal.io/geode/developing/events/how_client_server_distribution_works.html[Client-to-Server Event Distribution] +for more details. [[bootstrap:region:json]] == JSON Support -Gemfire 7.0 introduced support for caching JSON documents with OQL query support. These are stored internally as http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/pdx/PdxInstance.html[PdxInstance] types using the http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/pdx/JSONFormatter.html[JSONFormatter] to perform conversion to and from JSON strings. Spring Data GemFire provides a `` tag to enable a http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[AOP with Spring] component to advise appropriate region operations, effectively encapsulating the JSONFormatter, allowing your application to work directly with JSON strings. In addition, Java objects written to JSON configured regions will be automatically converted to JSON using the Jackson ObjectMapper. Reading these values will return a JSON string. +Apache Geode has support for caching JSON documents in Regions along with the ability to query stored JSON documents +using the Geode OQL. JSON documents are stored internally as +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types +using the http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class +to perform conversion to and from JSON documents (as a `String`). -By default, `` will perform the conversion on all regions. To apply this feature to selected regions, provide a comma delimited list of their ids via the `region-refs` attribute. Other attributes include a `pretty-print` flag (false by default) and `convert-returned-collections`. By default the results of region operations getAll() and values() will be converted for configured regions. This is done by creating a parallel structure in local memory. This can incur significant overhead for large collections. Set this flag to false to disable automatic conversion for these operation. NOTE: Certain region operations, specifically those that use GemFire's proprietary Region.Entry such as entries(boolean), entrySet(boolean) and getEntry() type are not targeted for AOP advice. In addition, the entrySet() method which returns a Set> is not affected. +_Spring Data Geode_ provides the `` element to enable a +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[AOP, _Spring_] +component to advise appropriate, proxied Region operations, which effectively encapsulates the `JSONFormatter`, +thereby allowing your applications to work directly with JSON Strings. + +In addition, Java objects written to JSON configured Regions will be automatically converted to JSON using Jackson's +`ObjectMapper`. Reading these values back will be returned as a JSON String. + +By default, `` performs the conversion for all Regions. To apply this feature +to selected Regions, provide a comma delimited list of Region bean ids via the `region-refs` attribute. +Other attributes include a `pretty-print` flag (defaults to *false*) and `convert-returned-collections`. + +Also by default, the results of the `getAll()` and `values()` Region operations will be converted for +configured Regions. This is done by creating a parallel data structure in local memory. This can incur +significant overhead for large collections, so set the `convert-returned-collections` to *false* +if you would like to disable automatic conversion for these Region operations. + +NOTE: Certain Region operations, specifically those that use Geode's proprietary `Region.Entry` such as: +`entries(boolean)`, `entrySet(boolean)` and `getEntry()` type are not targeted for AOP advice. In addition, +the `entrySet()` method which returns a `Set>` is also not affected. + +Example configuration: [source,xml] ---- - + ---- -This feature also works with seamlessly with GemfireTemplate operations, provided that the template is declared as a Spring bean. Currently native QueryService operations are not supported. - +This feature also works seamlessly with `GemfireTemplate` operations, provided that the template is declared +as a _Spring_ bean. Currently, the native `QueryService` operations are not supported. diff --git a/src/main/asciidoc/reference/repositories.adoc b/src/main/asciidoc/reference/repositories.adoc index 8e40b0a5..6200bde6 100644 --- a/src/main/asciidoc/reference/repositories.adoc +++ b/src/main/asciidoc/reference/repositories.adoc @@ -1,50 +1,52 @@ [[gemfire-repositories]] -= GemFire Repositories += Spring Data Geode Repositories == Introduction -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 +_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 http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here]. [[gemfire-repositories.spring-configuration]] == Spring Configuration -To bootstrap Spring Data Repositories you use the `` element from the GemFire Data namespace: +To bootstrap _Spring Data Repositories_, you use the `` element from the _Spring Data Geode_ +Data namespace: -.Bootstrap GemFire Repositories +.Bootstrap Spring Data Geode Repositories ==== [source,xml] ---- - + ---- ==== -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. +This configuration snippet looks for interfaces below the configured base package and creates Repository instances +for those interfaces backed by a `SimpleGemFireRepository`. + +IMPORTANT: You must have your application domain classes correctly mapped to configured Regions +or the bootstrap process will fail otherwise. [[gemfire-repositories.executing-queries]] == Executing OQL Queries -The GemFire Repositories allow the definition of query methods to easily execute OQL Queries against the Region -the managed entity is mapped to. +_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. .Sample Repository ==== [source,java] ---- -@Region("myRegion") +@Region("People") public class Person { … } ---- @@ -56,19 +58,21 @@ public interface PersonRepository extends CrudRepository { Collection findByFirstname(String firstname); - @Query("SELECT * FROM /Person p WHERE p.firstname = $1") + @Query("SELECT * FROM /People p WHERE p.firstname = $1") Collection findByFirstnameAnnotated(String firstname); - @Query("SELECT * FROM /Person p WHERE p.firstname IN SET $1") + @Query("SELECT * FROM /People p WHERE p.firstname IN SET $1") Collection findByFirstnamesAnnotated(Collection firstnames); } ---- ==== -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. +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. [cols="1,2,2", options="header"] .Supported keywords for query methods @@ -134,31 +138,32 @@ gets to verbose you can annotate the query methods with `@Query` as seen for met | `x.active = false` |=== -[[gemfire-repositories.oql-extension]] -== OQL Query Extensions with Annotations +[[gemfire-repositories.oql-extensions]] +== OQL Query Extensions using Annotations -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. +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 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. +One of _Spring Data Commons' Repository_ infrastructure goals is to function as the lowest common denominator +in order to maintain support for and portability across the widest array of data stores available and in use +for application development today. Technically, this means developers can access multiple different data stores +supported by _Spring Data Commons_ within their applications by reusing their existing application-specific +Repository interfaces, a very convenient and powerful abstraction. -To support GemFire's OQL Query language extensions and 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. +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 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. +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 OQL Query language extensions that are supported by Spring Data GemFire include: +Currently, the set of Geode OQL Query language extensions that are supported by _Spring Data Geode_ include: [cols="1,2,2,2", options="header"] -.Supported OQL Query extensions for query methods +.Supported Geode OQL extensions for Repository query methods |=== | Keyword | Annotation @@ -186,10 +191,10 @@ Currently, the set of OQL Query language extensions that are supported by Spring | NA |=== -As an example, suppose you have a `Customers` application domain type and corresponding GemFire Region along with a +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... -.Sample Repository +.Sample Customers Repository ==== [source,java] ---- @@ -231,12 +236,13 @@ public interface CustomerRepository extends GemfireRepository { This will result in the following OQL Query: -` IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers c WHERE c.lastName = $1 LIMIT 10` +` IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers x WHERE x.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. +_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. -For instance, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository` like so... +As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository` +like so... .CustomerRepository ==== @@ -256,18 +262,18 @@ public interface CustomerRepository extends GemfireRepository { This query method results in the following OQL Query: -`IMPORT org.example.app.domain.Customer; SELECT DISTINCT * FROM /Customers c WHERE c.reputation > $1 -ORDER BY c.reputation DESC LIMIT 5` +`IMPORT org.example.app.domain.Customer; 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. +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. [NOTE] ==== The "ReputationIdx" Index is probably not the most sensible index given the number of Customers who will possibly have the same value for their reputation, which will effectively reduce the effectiveness of the index. Please choose -indexes and other optimizations wisely as an improper or poorly choosen index and have the opposite effect on your +indexes and other optimizations wisely as an improper or poorly choosen index can have the opposite effect on your performance given the overhead in maintaining the index. The "ReputationIdx" was only used to serve the purpose of the example. ==== diff --git a/src/main/asciidoc/reference/samples.adoc b/src/main/asciidoc/reference/samples.adoc index 8f176c43..239156a5 100644 --- a/src/main/asciidoc/reference/samples.adoc +++ b/src/main/asciidoc/reference/samples.adoc @@ -1,31 +1,46 @@ [[samples]] = Sample Applications -NOTE: Sample applications are now maintained in the https://github.com/spring-projects/spring-gemfire-examples[Spring Data GemFire Examples] repository. +NOTE: Sample applications are now maintained in the +https://github.com/spring-projects/spring-gemfire-examples[Spring GemFire Examples] repository. -The Spring Data GemFire project also includes one sample application. Named "Hello World", the sample demonstrates how to configure and use GemFire inside a Spring application. At runtime, the sample offers a *shell* to the user allowing him to run various commands against the grid. It provides an excellent starting point for users unfamiliar with the essential components or the Spring and GemFire concepts. +The _Spring Data Geode_ project also includes one sample application. Named "Hello World", the sample application +demonstrates how to configure and use Apache Geode inside a _Spring_ application. At runtime, the sample offers +a *shell* to the user allowing her to run various commands against the data grid. It provides an excellent +starting point for users unfamiliar with the essential components or with _Spring_ and GemFire concepts. -The sample is bundled with the distribution and is Maven-based. One can easily import them into any Maven-aware IDE (such as https://spring.io/tools/sts[Spring Tool Suite]) or run them from the command-line. +The sample is bundled with the distribution and is Maven-based. A developer can easily import them into any +Maven-aware IDE (such as https://spring.io/tools/sts[Spring Tool Suite]) or run them from the command-line. [[samples:hello-world]] == Hello World -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 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. .Running under Linux -NOTE: If you experience networking problems when starting GemFire or the samples, try adding the following system property `java.net.preferIPv4Stack=true` to the command line (insert `-Djava.net.preferIPv4Stack=true`). For an alternative (global) fix especially on Ubuntu see this https://jira.spring.io/browse/SGF-28[link] +NOTE: If you experience networking problems when starting Geode or the samples, try adding the following +system property `java.net.preferIPv4Stack=true` to the command line (e.g. `-Djava.net.preferIPv4Stack=true`). +For an alternative (global) fix especially on Ubuntu see https://jira.spring.io/browse/SGF-28[SGF-28]. [[samples:hello-world:start-stop]] === Starting and stopping the sample -Hello World is designed as a stand-alone java application. It features a `Main` class which can be started either from your IDE of choice (in Eclipse/STS through `Run As/Java Application`) or from the command line through Maven using `mvn exec:java`. One can also use `java` directly on the resulting artifact if the classpath is properly set. +Hello World is designed as a stand-alone Java application. It features a `main` class which can be started +either from your IDE of choice (in Eclipse/STS through `Run As/Java Application`) or from the command-line +through Maven using `mvn exec:java`. A developer can also use `java` directly on the resulting artifact +if the classpath is properly set. -To stop the sample, simply type `exit` at the command line or press `Ctrl+C` to stop the VM and shutdown the Spring container. +To stop the sample, simply type `exit` at the command-line or press `Ctrl+C` to stop the JVM and shutdown +the _Spring_ container. [[samples:hello-world:run]] === Using the sample -Once started, the sample will create a shared data grid and allow the user to issue commands against it. The output will likely look as follows: +Once started, the sample will create a shared data grid and allow the user to issue commands against it. +The output will likely look as follows: [source] ---- @@ -61,7 +76,8 @@ null 2 ---- -Multiple instances can be created at the same time. Once started, the new VMs automatically see the existing region and its information: +Multiple instances can be ran at the same time. Once started, the new VMs automatically see the existing Region +and its information: [source] ---- @@ -77,12 +93,22 @@ Hello World! [one, two] ---- -Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance and see how the others react. To preserve data, at least one instance needs to be alive all times - if all instances are shutdown, the grid data is completely destroyed (in this example - to preserve data between runs, see the GemFire documentations). +Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance +and see how the others react. To preserve data, at least one instance needs to be alive all times. If all instances +are shutdown, the grid data is completely destroyed. [[samples:hello-world:explained]] === Hello World Sample Explained -Hello World uses both Spring XML and annotations for its configuration. The initial boostrapping configuration is `app-context.xml` which includes the cache configuration, defined under `cache-context.xml` file and performs classpath http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-classpath-scanning[scanning] for Spring http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[components]. The cache configuration defines the GemFire cache, region and for illustrative purposes a simple cache listener that acts as a logger. +Hello World uses both _Spring_ XML and annotations for its configuration. The initial bootstrapping configuration is +`app-context.xml`, which includes the cache configuration defined in the `cache-context.xml` file +and performs classpath +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-classpath-scanning[component scanning] +for _Spring_ +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[components]. -The main *beans* are `HelloWorld` and `CommandProcessor` which rely on the `GemfireTemplate` to interact with the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks. +The cache configuration defines the GemFire cache, Region and for illustrative purposes, a simple `CacheListener` +that acts as a logger. +The main *beans* are `HelloWorld` and `CommandProcessor` which rely on the `GemfireTemplate` to interact with +the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks. diff --git a/src/main/asciidoc/reference/serialization.adoc b/src/main/asciidoc/reference/serialization.adoc index 789c3f9f..6148b2ba 100644 --- a/src/main/asciidoc/reference/serialization.adoc +++ b/src/main/asciidoc/reference/serialization.adoc @@ -1,16 +1,39 @@ [[serialization]] -= Working with GemFire Serialization += Working with Apache Geode Serialization -To improve overall performance of the data grid, GemFire supports a dedicated serialization protocol (PDX) that is both faster and offers more compact results over the standard Java serialization and works transparently across various language http://community.gemstone.com/display/gemfire/Interoperability[platforms] (such as http://community.gemstone.com/display/gemfire/Serialization+in+Java[Java], http://community.gemstone.com/display/gemfire/Serialization+in+.NET[.NET] and C++). This chapter discusses the various ways in which Spring Data GemFire simplifies and improves GemFire custom serialization in Java. +To improve overall performance of the Apache Geode In-memory Data Grid, Geode supports a dedicated +serialization protocol, called PDX, that is both faster and offers more compact results over +standard Java serialization in addition to works transparently across various language platforms (Java, C++, .NET). +Please refer to +http://geode.apache.org/docs/guide/11/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features] +and +https://cwiki.apache.org/confluence/display/GEODE/PDX+Serialization+Internals[PDX Serialization Internals] +for more details. + +This chapter discusses the various ways in which _Spring Data Geode_ simplifies and improves Geode's +custom serialization in Java. [[serialization:wiring]] == Wiring deserialized instances -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 http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/Instantiator.html[`Instantiator`] that performs wiring for each new instance created by GemFire during deserialization. +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 +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/Instantiator.html[`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 http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-atconfigurable[`@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 (<>) for more details on wiring functionality. +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. -To use this `Instantiator`, simply declare it as a usual bean: +_Spring_ users might find this approach similar to that of +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-atconfigurable[`@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 (<>) for more details on wiring functionality. + +To use this SDG `Instantiator`, simply declare it as a bean: [source,xml] ---- @@ -22,16 +45,22 @@ 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. +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. [[serialization:instance-generator]] -== Auto-generating custom `Instantiator`s +== Auto-generating custom `Instantiators` -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: +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: [source,xml] ---- - + @@ -41,5 +70,6 @@ For data intensive applications, a large number of instances might be created on ---- -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. - +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. diff --git a/src/main/asciidoc/reference/snapshot.adoc b/src/main/asciidoc/reference/snapshot.adoc index 6a75b1c4..3d39bfb9 100644 --- a/src/main/asciidoc/reference/snapshot.adoc +++ b/src/main/asciidoc/reference/snapshot.adoc @@ -1,19 +1,25 @@ [[bootstrap:snapshot]] -= Using the Snapshot Service += Configuring the Snapshot Service -Spring Data GemFire supports `Cache` and `Region` snapshots using http://gemfire81.docs.pivotal.io/latest/userguide/index.html#managing/cache_snapshots/chapter_overview.html[GemFire's Snapshot Service]. -The out-of-the-box Snapshot Service support offers several convenient features to simply the use of GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/snapshot/CacheSnapshotService.html[Cache] -and http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/snapshot/RegionSnapshotService.html[Region] Snapshot Service APIs. +_Spring Data Geode_ supports `Cache` and `Region` snapshots using +http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Apache Geode's Snapshot Service]. +The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/CacheSnapshotService.html[Cache] +and http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/RegionSnapshotService.html[Region] +Snapshot Service APIs. -As http://gemfire.docs.pivotal.io/docs-gemfire/latest/managing/cache_snapshots/chapter_overview.html[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 http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-definition-profiles[Spring's bean definition profiles] +As the http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[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 http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-definition-profiles[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 `` 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: +_Spring Data Geode's_ support for Apache Geode's Snapshot Service begins with the `` element +from the `` 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: [source,xml] ---- @@ -25,23 +31,25 @@ 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. +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 GemFire `Cache`, having a -default name of `gemfireCache` (as described in <>). 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: +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 <>). 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: [source,xml] ---- ... -... + ... ---- -It is also straightforward to define a snapshot service for a GemFire Region by specifying the `region-ref` attribute: +It is also straightforward to define a Snapshot Service for a particular Geode Region by specifying +the `region-ref` attribute: [source,xml] ---- @@ -49,40 +57,43 @@ It is also straightforward to define a snapshot service for a GemFire Region by ... + - - - + - - + ---- -In addition, more complex snapshot filters can be expressed with the `ComposableSnapshotFilter` Spring Data GemFire class. -This class implements GemFire's http://data-docs-samples.cfapps.io/docs-gemfire/latest/javadocs/japi/com/gemstone/gemfire/cache/snapshot/SnapshotFilter.html[SnapshotFilter] interface -as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern. In a nutshell, the -https://en.wikipedia.org/wiki/Composite_pattern[Composite] design pattern allows developers to compose multiple objects -of the same type and treat the conglomerate as single instance of the object type, a very powerful and useful abstraction -to be sure. +In addition, more complex snapshot filters can be expressed with the `ComposableSnapshotFilter` _Spring Data Geode_ +provided class. This class implements Geode's +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] +interface as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern. -The `ComposableSnapshotFilter` has two factory methods, `'and'` and `'or'`, allowing developers to logically combine individual -snapshot filters using the AND and OR logical operators, respectively. The factory methods just take a list of snapshot filters. +In a nutshell, the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern allows developers +to compose multiple objects of the same type and treat the aggregate as single instance of the object type, +a very powerful and useful abstraction. -One is only limited by his/her imagination to leverage this powerful construct, for instance: +`ComposableSnapshotFilter` has two factory methods, `'and'` and `'or'`, allowing developers to logically combine +individual snapshot filters using the AND and OR logical operators, respectively. The factory methods take a +list of `SnapshotFilters`. + +In this case, the developer is only limited by his/her imagination to leverage this powerful construct. + +For instance: [source,xml] ---- @@ -155,7 +171,7 @@ One is only limited by his/her imagination to leverage this powerful construct, ---- -You could then go onto combine the `activesUsersSinceFilter` with another filter using `'or'` like so: +The developer could then go onto combine the `activesUsersSinceFilter` with another filter using `'or'` like so: [source,xml] ---- @@ -164,7 +180,7 @@ You could then go onto combine the `activesUsersSinceFilter` with another filter - + @@ -173,31 +189,36 @@ You could then go onto combine the `activesUsersSinceFilter` with another filter [[bootstrap::snapshot::events]] == Snapshot Events -By default, Spring Data GemFire uses GemFire's Snapshot Services on startup to import data and shutdown to export data. -However, you may want to trigger periodic, event-based snapshots, for either import or export from within your application. +By default, _Spring Data Geode_ uses Apache Geode's Snapshot Services on startup to import data and shutdown +to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export +from within your _Spring_ application. -For this purpose, Spring Data GemFire defines two additional Spring application events (extending Spring's http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[ApplicationEvent] class) -for imports and exports, respectively: `ImportSnapshotApplicationEvent` and `ExportSnapshotApplicationEvent`. +For this purpose, _Spring Data Geode_ defines two additional _Spring_ application events, extending _Spring's_ +http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[ApplicationEvent] +class for imports and exports, respectively: `ImportSnapshotApplicationEvent` and `ExportSnapshotApplicationEvent`. -The two application events can be targeted at the entire GemFire Cache, or individual GemFire Regions. The constructors -of these `ApplicationEvent` classes accept an optional Region pathname (e.g. "/Example") as well as 0 or more -`SnapshotMetadata` instances. +The two application events can be targeted at the entire Geode Cache, or individual Geode Regions. The constructors +in these classes accept an optional Region pathname (e.g. "/Example") as well as 0 or more `SnapshotMetadata` instances. The array of `SnapshotMetadata` is used to override the snapshot meta-data defined by `` and `` sub-elements in XML, which will be used in cases where snapshot application events -do not explicitly provide `SnapshotMetadata`. Each individual `SnapshotMetadata` instance can define it's own `location` -and `filters` properties. +do not explicitly provide `SnapshotMetadata`. Each individual `SnapshotMetadata` instance can define it's own +`location` and `filters` properties. -Import/export snapshot application events are received by all snapshot service beans defined in the Spring application context. -However, import/export events are only processed by "matching" snapshot service beans. +Import/export snapshot application events are received by all snapshot service beans defined in the _Spring_ +`ApplicationContext`. However, import/export events are only processed by "matching" Snapshot Service beans. -A Region-based `[Import|Export]SnapshotApplicationEvent` matches if the snapshot service bean defined is a `RegionSnapshotService` -and it's Region reference (as determined by `region-ref`) matches the Region's pathname specified by the snapshot application event. -A Cache-based `[Import|Export]SnapshotApplicationEvent` (i.e. a snapshot application event without a Region pathname) triggers -all snapshot service beans, including any `RegionSnapshotService` beans, to perform either an import or export, respectively. +A Region-based `[Import|Export]SnapshotApplicationEvent` matches if the Snapshot Service bean defined +is a `RegionSnapshotService` and it's Region reference (as determined by the `region-ref` attribute) matches +the Region's pathname specified by the snapshot application event. -It is very easy to use Spring's http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEventPublisher.html[ApplicationEventPublisher] interface -to fire import and/or export snapshot application events from your application like so: +A Cache-based `[Import|Export]SnapshotApplicationEvent` (i.e. a snapshot application event without a Region pathname) +triggers all Snapshot Service beans, including any `RegionSnapshotService` beans, to perform either an import or export, +respectively. + +It is very easy to use _Spring's_ +http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEventPublisher.html[ApplicationEventPublisher] +interface to fire import and/or export snapshot application events from your application like so: [source,java] ---- @@ -225,10 +246,12 @@ public class ExampleApplicationComponent { } ---- -In this particular example, only the "/Example" Region's SnapshotService bean will pick up and handle the export event, -saving the filtered "/Example" Region's data to the "data.snapshot" file in a sub-direcrtory of the application's -working directory. +In this particular example, only the "/Example" Region's Snapshot Service bean will pick up and handle the export event, +saving the filtered, "/Example" Region's data to the "data.snapshot" file in a sub-direcrtory +of the application's working directory. -Using Spring application events and messaging subsystem is a good way to keep your application loosely coupled. It is -also not difficult to imagine that the snapshot application events could be fired on a periodic basis using Spring's -http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#scheduling-task-scheduler[Scheduling] services. +Using _Spring_ application events and messaging subsystem is a good way to keep your application loosely coupled. +It is also not difficult to imagine that the snapshot application events could be fired on a periodic basis +using _Spring's_ +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#scheduling-task-scheduler[Scheduling] +services. diff --git a/src/main/resources/changelog.txt b/src/main/resources/changelog.txt index fff54a42..6159f439 100644 --- a/src/main/resources/changelog.txt +++ b/src/main/resources/changelog.txt @@ -102,769 +102,3 @@ Changes in version 1.7.0.APACHE-GEODE-EA-M1 (2016-02-12) * SGF-467 - Add Code of Conduct * SGF-468 - Improve coordination between the PoolFactoryBean and ClientCacheFactoryBean when configuring and resolving the GemFire DistributedSystem * SGF-471 - Release 1.7.0.APACHE-GEODE-EA-M1 - - -Changes in version 1.8.4.RELEASE (2016-09-29) ---------------------------------------------- -* SGF-535 - Allow both SpEL and property placeholder expressions to be used in the locators/servers attributes of the XML namespace element. -* SGF-534 - Fix ordered GemfireRepository.findAll(Sort) queries. -* SGF-531 - Release 1.8.4 (Hopper SR4). - - -Changes in version 1.7.6.RELEASE (2016-09-29) ---------------------------------------------- -* SGF-536 - Release 1.7.6 (Gosling SR6). -* SGF-535 - Allow both SpEL and property placeholder expressions to be used in the locators/servers attributes of the XML namespace element. -* SGF-534 - Fix ordered GemfireRepository.findAll(Sort) queries. - - -Changes in version 1.7.5.RELEASE (2016-09-20) ---------------------------------------------- -* SGF-532 - org.springframework.shell:spring-shell is listed in the pom as a runtime dependency. -* SGF-530 - Move project build to Maven. -* SGF-529 - Release 1.7.5 (Gosling SR5). -* SGF-522 - There are a few broken links in SDG documentation. -* SGF-507 - Handle case-insensitive OQL queries defined as Repository query methods. -* SGF-504 - Support Repositories with multiple Spring Data modules on the class path. -* SGF-475 - Add additional logging to the MappingPdxSerializer. -* SGF-474 - Fix the NPE in the MappingPdxSerializer. - - -Changes in version 1.8.3.RELEASE (2016-09-20) ---------------------------------------------- -* SGF-522 - There are a few broken links in SDG documentation. -* SGF-507 - Handle case-insensitive OQL queries defined as Repository query methods. -* SGF-506 - ExceptionInInitializerError with Spring Gemfire 1.8.1. -* SGF-504 - Support Repositories with multiple Spring Data modules on the class path. -* SGF-503 - Release 1.8.3 (Hopper SR3). - - -Changes in version 1.9.0.M1 (2016-07-27) ----------------------------------------- -* SGF-507 - Handle case-insensitive OQL queries defined as Repository query methods. -* SGF-506 - ExceptionInInitializerError with Spring Gemfire 1.8.1. -* SGF-504 - Support Repositories with multiple Spring Data modules on the class path. -* SGF-502 - DiskStoreAndEvictionRegionParsingTest fails when building with Maven due to missing Disk Store sub-directory. -* SGF-501 - Add serialVersionUID to ListRegionsOnServerFunction. -* SGF-499 - Prevent SDG-defined Pools from being destroyed before the Regions that use them. -* SGF-497 - Intermittent failures in DurableClientCacheIntegrationTest. -* SGF-496 - Upgrade to Pivotal GemFire 8.2.1. -* SGF-495 - Add 1.9 XML schemas for SDG namespaces. -* SGF-494 - Fix bug in GemfirePersistentEntity caused by Spring Data Commons ClassGeneratingPropertyAccessorFactory. -* SGF-492 - Improve GemFire Java-based configuration support - Iteration 1. -* SGF-486 - Release 1.9 M1 (Ingalls). -* SGF-445 - Remove MaxPermSize Java option from Gradle build. -* SGF-267 - Backwards Compatibility Testing between Clients and Servers as well as between GemFire Peer Members. - - -Changes in version 1.8.2.RELEASE (2016-06-15) ---------------------------------------------- -* SGF-502 - DiskStoreAndEvictionRegionParsingTest fails when building with Maven due to missing Disk Store sub-directory. -* SGF-501 - Add serialVersionUID to ListRegionsOnServerFunction. -* SGF-499 - Prevent SDG-defined Pools from being destroyed before the Regions that use them. -* SGF-497 - Intermittent failures in DurableClientCacheIntegrationTest. -* SGF-487 - Release 1.8.2 (Hopper SR2). -* SGF-484 - NoSuchMethodError with Spring Data Gemfire RC1 version. - - -Changes in version 1.8.1.RELEASE (2016-04-06) ---------------------------------------------- -* SGF-485 - Release 1.8.1 (Hopper SR1). - - -Changes in version 1.8.0.RELEASE (2016-04-06) ---------------------------------------------- -* SGF-483 - Add pull request template. -* SGF-482 - Release 1.8 GA (Hopper). - - -Changes in version 1.8.0.RC1 (2016-03-18) ------------------------------------------ -* SGF-481 - Upgrade to Spring Framework 4.2.5.RELEASE. -* SGF-480 - Change default for use-bean-factory-locator to false. -* SGF-479 - Remove lazy initialization option for configuring a GemFire cache. -* SGF-478 - Release 1.8 RC1 (Hopper). -* SGF-475 - Add additional logging to the MappingPdxSerializer. -* SGF-474 - Fix the NPE in the MappingPdxSerializer. -* SGF-473 - Allow a Spring-configured ClientCache to be constructed without a Pool. -* SGF-472 - Dependency to Aspectjweaver missing in Hopper M1. -* SGF-469 - Add support for CDI. -* SGF-416 - Avoid eager creation of a GemFire DistributedSystem in the PoolFactoryBean by creating a ClientCache first. - - -Changes in version 1.7.4.RELEASE (2016-02-23) ---------------------------------------------- -* SGF-473 - Allow a Spring-configured ClientCache to be constructed without a Pool. -* SGF-470 - Release 1.7.4 (Gosling SR4). -* SGF-462 - Add appinfo hint to client region element in XSD. -* SGF-460 - Remove unnecessary SLF4J compile-time dependency. -* SGF-459 - Add support for the get(key:Object, valueLoader:Callable) method in Spring Framework 4.3's Cache interface. -* SGF-458 - Enable resolution of GemFire's DistributedSystem and System properties to be overridden in PoolFactoryBean. -* SGF-457 - Clean up Javadoc warnings. - - -Changes in version 1.8.0.M1 (2016-02-12) ----------------------------------------- -* SGF-468 - Improve coordination between the PoolFactoryBean and ClientCacheFactoryBean when configuring and resolving the GemFire DistributedSystem. -* SGF-467 - Add Code of Conduct. -* SGF-466 - Restore function to the Gradle-based build. -* SGF-465 - Move project build to Maven. -* SGF-464 - Release 1.8 M1 (Hopper). -* SGF-462 - Add appinfo hint to client region element in XSD. -* SGF-461 - Upgrade to Spring Framework 4.1.9.RELEASE. -* SGF-460 - Remove unnecessary SLF4J compile-time dependency. -* SGF-459 - Add support for the get(key:Object, valueLoader:Callable) method in Spring Framework 4.3's Cache interface. -* SGF-458 - Enable resolution of GemFire's DistributedSystem and System properties to be overridden in PoolFactoryBean. -* SGF-457 - Clean up Javadoc warnings. -* SGF-455 - Fix creation of GemfireMappingContext for repositories. -* SGF-454 - Adapt to API changes in Spring Data Commons. -* SGF-450 - GemfireRepositoryFactoryBean needs to explicitly register the "default" GemfireMappingContext when not explicitly defined as a bean in the application's Spring context. -* SGF-449 - GemfireRepositoryFactoryBean.setGemfireMappingContext needs to call RepositoryFactoryBeanSupport.setMappingContext. -* SGF-448 - GemfireRepositoryConfigurationExtension needs to override the RepositoryConfigurationExtensionSupport postProcess(:BeanDefinitionBuilder, :AnnotationRepositoryConfigurationSource) method. -* SGF-447 - Fix apache-geode build due to recent changes in Apache Geode that removed various internal utility classes in favor of external Spring classes. -* SGF-442 - Remove incorrect statements about GemFire Java Reflection-based (PDX) Serialization in the SDG Reference Guide. -* SGF-441 - Fix possible CacheClosedException in ClientCacheFactoryBean onApplicationEvent(:ContextRefreshedEvent) when the ClientCache initialization is lazy. -* SGF-440 - Optimize imports across the SDG codebase. -* SGF-439 - Add 'durable-client-id' and 'durable-client-timeout' attributes to the namespace element for convenience. -* SGF-438 - Make , 'ready-for-events' true the default for durable clients. -* SGF-437 - Upgrade to Spring Framework 4.1.8.RELEASE. -* SGF-434 - Add a durable GemFire client cache test to assert proper behavior by SDG. -* SGF-433 - Fix improper resolution of Spring property placeholders in 'locators' and 'servers' attributes on the '' element(s) in Spring XML config. -* SGF-432 - IndexFactoryBean traps IndexExistsException instead of IndexNameConflictException. -* SGF-431 - Remove mavenLocal() from the artifact repository declarations. -* SGF-430 - Cleanup test failures on Windows due to incorrect Spring test context configuration resource resolution. -* SGF-429 - GemfirePersistentProperty considers a BigDecimal property an entity. -* SGF-427 - Update Spring Data GemFire Reference Guide 'New in the 1.7 Release' section. -* SGF-387 - Prepare SDG 1.8 and upgrade to GemFire 8.2.0 GA. -* SGF-373 - Implement a Spring Session Adapter for GemFire to back an HttpSession similar to Redis. - - -Changes in version 1.7.2.RELEASE (2015-12-18) ---------------------------------------------- -* SGF-456 - Release 1.7.2 (Gosling). -* SGF-455 - Fix creation of GemfireMappingContext for repositories. -* SGF-450 - GemfireRepositoryFactoryBean needs to explicitly register the "default" GemfireMappingContext when not explicitly defined as a bean in the application's Spring context. -* SGF-449 - GemfireRepositoryFactoryBean.setGemfireMappingContext needs to call RepositoryFactoryBeanSupport.setMappingContext. -* SGF-448 - GemfireRepositoryConfigurationExtension needs to override the RepositoryConfigurationExtensionSupport postProcess(:BeanDefinitionBuilder, :AnnotationRepositoryConfigurationSource) method. -* SGF-447 - Fix Spring Data GemFire due to recent changes to Apache Geode that removed various internal utility classes in favor of external Spring classes. - - -Changes in version 1.7.1.RELEASE (2015-11-15) ---------------------------------------------- -* SGF-446 - Release 1.7.1 (Gosling). -* SGF-443 - Fix Spring Data GemFire apache-geode build due to recent changes to Apache Geode that removed the HDFS support. -* SGF-442 - Remove incorrect statements about GemFire Java Reflection-based (PDX) Serialization in the SDG Reference Guide. -* SGF-437 - Upgrade to Spring Framework 4.1.8.RELEASE. -* SGF-434 - Add a durable GemFire client cache test to assert proper behavior by SDG. -* SGF-433 - Fix improper resolution of Spring property placeholders in 'locators' and 'servers' attributes on the '' element(s) in Spring XML config. -* SGF-432 - IndexFactoryBean traps IndexExistsException instead of IndexNameConflictException. -* SGF-430 - Cleanup test failures on Windows due to incorrect Spring test context configuration resource resolution. -* SGF-429 - GemfirePersistentProperty considers a BigDecimal property an entity. -* SGF-427 - Update Spring Data GemFire Reference Guide 'New in the 1.7 Release' section. - - -Changes in version 1.5.4.RELEASE (2015-10-14) ---------------------------------------------- -* SGF-436 - Release 1.5.4 (Evans). - - -Changes in version 1.7.0.RELEASE (2015-09-01) ---------------------------------------------- -* SGF-426 - Release 1.7 GA (Gosling). -* SGF-425 - Allow early initialization and re-initialization of LazyWiringDeclarableSupport instances. -* SGF-423 - Handle improper ClassCastException thrown from SDG's Function Execution interface and annotation-based support when a GemFire Function throws an Exception. -* SGF-419 - Documentation error on page 22 in the Spring Data GemFire Reference PDF. -* SGF-408 - Provide support in the SDG XML namespace to load a pre-defined data set using GemFire Snapshot Service for development and testing purposes. -* SGF-392 - Add support for OQL Query statement extensions in Repository Query methods via Annotations. - - -Changes in version 1.7.0.RC1 (2015-08-04) ------------------------------------------ -* SGF-422 - Release 1.7 RC1 (Gosling). -* SGF-421 - Fix Spring Data GemFire's MappingPdxSerializer due to the package-private access modifier change on org.springframework.data.mapping.model.BeanWrapper. -* SGF-418 - Merge PR #83 updating the Spring IO Platform Plugin to perform compatibility checks. -* SGF-417 - Update apache-geode SDG branch based on the latest Apache Geode developments (snapshot 20150713182515). -* SGF-415 - Remove the ClientCacheFactory Pool configuration in ClientCacheFactoryBean. -* SGF-414 - Resolve incompatibility between the DistributedSystem created by the PoolFactoryBean and the DistributedSystem resolved by the ClientCacheFactoryBean when SSL is configured. -* SGF-410 - Enable the definition and creation of a generic, GemFire Cache Region with out-the-box defaults. -* SGF-409 - Modify the GemfireDataSourcePostProcessor (basis for ) to not assume a GemFire Server was configured and bootstrapped with Spring and subsequently that the SDG ListRegionsOnServerFunction was registered. -* SGF-407 - Modify the MappingPdxSerializer to allow for extensibility. -* SGF-406 - Fix JavaDoc build. -* SGF-404 - Enable Expiration settings and policies to be specified per application domain object using an @Expiration annotation and a "custom", SDG-provided CustomExpiry instance. -* SGF-398 - Provide early support of Apache Geode (Pivotal GemFire OSS). -* SGF-370 - Add multi-Index definition and creation support. - - -Changes in version 1.6.2.RELEASE (2015-07-28) ---------------------------------------------- -* SGF-420 - Release 1.6.2 (Fowler). -* SGF-415 - Remove the ClientCacheFactory Pool configuration in ClientCacheFactoryBean. -* SGF-414 - Resolve incompatibility between the DistributedSystem created by the PoolFactoryBean and the DistributedSystem resolved by the ClientCacheFactoryBean when SSL is configured. -* SGF-409 - Modify the GemfireDataSourcePostProcessor (basis for ) to not assume a GemFire Server was configured and bootstrapped with Spring and subsequently that the SDG ListRegionsOnServerFunction was registered. - - -Changes in version 1.4.6.RELEASE (2015-07-01) ---------------------------------------------- -* SGF-411 - Release 1.4.6 (Dijkstra). -* SGF-399 - Fix incorrect XSD appinfo annotation, expected 'type' attribute value on the 'error-handler' attribute of the 'cq-listener-container' element. - - -Changes in version 1.5.3.RELEASE (2015-07-01) ---------------------------------------------- -* SGF-412 - Release 1.5.3 (Evans). -* SGF-407 - Modify the MappingPdxSerializer to allow for extensibility. -* SGF-406 - Fix JavaDoc build. -* SGF-399 - Fix incorrect XSD appinfo annotation, expected 'type' attribute value on the 'error-handler' attribute of the 'cq-listener-container' element. -* SGF-393 - Region scope not properly set for replicated region, prevents client CQ from registering properly. -* SGF-385 - Local region does remote put in addition to local put in client cache. -* SGF-384 - Issue with partitioned-region-template when persistence is enabled. -* SGF-382 - Add logging to the SpringContextBootstrappingInitializer init method to capture any Spring context/GemFire errors on startup. -* SGF-381 - Enable RegionFactoryBean to respect the Data Policy specified on a nested or referenced RegionAttributes bean definition. -* SGF-379 - Specifying multiple or a single Gateway Endpoint with one or more GatewayListeners is not permitted by the SDG XML namespace (XSD) gatewayType element definition. -* SGF-378 - SDG completely ignores the 'socket-read-timeout' attribute on the Gateway element nested in a GatewayHub. -* SGF-376 - The GemFire WAN GatewayHub support needs refactoring and test coverage. -* SGF-375 - The XML namespace element is missing the 'max-time-between-pings' attribute. -* SGF-374 - Specifying a disk-store on a GatewayHub forces the GatewayHub to be persistent. - - -Changes in version 1.6.1.RELEASE (2015-06-30) ---------------------------------------------- -* SGF-413 - Release 1.6.1 (Fowler). -* SGF-407 - Modify the MappingPdxSerializer to allow for extensibility. -* SGF-406 - Fix JavaDoc build. -* SGF-400 - Enable the ability to set the ClassLoader used by the Spring ApplicationContext created in the SpringContextBootstrappingInitializer for loading bean definition classes and resolving resources. -* SGF-399 - Fix incorrect XSD appinfo annotation, expected 'type' attribute value on the 'error-handler' attribute of the 'cq-listener-container' element. -* SGF-396 - Enable support for variable Locator and Server endpoints on a SDG GFE Pool bean definition in a Spring Context. -* SGF-395 - Allow Spring JavaConfig @Configuration classes to be registered and used to configure the (AnnotationConfig)ApplicationContext created by the SpringContextBootstrappingInitializer. -* SGF-394 - Improve SDG Gradle build removing FindBug compilation warnings caused by GemFire. -* SGF-393 - Region scope not properly set for replicated region, prevents client CQ from registering properly. - - -Changes in version 1.7.0.M1 (2015-06-02) ----------------------------------------- -* SGF-405 - Release 1.7 M1 (Gosling). -* SGF-403 - Simplify the process of adding custom methods to Spring Data GemFire Repositories. -* SGF-400 - Enable the ability to set the ClassLoader used by the Spring ApplicationContext created in the SpringContextBootstrappingInitializer for loading bean definition classes and resolving resources. -* SGF-399 - Fix incorrect XSD appinfo annotation, expected 'type' attribute value on the 'error-handler' attribute of the 'cq-listener-container' element. -* SGF-397 - Upgrade to Spring Framework 4.1.6.RELEASE. -* SGF-396 - Enable support for variable Locator and Server endpoints on a SDG GFE Pool bean definition in a Spring Context. -* SGF-395 - Allow Spring JavaConfig @Configuration classes to be registered and used to configure the (AnnotationConfig)ApplicationContext created by the SpringContextBootstrappingInitializer. -* SGF-394 - Improve SDG Gradle build removing FindBug compilation warnings caused by GemFire. -* SGF-393 - Region scope not properly set for replicated region, prevents client CQ from registering properly. -* SGF-391 - Simplify and improve the robustness of the JNDI DataSource Type matching used in the Cache FactoryBeans. -* SGF-390 - Improve unit test coverage for the PoolFactoryBean class. -* SGF-389 - Improve unit test coverage of the ClientCacheFactoryBean class. -* SGF-388 - Improve unit test coverage of the CacheFactoryBean class. -* SGF-383 - Refactor and make RegionFactoryBean and RegionLookupFactoryBean abstract. -* SGF-371 - The GatewayReceiverFactoryBean needs to set GatewayReceiverFactory.setManualStart(false) in GemFire 8.1 in order to enable manual starts on a GatewayReceiver. -* SGF-357 - Optimize SimpleGemfireRepository.deleteAll() by using the new Region.removeAll() operation. -* SGF-353 - Prepare SDG 1.7 and upgrade to GemFire 8.1.0 GA. -* SGF-345 - Add PDX Aliases support. -* SGF-322 - Add support for the newly added, retro 'max-connections' attribute on the element in the SDG XML namespace (XSD). -* SGF-196 - Support adding CacheListeners, CacheLoaders and CacheWriters, along with other mutable Region attributes to an existing Region. - - -Changes in version 1.6.0.RELEASE (2015-03-23) ---------------------------------------------- -* SGF-386 - Release 1.6 GA. -* SGF-385 - Local region does remote put in addition to local put in client cache. -* SGF-384 - Issue with partitioned-region-template when persistence is enabled. -* SGF-382 - Add logging to the SpringContextBootstrappingInitializer init method to capture any Spring context/GemFire errors on startup. -* SGF-381 - Enable RegionFactoryBean to respect the Data Policy specified on a nested or referenced RegionAttributes bean definition. - - -Changes in version 1.6.0.RC1 (2015-03-05) ------------------------------------------ -* SGF-380 - Release 1.6 RC1. -* SGF-379 - Specifying multiple or a single Gateway Endpoint with one or more GatewayListeners is not permitted by the SDG XML namespace (XSD) gatewayType element definition. -* SGF-378 - SDG completely ignores the 'socket-read-timeout' attribute on the Gateway element nested in a GatewayHub. -* SGF-376 - The GemFire WAN GatewayHub support needs refactoring and test coverage. -* SGF-375 - The XML namespace element is missing the 'max-time-between-pings' attribute. -* SGF-374 - Specifying a disk-store on a GatewayHub forces the GatewayHub to be persistent. -* SGF-366 - Unable to create local-only, client-based Region Indexes using SDG's and corresponding IndexFactoryBean functionality. -* SGF-364 - Move EvictionAttributesFactoryBean and SubscriptionAttributesFactoryBean along with supporting enum types from the ..data.gemfire.config package to ..data.gemfire. -* SGF-363 - Upgrade to Spring Framework 4.0.9.RELEASE. -* SGF-360 - Failures in SubRegionNamespaceTests when built with Java 8. -* SGF-358 - Enhance SDG's Function annotation support to allow strongly-typed arguments in the context of PDX even when read-serialized is set to true. -* SGF-354 - SimpleGemfireRepository.deleteAll that supports transactions. -* SGF-289 - Enumeration restrictions (xsd:enumeration) should be avoided in the XML schema. - - -Changes in version 1.5.2.RELEASE (2015-01-28) ---------------------------------------------- -* SGF-368 - Release 1.5.2. -* SGF-366 - Unable to create local-only, client-based Region Indexes using SDG's and corresponding IndexFactoryBean functionality. -* SGF-363 - Upgrade to Spring Framework 4.0.9.RELEASE. -* SGF-360 - Failures in SubRegionNamespaceTests when built with Java 8. -* SGF-358 - Enhance SDG's Function annotation support to allow strongly-typed arguments in the context of PDX even when read-serialized is set to true. -* SGF-354 - SimpleGemfireRepository.deleteAll that supports transactions. -* SGF-352 - Change all Artifact Repository URLs to use HTTPS. -* SGF-348 - Upgrade to Spring Framework 4.0.8.RELEASE. - - -Changes in version 1.4.5.RELEASE (2015-01-27) ---------------------------------------------- -* SGF-369 - Fix Javadoc so that 1.4.x builds on Java 8. -* SGF-367 - Release 1.4.5. -* SGF-362 - Upgrade to Spring Framework 3.2.13.RELEASE. -* SGF-352 - Change all Artifact Repository URLs to use HTTPS. -* SGF-349 - Upgrade to Spring Framework 3.2.12.RELEASE. -* SGF-346 - Enable LazyWiringDeclarableSupport-based GemFire components to be used inside both cache.xml and Spring config, especially in the context of GemFire 8's Cluster Configuration. -* SGF-343 - Optimize the SDG implementation of CrudRepository.save(Iterable enttiies) to use GemFire's Region.putAll(Map values) operation. -* SGF-337 - SDG's XML Schema (XSD) does not allow the developer to specify 'timeout' and 'action' values for CustomExpiry () on Region attributes. -* SGF-336 - Upgrade to Spring Framework 3.2.11.RELEASE. -* SGF-333 - The SpringContextBootstrappingInitializer needs to handle the case when it's init(:Properties) method maybe called more than once on initialization. -* SGF-330 - Add missing 'disk-synchronous' attribute to the element in the SDG XML namespace (XSD). -* SGF-328 - Add missing 'hostname-for-senders' attribute on the element in the SDG XML namespace (XSD). -* SGF-327 - Avoid setting null values with GemFire's Cache Region put(key, value) operation when GemFire is used as the caching provider in Spring's Cache Abstraction (@Cacheable). -* SGF-317 - Improve GemfireCache implementation to be able to build on Spring 4.1. - - -Changes in version 1.6.0.M1 (2014-12-01) ----------------------------------------- -* SGF-356 - local-region on client side. -* SGF-355 - Release 1.6 M1. -* SGF-350 - Upgrade to Spring Data Commons 1.10. -* SGF-348 - Upgrade to Spring Framework 4.0.8.RELEASE. -* SGF-346 - Enable LazyWiringDeclarableSupport-based GemFire components to be used inside both cache.xml and Spring config, especially in the context of GemFire 8's Cluster Configuration. -* SGF-343 - Optimize the SDG implementation of CrudRepository.save(Iterable enttiies) to use GemFire's Region.putAll(Map values) operation. -* SGF-342 - Update Spring Data GemFire Reference Guide with GemFire 8 functional support. -* SGF-340 - Change a SpringSource-based links in the SDG Reference Guide to Spring.io-based links. -* SGF-339 - Change all VMWare-based links in the SDG Reference Guide to Pivotal-based links. -* SGF-338 - Both and SDG XML namespace elements allow for more than one 'CustomExpiry' bean to be set in the Region Expiration Attributes although GemFire only allows one!. -* SGF-337 - SDG's XML Schema (XSD) does not allow the developer to specify 'timeout' and 'action' values for CustomExpiry () on Region attributes. -* SGF-333 - The SpringContextBootstrappingInitializer needs to handle the case when it's init(:Properties) method maybe called more than once on initialization. -* SGF-332 - Add support for the GatewaySender 'eventSubstitutionFilter' property in the SDG XSD and GatewaySenderFactoryBean API. -* SGF-331 - Pull common WAN attributes from GatewaySenders and AsyncEventQueues in the SDG XSD into the 'commonWANQueueAttributes' attributes group. -* SGF-330 - Add missing 'disk-synchronous' attribute to the element in the SDG XML namespace (XSD). -* SGF-328 - Add missing 'hostname-for-senders' attribute on the element in the SDG XML namespace (XSD). -* SGF-327 - Avoid setting null values with GemFire's Cache Region put(key, value) operation when GemFire is used as the caching provider in Spring's Cache Abstraction (@Cacheable). -* SGF-326 - Create spring-gemfire-1.6.xsd and spring-data-gemfire-1.6.xsd for SDG 1.6. -* SGF-325 - Create spring-gemfire-2.0.xsd and spring-data-gemfire-2.0.xsd for SDG 2. -* SGF-323 - Add support for GemFire 8's DiskStore 'diskUsageCriticalPercentage' and 'diskUsageWarningPercentage' properties in the SDG XML namespace (XSD) and DiskStoreFactoryBean API. -* SGF-318 - Upgrade to Spring Framework 4.0.7. -* SGF-317 - Improve GemfireCache implementation to be able to build on Spring 4.1. -* SGF-316 - Update Spring Data GemFire Reference Guide with 1.5 changes (e.g. Auto Region Lookups, Region Templates). -* SGF-314 - Upgrade to Spring Framework 4.0.7. -* SGF-313 - SDG 1.6 support for both GemFire 7 and GemFire 8. -* SGF-309 - Add support for Region Data Compression with the new 'Compressor' property on the RegionAttributes class. -* SGF-291 - Upgrade Spring Data GemFire 1.5 to GemFire 8.0. -* SGF-270 - Remove the validation logic in the AsyncEventQueueFactoryBean restricting the specification of Dispatcher Threads when a 'Parallel' AsyncEventQueue is used. -* SGF-269 - Remove the validation logic in the GatewaySenderFactoryBean restricting the specification of Dispatcher Threads when a 'Parallel' GatewaySender is used. -* SGF-264 - Completely remove the 'data-policy' and 'shortcut' attributes from the SDG XML namespace Region elements. -* SGF-227 - Support for 'auto-reconnect' functionality when peers are forcefully disconnected from the cluster. -* SGF-226 - Support for requesting a peer member's configuration from a GemFire Locator/Manager using the new Cluster-based Configuration Service. - - - -Changes in version 1.5.1.RELEASE (2014-10-30) ---------------------------------------------- -* SGF-347 - Release 1.5.1. -* SGF-346 - Enable LazyWiringDeclarableSupport-based GemFire components to be used inside both cache.xml and Spring config, especially in the context of GemFire 8's Cluster Configuration. -* SGF-343 - Optimize the SDG implementation of CrudRepository.save(Iterable enttiies) to use GemFire's Region.putAll(Map values) operation. -* SGF-340 - Change a SpringSource-based links in the SDG Reference Guide to Spring.io-based links. -* SGF-339 - Change all VMWare-based links in the SDG Reference Guide to Pivotal-based links. -* SGF-337 - SDG's XML Schema (XSD) does not allow the developer to specify 'timeout' and 'action' values for CustomExpiry () on Region attributes. -* SGF-333 - The SpringContextBootstrappingInitializer needs to handle the case when it's init(:Properties) method maybe called more than once on initialization. -* SGF-330 - Add missing 'disk-synchronous' attribute to the element in the SDG XML namespace (XSD). -* SGF-328 - Add missing 'hostname-for-senders' attribute on the element in the SDG XML namespace (XSD). -* SGF-327 - Avoid setting null values with GemFire's Cache Region put(key, value) operation when GemFire is used as the caching provider in Spring's Cache Abstraction (@Cacheable). - - -Changes in version 1.5.0.RELEASE (2014-09-05) ---------------------------------------------- -* IMPORTANT: Upgrade to Gemfire 8.0 has been postponed to a 2.0 release. -* SGF-319 - Release 1.5 GA. -* SGF-318 - Upgrade to Spring Framework 4.0.7. -* SGF-317 - Improve GemfireCache implementation to be able to build on Spring 4.1. -* SGF-316 - Update Spring Data GemFire Reference Guide with 1.5 changes (e.g. Auto Region Lookups, Region Templates). -* SGF-315 - Re-enable Bundlor plugin to create OSGi metadata. -* SGF-314 - Upgrade to Spring Framework 4.0.7. -* SGF-312 - The element in the SDG XSD does not properly support multiple PartitionListener bean definitions or references. -* SGF-311 - ClientRegionFactoryBean does not properly set the 'concurrency-checks-enabled' attribute and property of GemFire's ClientRegionFactory class. -* SGF-310 - The element is missing the 'concurrency-level' attribute, which is supported by GemFire's ClientRegionFactory API. -* SGF-307 - Remove all default values on strongly-typed Region elements in the SDG Schema in support of Region Templates. -* SGF-305 - Move to Asciidoctor for reference documentation. -* SGF-254 - Template Regions which can be used to reuse the same Region configuration for all Regions that reference it. -* SGF-223 - Ability to create directories on-the-fly at runtime based on explicitly defined Disk Stores disk directory locations. -* SGF-207 - No support for hierarchical, inherited Region attributes like there is in GemFire's cache.xml. -* SGF-191 - Provide automated way to add all Regions defined in GemFire's cache.xml as beans in the Spring context. - - -Changes in version 1.4.4.RELEASE (2014-08-27) ---------------------------------------------- -* SGF-308 - Release 1.4.4. -* SGF-304 - OnMembers function execution with Gemfire Group calls onMember (wrong method). - - -Changes in version 1.5.0.RC1 (2014-08-13) ------------------------------------------ -* SGF-306 - Release 1.5 RC1. -* SGF-304 - OnMembers function execution with Gemfire Group calls onMember (wrong method). -* SGF-291 - Upgrade Spring Data GemFire 1.5 to GemFire 8.0. -* SGF-227 - Ability to handle forced disconnects due to node failures with "Reconnect" functionality being added in GemFire. -* SGF-226 - Ability to request and get the member's configuration from a GemFire Locator/Manager using the cluster-wide configuration in the new Persistent Config feature. - - -Changes in version 1.4.2.RELEASE (2014-07-28) ---------------------------------------------- -* SGF-303 - Release 1.4.2. -* SGF-297 - Executing SDG Functions annotated POJO methods from Gfsh does not work when "injecting" arguments during Function argument resolution. -* SGF-295 - Enable Local Region Eviction action to be set to 'LOCAL_DESTROY', which is allowed in GemFire using the public API or in cache.xml. -* SGF-294 - Enable GemFire GatewayReceivers to be started manually, the same as for GatewaySenders using SDG. -* SGF-284 - Modify SDG build (build.gradle script) to include SDG validation and compatibility checks for Spring IO. - - -Changes in version 1.5.0.M1 (2014-07-10) ----------------------------------------- -* SGF-299 - Upgrade Spring Data GemFire 1.5 to Spring Framework 4.0.6. -* SGF-298 - Release 1.5 M1. -* SGF-297 - Executing SDG Functions annotated POJO methods from Gfsh does not work when "injecting" arguments during Function argument resolution. -* SGF-296 - Create spring-gemfire-1.5.xsd and spring-data-gemfire-1.5.xsd for SDG 1.5. -* SGF-295 - Enable Local Region Eviction action to be set to 'LOCAL_DESTROY', which is allowed in GemFire using the public API or in cache.xml. -* SGF-294 - Enable GemFire GatewayReceivers to be started manually, the same as for GatewaySenders using SDG. -* SGF-292 - Upgrade Spring Data GemFire 1.5 to Spring Framework 4.0.5.RELEASE. -* SGF-290 - SDG's Repository extension does not properly handle custom @Query annotated Repository methods returning non-Collection, non-Entity-based return values. -* SGF-215 - Ensure compatibility with Spring Framework 4.0.0.X. - - -Changes in version 1.4.1.RELEASE (2014-06-30) ---------------------------------------------- -* SGF-293 - Release 1.4.1. -* SGF-290 - SDG's Repository extension does not properly handle custom @Query annotated Repository methods returning non-Collection, non-Entity-based return values. -* SGF-288 - CacheServer's "maximum-time-between-pings" is set to ZERO. - - -Changes in version 1.4.0.RELEASE (2014-05-20) ---------------------------------------------- -* SGF-287 - Upgrade to Spring 3.2.9. -* SGF-286 - Release 1.4 GA. -* SGF-274 - Avoid the creation of temporary objects in the GemfireTemplate when used with Spring Data GemFire's Repository abstraction and extension. -* SGF-272 - Cleanup all Javadoc warnings. - - -Changes in version 1.4.0.RC1 (2014-05-02) ------------------------------------------ -* SGF-283 - Release 1.4 RC1. -* SGF-282 - The Eviction 'action', other than the default, for a PARTITION Region is not properly passed to the GemFire EvictionAttributes.createLRUEntryAttributes(..) factory method when the 'threshold' is not set. -* SGF-281 - Avoid setting the RegionAttributes Disk Store "Name" when the Region is neither "persistent" nor has an Eviction policy set to "OVERFLOW_TO_DISK". -* SGF-280 - The ContinuousQueryListenerContainer class is not Thread-safe!. -* SGF-279 - The element is missing the 'error-handler' attribute. -* SGF-278 - The ContinuousQueryListenerContainer class's 'taskExecutor' property is not set properly by the GemfireListenerContainerParser. -* SGF-277 - OQL Join in Repository interface. -* SGF-276 - LIKE operator does not work. -* SGF-275 - The element's 'phase' attribute is ignored. -* SGF-274 - Avoid the creation of temporary objects in the GemfireTemplate when used with Spring Data GemFire's Repository abstraction and extension. -* SGF-273 - OrderBy (static) and Sort parameter (dynamic) Repository Queries do not work!. -* SGF-271 - The element is missing the 'auto-startup' attribute. -* SGF-268 - Make it possible to run the build on Java 7 and/or Java 8. -* SGF-265 - Upgrade to the latest version GemFire (7.0.2). - - -Changes in version 1.4 M1 (2014-03-31) --------------------------------------- -* SGF-88 - Create Regions in Spring Context with Region Shortcuts -* SGF-132 - Being able to get cacheservers overall status on the client -* SGF-187 - Consider appending to the list of listener a new listener defined by another peer member -* SGF-201 - Create a Spring Boot Starter POM for Spring Data GemFire -* SGF-204 - The existing RegionFactoryBean does a lookup of a Region before trying to create one. -* SGF-209 - GemfireTemplate creates a temporary object for every operation. -* SGF-210 - GemfireRepository requires that there be an attribute in the entity class for the key. -* SGF-225 - Inconsistent data policy defaults for subregions that are replicated regions -* SGF-230 - Cannot specify a Disk Store to be used for overflow on a Gateway Sender without enabling persistence. -* SGF-231 - Unable to specify Ordering Policy for Serial GW Sender -* SGF-232 - Unable to specify Order Policy for Serial Async Event Queue -* SGF-233 - Cannot specify a Disk Store to be used for overflow on an Async Event Queue without enabling persistence. -* SGF-234 - The docs indicate that the PDX attribute pdx-persistent defaults to true, however this does not seem to be the case. -* SGF-235 - NPE in DefaultFunctionArgumentResolver.resolveFunctionArguments(30) when a Function has no arguments and none are provided. -* SGF-238 - "jndi-prop" is not parced correctly -* SGF-239 - The value "XaPooledDataSource" of jndi-binding "type" attribute should be changed to "XAPooledDataSource" -* SGF-240 - XML schema type restrictions should be avoided in order to support placeholders (al types should be xs:string) -* SGF-242 - When defining "membership-attributes" for a Region, the bean definition "required-roles" attribute is required and, when specified, causes a BeanCreationException in the Spring container during initialization. -* SGF-244 - The nested , element is missing the ref attribute in the XSD. -* SGF-245 - always creates cache with default values ignoring all the specified attributes -* SGF-246 - execute function always assumes arguments are passed -* SGF-247 - boolean based repository queries generate UnsupportedOperationException in non PDX serialized entities -* SGF-249 - The SDG XSD is restricting the use of property placeholder values on , compaction-threshold attributes given the attribute type is a short and not string. -* SGF-251 - Creating and using GemFire Repositories based on the Spring Data Commons Repository abstraction does not work properly for domain objects stored in Subregions. -* SGF-252 - Spring GemFire's Repository extension does not properly handle multiple, identically named Subregions for persisting corresponding application domain objects associated by way of the @Region annotation. -* SGF-255 - The element's 'threshold' attribute is required even when the Eviction type is 'HEAP_PERCENTAGE'. -* SGF-258 - The SDG XML namespace element is missing the 'data-policy' attribute. -* SGF-263 - The 'disk-synchronous' Region attribute does not get successfully applied when explicitly set to false. -* SGF-236 - Sub-Region Bean names require prepended "/" (vs. previous use of gfe:lookup-region for sub-regions) -* SGF-241 - Add support for defining client sub-Regions using nested SDG XML namespace elements. -* SGF-248 - Ability to bootstrap a Spring context inside a GemFire Server JVM process by starting the GemFire Server with Gfsh. -* SGF-256 - Upgrade to the latest version of the Spring Framework (3.2.8) and Spring Data Commons (1.8.0) -* SGF-257 - Specify strict type rules in the Spring Data GemFire XSD for peer Region 'data-policy' and 'shortcut' attributes as currently enforced by the element's 'shortcut' attribute. -* SGF-259 - Handle cyclic bean dependencies in SDG XML config between Async Event Queues and Async Event Listeners. -* SGF-260 - Add the ability to set @Id to a method name. -* SGF-261 - Add ability to persist application domain objects (entities) to multiple Regions in a GemFire Cache. -* SGF-265 - Upgrade to the latest version GemFire (7.0.2) -* SGF-266 - Release 1.4 M1 - - -Changes in Version 1.3.4 (2014-04-04) -------------------------------------- -General - * This is a maintenance/patch release to address bugs and other minor improvements. -Bugs - * [SGF-235] - NPE in DefaultFunctionArgumentResolver.resolveFunctionArguments(30) when a Function has no arguments and none are provided. - * [SGF-238] - "jndi-prop" is not parced correctly. - * [SGF-239] - The value "XaPooledDataSource" of jndi-binding "type" attribute should be changed to "XAPooledDataSource". - * [SGF-240] - XML schema type restrictions should be avoided in order to support placeholders (al types should be xs:string). - * [SGF-246] - execute function always assumes arguments are passed. - * [SGF-249] - The SDG XSD is restricting the use of property placeholder values on , compaction-threshold attributes given the attribute type is a short and not string. - * [SGF-255] - The element's 'threshold' attribute is required even when the Eviction type is 'HEAP_PERCENTAGE'. -Improvements - * Upgrades SDG to Spring Framework 3.2.8 and Spring Data Commons 1.7.1. - - -Changes in Version 1.3.3 (2013-11-13) -------------------------------------- -General - * This is a maintenance/patch release to address bugs and other minor improvements. - * See [1.3.3 release notes](https://jira.springsource.org/secure/ReleaseNote.jspa?projectId=10462&version=14257). -Bugs - * [SGF-174] - DynamicRegion usage causes ApplicationContext to fail to load when using non-dynamic parent - * [SGF-178] - parent attribute causes endless loop in hashCode - * [SGF-194] - Nested region do not work - * [SGF-195] - colocated-with fails on partition region - * [SGF-197] - A Cache (Region) created using Spring configuration with persistent PDX keys fails to start. - * [SGF-198] - BeanCurrentlyInCreationException when injecting async-event-queue to a Gemfire replicated region - * [SGF-200] - Extra unnecessary directory for disk store created when an embedded sender starts up - * [SGF-203] - The treatment of 'persistence' is wrong. - * [SGF-211] - Property placeholders don't work for copies attribute on partitioned-region - * [SGF-216] - FunctionContextInjectingArgumentResolver only injects arguments for RegionFunctionContext - * [SGF-217] - When configuring CacheServer with a Disk Store (used for client subscription queue overflow), the Cache Server fails to start up with an error. - * [SGF-218] - The Eviction Policy on Client Subscription when configuring a GemFire Cache Server is not being properly set; always defaults to "NONE". - * [SGF-219] - Unable to register GemFire CacheListeners on SubRegions. - * [SGF-220] - Unable to register GemFire Gateway Senders on SubRegions. - * [SGF-221] - Unable to register GemFire Async Event Listeners on SubRegions. -Improvements - * [SGF-214] - OnMembersFunctionExecutionTemplate constructors should be public -New Features - * [SGF-193] - concurrency-checks-enabled is not supported in SGF. - * [SGF-206] - CacheLoader and CacheWriter are not supported on client local regions. - - -Changes in Version 1.3.2 (2013-08-06) --------------------------------------- -General -* This is a patch release to address bugs and minor enhancements -see [1.3.2 release notes](https://jira.springsource.org/secure/ReleaseNote.jspa?version=14219&projectId=10462) - -** Bug - * [SGF-168] - Race condition when using Spring data gemfire with tc Server parallel deployment - * [SGF-176] - Missing Functionality: time to live and entry idle time on a local client region - * [SGF-185] - @OnServers fails when pool attribute is set - cannot specify both pool and cache - * [SGF-186] - BeanFactoryLocator reports cache already exists when ClientCache, Pool, and Functions are configured - * [SGF-188] - Documentation mistake - * [SGF-189] - Spring Gemfire does not allow persistence for a local region even though this is supported in Gemfire - * [SGF-192] - client region ignores destroy and close settings - -** Improvement - * [SGF-180] - If nothing references the cache bean it doesn't get initialized - * [SGF-183] - Little or no logging in Spring Gemfire - -Changes in version 1.3.1.RELEASE(2013-04-18) -** Bug - * [SGF-159] - isRollbackOnCommitFailure flag is ignored by GemfireTransactionManager when transaction fails. - * [SGF-169] - Unidirectional Gateway hubs cannot be created and fail with an exception - * [SGF-173] - Function Execution throws exception on void return. - - -Changes in version 1.3.0.RELEASE (2013-03-14) ---------------------------------------------- -General -* Added annotation support for GemFire functions -* Added 'datasource' element to gfe-data namespace to simplify client connection -* Added support for JSON -See [1.3.0.M1 release notes](https://jira.springsource.org/secure/ReleaseNote.jspa?projectId=10462&version=13300) -See [1.3.0 release notes](https://jira.springsource.org/secure/ReleaseNote.jspa?projectId=10462&version=14023) - - -Changes in version 1.2.1.RELEASE (2012-10-26) ---------------------------------------------- -General -* Upgraded to GemFire 7.0 -* Added support for GemFire 7.0 WAN Configuration - - -Changes in version 1.2.0.RELEASE (2012-08-15) ---------------------------------------------- -General -* Added support for Spring Data repositories -* The Spring Data GemFire project, formerly Spring GemFire, is now a component of the Spring Data project -* Upgraded to Spring 3.1.2.RELEASE -* Upgraded to Spring Data Commons 1.4.0.RELEASE -* The XML namespace provides support for everything that can be configured natively with Cache XML -* A separate XML namespace has been created for Spring Data Repository support - -Enhancements -* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config -* [SGF-75] - Ability to define gateways in the Spring GemFire namespace -* [SGF-76] - Disk store should be its own bean -* [SGF-79] - Missing gateway attributes for regions -* [SGF-86] - Make instance variables protected in CacheFactoryBean -* [SGF-95] - Add namespace support for subregions -* [SGF-98] - Provide namespace support for all cache and region properties -* [SGF-102] - Add support for JavaConfig for repositories -* [SGF-103] - Replace xsd:id type with xsd:string to support Spring environment profiles -* [SGF-104] - The repository deleteAll() method only works for replicated regions -* [SGF-109] - Separate repository support into its own namespace -* [SGF-111] - Change default bean names from hyphenated to camel case to support @Autowired -* [SGF-112] - Repositories should reject PagingAndSorting and Pageable parameters -* [SGF-113] - Repositories should support single entities returned from a query method -* [SGF-115] - Add support for 'Like', 'StartsWith','EndsWith', and 'Containing' repository queries - -Bug Fixes -* [SGF-85] - Pdx disk store does not work when trying to references a disk store created in cache.xml -* [SGF-89] - Continuous query container fails when implementing the ContinuousQueryListener interface -* [SGF-101] - The repository deleteAll() method only works for replicated regions - - -Changes in version 1.1.2.RELEASE (2012-07-04) ---------------------------------------------- -General -* Upgraded to GemFire 6.6.3 - -Package org.springframework.data.gemfire.config -* Fixed incorrect parsing of pdx-disk-store attribute - - -Changes in version 1.1.1.RELEASE (2012-03-20) ---------------------------------------------- -General -* Upgraded to GemFire 6.6.2 -* Upgraded to Spring Framework 3.1.1 GA - -Package org.springframework.data.gemfire -* Fixed incorrect parsing of pdx-serializer (from value to reference) -* Fixed incorrect parsing of use-bean-factory-locator -* Fixed GemfireTransactionCommitException class hierarchy -* Improved handling of GemFire 6.5+ transaction exceptions - -Package org.springframework.data.gemfire.client -* Fixed bug that caused client namespace to create only local regions - - -Changes in version 1.1.0.RELEASE (2011-12-14) ---------------------------------------------- -General -* Upgraded to Spring Framework 3.1 GA - - -Changes in version 1.1.0.RC1 (2011-11-13) ------------------------------------------ -General -* Upgraded to GemFire 6.6.1 -* Aligned Maven naming to Spring Data conventions (changed ids to 'org.springframework.data'/'spring-data-gemfire') -* Introduced PDX options for 'cache' and 'client-cache' elements - - -Changes in version 1.1.0.M3 (2011-09-25) ----------------------------------------- -General -* Upgraded to GemFire 6.6 GA -* Introduced support for GemFire Indecies -* Reintroduced samples in zip distribution - -Package org.springframework.data.gemfire -* Improved region creation by removing the use of GemFire 6.0 API (replaced with 6.5+) - -Package org.springframework.data.gemfire.client -* Added missing properties to PoolFactoryBean and pool namespace -* Fixed registration of custom listeners specified through region attributes -* Added missing 'receive-values' property to region interests - - -Changes in version 1.1.0.M2 (2011-08-29) ----------------------------------------- -General -* Introduced support for GemFire Continuous Query (CQ) -* Introduced support for client cache -* Introduced namespace support for region expiration attributes - -Package org.springframework.data.gemfire -* Added find methods (based on the query service) inside GemFireTemplate -* Improved detection of local client regions without pools configured - -Package org.springframework.data.gemfire.server -* Fixed bug occuring when applying defaults for disk stores -* Delayed CacheServer start up to allow declared regions to properly initialize - - -Changes in version 1.1.0.M1 (2011-07-20) ----------------------------------------- -General -* Changed build system to Gradle -* Added support for GemFire 6.6 -* Dropped support for GemFire 6.0 (GemFire 6.5 or higher required) -* Introduced support for CacheServer -* Introduced GemFire implementation for Spring 3.1 cache abstraction -* Upgraded to Spring Framework 3.1 M2 - -Package org.springframework.data.gemfire -* Introduced cache option for disabling bean factory locator; useful for multi cache definitions, in the same VM -* Added more region methods to GemfireTemplate -* Introduced support for queries with variable parameters in GemfireTemplate -* Improved handling of optimistic exception in a transaction scenario - - -Changes in version 1.0.1 (2011-04-26) -------------------------------------- -General -* Upgraded to GemFire 6.5.1.4 -* Fix networking issue with the sample on some Linux distributions (Ubuntu) -* Loosen type constraints in the schema to allow placeholders -* Added 'statistics' attribute to all write regions - -Package org.springframework.data.gemfire -* Introduced auto-close (configurable) on RegionFactoryBean - -Package org.springframework.data.gemfire.config -* Fixed bug causing region names to be used as aliases for region beans - -Package org.springframework.data.gemfire.client -* Improved dependency initialization between cache and pools - -Package org.springframework.data.gemfire.serialization -* Improved cache-wide registration of custom instantiators - -Package org.springframework.data.gemfire.support -* Introduced GemfireDaoSupport - - -Changes in version 1.0.0 (2011-02-02) -------------------------------------- - - -Changes in version 1.0.0.RC1 (2010-12-20) ------------------------------------------ -General -* Upgraded to GemFire 6.5.1 -* Upgraded to Spring 3.0.5 - - -Changes in version 1.0.0.M2 (2010-12-08) ----------------------------------------- -General -* Introduced namespace for all the major SGF components -* Improved documentation to accomodate the SGF namespace - -Package org.springframework.data.gemfire -* Introduced RegionLookupFactoryBean for retrieving (but not creating) regions - -Package org.springframework.data.gemfire.client -* Refactored client-specific classes into a dedicated package -* Introduced support for configuring GemFire Pools - - -Changes in version 1.0.0.M1 (2010-08-03) ----------------------------------------- -General -* Configuration support for GemFire Cache, Region -* Exception translation -* GemFire Template for exception translation -* Declarative transaction management -* Auto-generation of non-reflection based GemFire instantiators