From e8389b6491ea8068f8763cbb3e2f71d09c771a73 Mon Sep 17 00:00:00 2001 From: John Blum Date: Mon, 30 Jul 2018 18:02:49 -0700 Subject: [PATCH] DATAGEODE-135 - Polish SDG Reference Guide Edits. --- .../asciidoc/introduction/new-features.adoc | 9 ++- .../reference/bootstrap-annotations.adoc | 44 ++++++++------- src/main/asciidoc/reference/cache.adoc | 4 +- src/main/asciidoc/reference/introduction.adoc | 8 +-- src/main/asciidoc/reference/region.adoc | 56 ++++++++++++++++--- 5 files changed, 85 insertions(+), 36 deletions(-) diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index 8ee04620..3e6fdec9 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -177,10 +177,13 @@ and server when using JavaConfig. * Added support in the Annotation configuration model for Off-Heap, Redis Adapter, and {data-store-name}'s new Security framework. -[[new-in-2-1-0] +[[new-in-2-1-0]] == New in the 2.1 Release -* Upgraded to {data-store-name} 9.5.1. +* Upgraded to {data-store-name} {data-store-version}. * Upgraded to Spring Framework 5.1.0.RELEASE. * Upgraded to Spring Data Commons 2.1.0.RELEASE. -* +* Added support for parallel cache/Region snapshots along with invoking callbacks when loading snapshots. +* Added support for registering QueryPostProcessors to customize the OQL generated fro Repository query methods. +* Added support for include/exclude TypeFilters in o.s.d.g.mapping.MappingPdxSerializer. +* Updated docs. diff --git a/src/main/asciidoc/reference/bootstrap-annotations.adoc b/src/main/asciidoc/reference/bootstrap-annotations.adoc index 95069b0d..9b0cda30 100644 --- a/src/main/asciidoc/reference/bootstrap-annotations.adoc +++ b/src/main/asciidoc/reference/bootstrap-annotations.adoc @@ -16,12 +16,13 @@ and as _easily_ as possible. and different configuration options: * {x-data-store-javadoc}[Java API] -* {x-data-store-docs}/reference/topics/chapter_overview_cache_xml.html[cache.xml] +* {x-data-store-docs}/reference/topics/chapter_overview_cache_xml.html[`cache.xml`] * {x-data-store-docs}/tools_modules/gfsh/chapter_overview.html[_Gfsh_] -with {x-data-store-docs}/configuring/chapter_overview.html[cluster configuration] -* <>) +with {x-data-store-docs}/configuring/chapter_overview.html[Cluster Configuration] +* <> + +Further complexity arises from the different supported topologies: -Further complexity comes from the different supported topologies: * ({x-data-store-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] * {x-data-store-docs}/topologies_and_comm/p2p_configuration/chapter_overview.html[P2P] * {x-data-store-docs}/topologies_and_comm/multi_site_configuration/chapter_overview.html[WAN]) @@ -56,7 +57,7 @@ and {sdg-name}'s annotation-based configuration quietly backs away. You need onl you wish to adjust. Also, as we will see later in this document, there are several ways to configure a {data-store-name} feature or embedded service by using the annotations. -You can find all the new SDG Java Annotations in the `org.springframework.data.gemfire.config.annotation` package. +You can find all the new SDG Java `Annotations` in the `org.springframework.data.gemfire.config.annotation` package. [[bootstrap-annotation-config-geode-applications]] == Bootstrapping {data-store-name} Applications with Spring @@ -140,9 +141,10 @@ The most common and recommended approach is to use {data-store-name} Locators. NOTE: A cache client can connect to one or more Locators in the {data-store-name} cluster instead of directly to a `CacheServer`. The advantage of using Locators over direct `CacheServer` connections is that Locators provide metadata about the cluster to which the client is connected. This metadata includes information such as which servers contain -the data of interest or which servers have the least amount of load. A Locator also provides fail-over capabilities -in case a `CacheServer` crashes. By enabling the PR single-hop feature in the client `Pool`, the client is routed -directly to the server containing the data requested and needed by the client. +the data of interest or which servers have the least amount of load. A client `Pool` in conjuction with a Locator +also provides fail-over capabilities in case a `CacheServer` crashes. By enabling the `PARTITION` Region (PR) +single-hop feature in the client `Pool`, the client is routed directly to the server containing the data requested +and needed by the client. NOTE: Locators are also peer members in a cluster. Locators actually constitute what makes up a cluster of {data-store-name} nodes. That is, all nodes connected by a Locator are peers in the cluster, and new members use Locators to join a cluster @@ -474,12 +476,11 @@ The following example shows a nested property being set in Java: .Property placehodler nesting [source, java] ---- - @Bean - CacheServerConfigurer cacheServerPortConfigurer( - @Value("${gemfire.cache.server.port:${some.other.property:40404}}") int cacheServerPort) { - - ... - } +@Bean +CacheServerConfigurer cacheServerPortConfigurer( + @Value("${gemfire.cache.server.port:${some.other.property:40404}}") + int cacheServerPort) { + ... } ---- @@ -1010,9 +1011,9 @@ The following example shows how to configure the same Region bean in XML: .Example Region bean definition using {sdg-acronym}'s XML Namespace [source, xml] ---- - - ... - + + ... + ---- While neither Java nor XML configuration is all that difficult to specify, either one can be cumbersome, especially if @@ -2193,14 +2194,15 @@ in the Spring container, intercepting the Region operation and logging the event == Conclusion As we learned in the previous sections, {sdg-name}'s new annotation-based configuration model provides a tremendous -amount of power. Hopefully, it lives up to its goal of making it easier for you to get started quickly and easily +amount of power. Hopefully, it lives up to its goal of making it easier for you to _get started quickly_ and _easily_ when using {data-store-name} with Spring. Keep in mind that, when you use the new annotations, you can still use Java configuration or XML configuration. You can even combine all three approaches by using Spring's {spring-framework-javadoc}/org/springframework/context/annotation/Import.html[`@Import`] and {spring-framework-javadoc}/org/springframework/context/annotation/ImportResource.html[`@ImportResource`] -annotations on a Spring `@Configuration` or `@SpringBootApplication` class. The moment you explicitly provide a bean definition -that would otherwise be provided by {sdg-name} by using an annotation, the annotation-based configuration backs away. +annotations on a Spring `@Configuration` or `@SpringBootApplication` class. The moment you explicitly provide +a bean definition that would otherwise be provided by {sdg-name} using 1 of the annotations, the annotation-based +configuration backs away. [NOTE] ==== @@ -2219,3 +2221,5 @@ The annotations were not meant to handle every situation. The annotations were m as _quickly_ and as _easily_ as possible, especially during development. We hope you will enjoy these new capabilities! + +include::{basedocdir}/reference/bootstrap-annotations-quickstart.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index 29b1335a..f2663e85 100644 --- a/src/main/asciidoc/reference/cache.adoc +++ b/src/main/asciidoc/reference/cache.adoc @@ -296,8 +296,8 @@ to support externalization of environment-specific properties from the main code NOTE: To avoid initialization problems, the `CacheServer` started by {sdg-name} starts *after* the Spring container has been fully initialized. Doing so lets potential Regions, listeners, writers or instantiators that are defined -declaratively 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 +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 before your components and thus not be seen by the clients connecting right away. [[bootstrap:cache:client]] diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc index 4cf08c6d..6c1bcb98 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -20,11 +20,11 @@ stored in {data-store-name} by using basic CRUD and simple query operations. to perform distributed computations where the data lives. * <> describes how to use {data-store-name}'s Continuous Query (CQ) functionality -to process a stream of events based on interest defined and registered using {data-store-name}'s -OQL (Object Query Language) query. +to process a stream of events based on interest that is defined and registered with {data-store-name}'s +OQL (Object Query Language). -* <> describes how to bootstrap a Spring `ApplicationContext` running in an {data-store-name} server -using `Gfsh`. +* <> describes how to configure and bootstrap a Spring `ApplicationContext` +running in an {data-store-name} server using `Gfsh`. * <> describes the examples provided with the distribution to illustrate the various features available in {sdg-name}. diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index 1458652e..35ae32db 100644 --- a/src/main/asciidoc/reference/region.adoc +++ b/src/main/asciidoc/reference/region.adoc @@ -348,11 +348,11 @@ in the {data-store-name} documentation for more details. [[bootstrap:region:compression]] == Compression -{data-store-name} Regions may also be compressed in order to reduce JVM memory consumption and pressure -to possibly avoid global GCs. When you enable compression for a Region, all values stored in memory for the Region -are compressed, while keys and indexes remain uncompressed. New values are compressed when put into the Region -and all values are decompressed automatically when read back from the Region. Values are not compressed when -persisted to disk or when sent over the wire to other peer members or clients. +{data-store-name} Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly +avoid global GCs. When you enable compression for a Region, all values stored in memory for the Region are compressed, +while keys and indexes remain uncompressed. New values are compressed when put into the Region and all values +are decompressed automatically when read back from the Region. Values are not compressed when persisted to disk +or when sent over the wire to other peer members or clients. The following example shows a Region with compression enabled: @@ -370,6 +370,48 @@ The following example shows a Region with compression enabled: See {data-store-name}'s documentation for more information on {x-data-store-docs}/managing/region_compression/region_compression.html[Region Compression]. +[[bootstrap:region:off-heap]] +== Off-Heap + +{data-store-name} Regions may also be configured to store Region values in off-heap memory, which is a portion of +JVM memory that is not subject to Garbage Collection (GC). By avoid expensive GC cycles, your application +can spend more of its time on things that matter, like processing requests. + +Using off-heap memory is as simple as declaring the amount of memory to use and then enabling your Regions +to use off-heap memory, as shown in the following configuration: + +[source,xml] +---- + + 200G + + + + + +---- + +You can control other aspects of off-heap memory management by setting the following {data-store-name} configuration +properties using the `<gfe:cache>` element:s + +[source,xml] +---- + +---- + +{data-store-name}'s `ResourceManager` will use these two threshold values (`critical-off-heap-percentage` +& `eviction-off-heap-percentage`) to more effectively manage the off-heap memory in much the same way +as the JVM does when managing heap memory. {data-store-name} `ResourceManager` will prevent the cache +from consuming too much off-heap memory by evicting old data. If the off-heap manager is unable to keep up, +then the `ResourceManager` refuses additions to the cache until the off-heap memory manager has freed up +an adequate amount of memory. + +See {data-store-name}'s documentation for more information on +{x-data-store-docs}/managing/heap_use/heap_management.html[Managing Heap and Off-Heap Memory]. + +Specifically, read the section, +{x-data-store-docs}/managing/heap_use/off_heap_management.html[Managing Off-Heap Memory]. + [[bootstrap:region:subregions]] == Subregions @@ -1032,7 +1074,7 @@ meaning there is no redundancy. Each copy provides extra backup at the expense o | The maximum amount of memory (in megabytes) used by the region in *this* process. | total-max-memory -| *any integer value* +| any integer value | The maximum amount of memory (in megabytes) used by the region in *all* processes. | partition-listener @@ -1049,7 +1091,7 @@ meaning there is no redundancy. Each copy provides extra backup at the expense o -1 (the default) indicates that redundancy is not recovered after a failure. | startup-recovery-delay -| *any long value* +| any long value | The delay in milliseconds that new members wait before satisfying redundancy. -1 indicates that adding new members does not trigger redundancy recovery. The default is to recover redundancy immediately when a new member is added.