diff --git a/docs/src/reference/docbook/reference/bootstrap.xml b/docs/src/reference/docbook/reference/bootstrap.xml index 426ea18a..8cb75187 100644 --- a/docs/src/reference/docbook/reference/bootstrap.xml +++ b/docs/src/reference/docbook/reference/bootstrap.xml @@ -3,7 +3,10 @@ xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" - > + xmlns:ns5="http://www.w3.org/2000/svg" + xmlns:ns4="http://www.w3.org/1998/Math/MathML" + xmlns:ns3="http://www.w3.org/1999/xhtml" + xmlns:ns="http://docbook.org/ns/docbook"> Bootstrapping GemFire through the Spring Container Spring Data GemFire provides full configuration and initialization of @@ -25,32 +28,41 @@ cache.xml As of release 1.2.0, Spring Data GemFire's XML namespace - supports full configuration of the data grid. In fact, the Spring - namespace is considered the preferred way to configure GemFire. GemFire - will continue to support cache.xml for legacy - reasons, but you 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, SpEL, and environment profiles. - Behind the namespace, Spring Data GemFire makes extensive use of Spring's - FactoryBean pattern to simplify the - creation and initialization of GemFire components. + supports full configuration of the data grid. In fact, the Spring Data + GemFire namespace is considered the preferred way to configure GemFire. + GemFire will continue to support native + cache.xml + for legacy reasons, but you 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, SpEL, and + environment profiles. Behind the namespace, Spring Data GemFire makes + extensive use of Spring's FactoryBean + pattern to simplify the creation and initialization of GemFire + components. For example, GemFire provides several callback interfaces - such as CacheListener, - CacheWriter, - CacheLoader to allow developers to add - custom event handlers. Using the Spring IoC container, these may - configured as normal Spring beans and injected into GemFire components. - This is a significant improvement over 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 DI container). + such as + CacheListener + , + CacheWriter + , + CacheLoader + to allow developers to add custom event handlers. Using + the Spring IoC container, these may 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 DI container). In addition, IDEs such as the Spring Tool Suite (STS) provide excellent support for Spring XML namespaces, such as code completion, pop-up annotations, and real time validation, making them easy - to use. + to use.
@@ -58,7 +70,7 @@ To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components. It is also possible - to configure the beans directly through Springs standard <bean> + to configure the beans directly through Spring's standard <bean> definition. However, as of Spring Data GemFire 1.2.0, all bean properties are exposed via the namespace so there is little benefit to using raw bean definitions. For more information about XML Schema-based configuration in @@ -73,7 +85,7 @@ To use the Spring Data GemFire namespace, simply declare it in your - Spring XML configuration: + Spring XML configuration meta-data: <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" @@ -193,7 +205,10 @@ cache declaration but one can customize it accordingly or use a pool (if need be) - see the namespace schema for the full set of options.
- - - + + + + + + diff --git a/docs/src/reference/docbook/reference/region.xml b/docs/src/reference/docbook/reference/region.xml index 7246d317..93a83244 100644 --- a/docs/src/reference/docbook/reference/region.xml +++ b/docs/src/reference/docbook/reference/region.xml @@ -10,9 +10,9 @@ Configuring a GemFire Region A region is required to store and retrieve data from the - cache. Region is an interface extends - java.util.map used to perform basic data - access using familiar key-value semantics. 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 @@ -42,11 +42,11 @@ 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. + 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. @@ -60,10 +60,10 @@
Using an externally configured Region - For referencing Regions already configured through GemFire native + For referencing regions already configured through GemFire native configuration, e.g., a cache.xml file, use the lookup-region element. Simply declare the target region - name with the name attribute; for example to declare a + 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 definition: @@ -161,7 +161,8 @@ close - boolean, default:false (Note: The default was true prior to 1.3.0) + boolean, default:false (Note: The default was true + prior to 1.3.0) Indicates whether the region @@ -358,7 +359,7 @@ using the cache-listener element enclosed in a *-region element. In the example below, there are two CacheListeners declared. The first - references a top level named Spring bean; the second is an anonymous + references a top-level named Spring bean; the second is an anonymous inner bean definition. <gfe:replicated-region id="region-with-listeners"> <gfe:cache-listener> @@ -370,7 +371,7 @@ <bean id="c-listener" class="some.pkg.SimpleCacheListener"/> </gfe:replicated-region> - The following example uses an alternate form of the + 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 @@ -418,9 +419,9 @@ 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 - source, a database for example. A - CacheWriter is invoked afer an entry is - created or updated,intended for synchronizing to an external data + data source, a database for example. A + CacheWriter is invoked after 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. See - With Spring Data GemFire, to enable persistence, simply set the + To enable persistence with Spring Data GemFire, simply set the persistent attribute to true: <gfe:partitioned-region id="persitent-partition" persistent="true"/> @@ -486,6 +487,21 @@ initialization exception. + Persistence may also be configured using the + data-policy attribute, set to one of GemFire's + data policy settings. For instance... + + + <gfe:partitioned-region id="persitent-partition" data-policy="PERSISTENT_PARTITION"/> + + + 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. @@ -497,24 +513,28 @@ This is discussed further in
-
+ +
Subscription Interest Policy - GemFire allows configuration of subscriptions to control peer to peer event handling. - Spring Data GemFire provides a <gfe:subscription/> to set the interest policy on replicated and partitioned regions to either ALL or CACHE_CONTENT. - + GemFire allows configuration of subscriptions to control peer + to peer event handling. Spring Data GemFire provides a + <gfe:subscription/> to set the interest policy on + replicated and partitioned regions to either ALL or + CACHE_CONTENT. <gfe:partitioned-region id="subscription-partition"> <gfe:subscription type="CACHE_CONTENT"/> </gfe:partitioned-region>
+
Data Eviction and Overflowing 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 LRU). Evicted entries are either destroyed or paged to disk (also known as overflow). @@ -537,9 +557,9 @@ information. - When configuring regions for oveflow, it is recommended to configure - the storage through the disk-store element for maximum - efficiency. + 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 - 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 GemFire provides <region-ttl>, <region-tti>, <entry-ttl> and <entry-tti> region child elements to specify @@ -619,7 +639,7 @@ Partitioned Region Another region type supported out of the box by the Spring Data - GemFire namespace, is the partitioned region. To quote the GemFire + GemFire namespace is the partitioned region. To quote the GemFire docs: "A partitioned region is a region where data is divided between peer @@ -790,7 +810,7 @@ and a nested resolver declaration --> client region while the latter defines connection pools to be used/shared by the various client regions. - Below is a typical client region configuration:G + Below is a typical client region configuration: <!-- client region using the default client-cache pool --> <gfe:client-region id="simple"> @@ -810,8 +830,9 @@ and a nested resolver declaration --> </gfe:pool> As with the other region types, client-region - supports CacheListeners (but not - CacheLoaders or CacheWriters). It also requires a connection + supports CacheListeners + 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. @@ -860,28 +881,43 @@ and a nested resolver declaration --> JSON Support Gemfire 7.0 introduced support for caching JSON documents with OQL - query support. These are stored internally as PdxInstance types using the - JSONFormatter to perform conversion to and from JSON strings. Spring Data - GemFire provides a <gfe-data:json-region-autoproxy/> tag to enable a - Spring AOP component to advise appropropriate 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. - - - By default, <gfe-data:json-region-autoproxy/> 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. - 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<java.util.Map.Entry<?,?>> is not affected. - - + query support. These are stored internally as PdxInstance + types using the JSONFormatter + to perform conversion to and from JSON strings. Spring Data GemFire + provides a <gfe-data:json-region-autoproxy/> tag to + enable a Spring + AOP component to advise appropropriate 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. + + By default, <gfe-data:json-region-autoproxy/> 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. + 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<java.util.Map.Entry<?,?>> is not affected. + + <gfe-data:json-region-autoproxy pretty-print="true" region-refs="myJsonRegion" convert-returned-collections="true"/> - 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 with seamlessly with GemfireTemplate + operations, provided that the template is declared as a Spring bean. + Currently native QueryService operations are not supported.