From 7aa6c051b64b33fd11ab0d8509d4cff137e94e68 Mon Sep 17 00:00:00 2001 From: costin Date: Thu, 16 Sep 2010 12:20:27 +0300 Subject: [PATCH] SGF-10 SGF-19 + add section on replicated and partitioned regions --- docs/src/docbkx/reference/bootstrap.xml | 253 +++++++++++++++++++++++- 1 file changed, 247 insertions(+), 6 deletions(-) diff --git a/docs/src/docbkx/reference/bootstrap.xml b/docs/src/docbkx/reference/bootstrap.xml index 4783fc5b..191cdf23 100644 --- a/docs/src/docbkx/reference/bootstrap.xml +++ b/docs/src/docbkx/reference/bootstrap.xml @@ -192,14 +192,19 @@ Once the Cache is configured, one needs to configure one or more Regions to interact with the data fabric. SGF allows various region types to be configured and created directly from Spring or - in case they are created directly in GemFire, retrieved as such. + in case they are created directly in GemFire, retrieved as such. + + For more information about the various region types and their capabilities as well as configuration options, please + refer to the GemFire Developer's Guide and community + site.
Using an externaly configured <interfacename>Region</interfacename> - For consuming but not creating Regions, one can use the - lookup element. Simply declare the target region name the - name attribute, for example to declare a bean definition, named region-bean + For consuming but not creating Regions (for example in case, + the regions are already configured through GemFire native configuration, the cache.xml), + one can use the lookup-region element. Simply declare the target region name 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: ]]> @@ -207,11 +212,247 @@ If the name is not specified, the bean name will be used automatically. The example above becomes: - + ]]> - CONTINUE DOC HERE + If the region does not exist, an initialization exception will be thrown. See the section below + on how to configure GemFire regions. + + Note that in the previous examples, since no cache name was defined, the default SGF naming convention (gemfire-cache) + was used. If that is not an option, one can point to the cache bean through the cache-ref attribute: + + + + +]]> + + The lookup-region provides a simple way of retrieving existing, pre-configured regions without exposing + the region semantics or setup infrastructure.
+ +
+ Configuring a GemFire replicated region + + One of the common region types supported by GemFire is replicated region or replica. In short: + + What is a replica? + When a region is configured to be a replicated region, every member that hosts that region stores a copy of the contents of the region 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 replicas. + + + SGF offers a dedicated element for creating replicas in the form of replicated-region element. A minimal declaration looks as follows + (again, the example will not setup the cache wiring, relying on the SGF namespace naming conventions): + + ]]> + + Here, a replicated region is created (if one doesn't exist already). The name of the region is the same as the bean name (simple-replica) and + the bean assumes the existence of a GemFire cache named gemfire-cache. + + When setting a region, it's fairly common to associate various CacheLoaders, CacheListeners and + CacheWriters with it. These components can be either referrenced or declared inlined by the region declaration. + + + Following the GemFire recommandations, the namespace allows for each region created multiple listeners but only one + cache writer and cache loader. This restriction can be relaxed, for advanced usages by using the beans declaration (see the next section). + + + Below is an example, showing both styles: + + + + + + + + + + + + +]]> + + Using ref and a nested declaration on cache-listener, cache-loader or cache-writer + is illegal. The two options are mutually exclusive and using them at the same time, on the same element will throw an exception. + +
+ <literal>replicated-region</literal> Options + + The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the + replicated-region element. Please see the storage and eviction section for the relevant configuration. + + + <![CDATA[replicated-region]]> options + + + + + + + Name + Values + Description + + + + + id + any valid bean name + The id of the region bean definition. + + + name + any valid region name + The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name). + + + cache-ref + GemFire cache bean name + The name of the bean defining the GemFire cache (by default 'gemfire-cache'). + + + cache-listener + valid bean name or definition + The name or nested bean declaration of a GemFire CacheListener. + + + cache-loader + valid bean name or definition + The name or nested bean declaration of a GemFire CacheLoader. + + + cache-writer + valid bean name or definition + The name or nested bean declaration of a GemFire CacheWriter. + + + +
+
+ +
+ +
+ Configuring a GemFire partition(ed) region + + Another region type supported out of the box by the SGF namespace, is the partitioned region. To quote again the GemFire docs: + + What is a partition? + 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. + + A partition can be created by SGF through 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: + + + + + + +]]> + +
+ <literal>partitioned-region</literal> Options + + The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the + partition element. Please see the storage and eviction section for the relevant configuration. + + + <![CDATA[partitioned-region]]> options + + + + + + + Name + Values + Description + + + + + id + any valid bean name + The id of the region bean definition. + + + name + any valid region name + The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name). + + + cache-ref + GemFire cache bean name + The name of the bean defining the GemFire cache (by default 'gemfire-cache'). + + + + cache-listener + valid bean name or definition + The name or nested bean declaration of a GemFire CacheListener. + + + cache-loader + valid bean name or definition + The name or nested bean declaration of a GemFire CacheLoader. + + + cache-writer + valid bean name or definition + The name or nested bean declaration of a GemFire CacheWriter. + + + + partition-resolver + bean name + The name of the partitioned resolver used by this region, for custom partitioning. + + + 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 storages. + + + colocated-with + valid region name + The name of the partitioned region with which this newly created partitioned region is colocated. + + + local-max-memory + positive integer + The maximum amount of memory, in megabytes, to be 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. + + + 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. + + + 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. + + + +
+
+ +
In a similar manner to the