diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index 01ad9469..d3ca6c95 100644 --- a/src/main/asciidoc/reference/cache.adoc +++ b/src/main/asciidoc/reference/cache.adoc @@ -1,15 +1,14 @@ [[bootstrap:cache]] = Configuring a GemFire Cache -In order to use GemFire, a developer needs to either create a new `Cache` or connect to an existing one. -In the current version of GemFire, there can be only one open Cache per VM (or per `ClassLoader` to be -technically correct). In most cases the Cache should only be created once. +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. -NOTE: This section describes the creation and configuration of a full Cache member, appropriate for peer-to-peer -cache topologies and cache servers. A full cache is also commonly used for standalone applications, integration tests -and proofs of concept. In a typical production system, most application processes will act as cache clients -and will create a `ClientCache` instance instead. This is described in the sections <> -and <> +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 <>. A cache with default configuration can be created with a very simple declaration: @@ -18,23 +17,24 @@ A cache with default configuration can be created with a very simple declaration ---- -Upon initialization, a Spring application context containing this cache definition will register a `CacheFactoryBean` -to create a Spring bean named `gemfireCache` referencing a GemFire `Cache` instance. This will either be 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. +During Spring container initialization, any application context containing this cache definition will register +a `CacheFactoryBean` that creates a Spring bean named `gemfireCache` referencing a GemFire `Cache` instance. +This bean will refer to either an existing cache, or if one does not already exist, a newly created one. Since no +additional properties were specified, a newly created cache will apply the default cache configuration. -All Spring Data GemFire components that depend on the cache respect this naming convention so that 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 namespace elements. Also, you can easily override the cache's bean name: +All _Spring Data GemFire_ components that depend on the cache respect this naming convention, so there is no need +to explicitly declare the cache dependency. If you prefer, you can make the dependency explicit via the `cache-ref` +attribute provided by various SDG namespace elements. Also, you can easily override the cache's bean name using +the `id` attribute: [source,xml] ---- ---- -Starting with Spring Data GemFire 1.2.0, the GemFire `Cache` may be fully configured using Spring. However, GemFire's -native XML configuration file, `cache.xml`, is also supported. For scenarios in which the GemFire Cache needs to be -configured natively, simply provide a reference to the GemFire configuration file using the `cache-xml-location` +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: [source,xml] @@ -42,16 +42,19 @@ attribute: ---- -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 the cache needs to be created, it will use the file named `cache.xml` located in the classpath root +to configure it. -NOTE: Note that 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 +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 configuration file one can specify GemFire http://gemfire.docs.pivotal.io/latest/userguide/index.html#reference/topics/gemfire_properties.html[properties] -using any of Spring's common properties support features. For example, one can use the `properties` element -defined in the `util` namespace to define properties directly or load properties from a properties file. The latter is -recommended for externalizing environment specific settings outside the application configuration: +In addition to referencing an external XML configuration file, a developer may also specify GemFire System +http://gemfire.docs.pivotal.io/latest/userguide/index.html#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` +directly or load properties from a properties file: [source,xml] ---- @@ -71,8 +74,10 @@ recommended for externalizing environment specific settings outside the applicat ---- -NOTE: The cache settings apply only if a new cache needs to be created. If an open cache already exists in the VM, -these settings will be ignored. +The latter approach 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. [[bootstrap:cache:advanced]] == Advanced Cache Configuration @@ -160,9 +165,9 @@ the required interface. More information on serialization support can be found i Setting the ` - - - + + @@ -259,14 +264,28 @@ In Spring Data GemFire 1.1 dedicated support for configuring a http://gemfire.do 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`. http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-factory-placeholderconfigurer[property placeholder] reads one or more properties file and then replaces property placeholders with values at runtime. This allows administrators to change such values without having to touch the main application configuration. Spring also provides 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] one to support externalization of environment specific properties from the main code base, easing the deployment across multiple machines. +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. -NOTE: To avoid initialization problems, the `CacheServer`s 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 items 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 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. [[bootstrap:cache:client]] -== Configuring a GemFire Client Cache +== Configuring a GemFire ClientCache -Another configuration addition in Spring Data GemFire 1.1 is the dedicated support for configuring http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientCache.html[ClientCache]. This is similar to a <> in both usage and definition and supported by `org.springframework.data.gemfire.clientClientCacheFactoryBean`. +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://gemfire.docs.pivotal.io/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`. + +The simplest definition of a GemFire cache client with default configuration can be accomplished with the following +declaration: [source,xml] ---- @@ -275,22 +294,124 @@ Another configuration addition in Spring Data GemFire 1.1 is the dedicated suppo ---- -`client-cache` supports much of the same options as the *cache* element. However as opposed to a *full* cache, a client cache connects to a remote cache server through a pool. By default a pool is created to connect to a server on `localhost` port `40404`. The the default pool is used by all client regions unless the region is configured to use a different pool. +`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. -Pools can be defined through the `pool` element; The client side `pool` can be used to configure connectivity to the server for individual entities or for the entire cache. For example, to customize the default pool used by `client-cache`, one needs to define a pool and wire it to cache definition: +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. + +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: [source,xml] ---- - + - + ---- -The tag also includes a `ready-for-events` attribute. If set to `true`, the client cache initialization will include http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientCache.html#readyForEvents()[ClientCache.readyForEvents()]. +The `` element also includes the `ready-for-events` attribute. If set to `true`, the client cache +initialization will include a call to http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/client/ClientCache.html#readyForEvents()[ClientCache.readyForEvents()]. -Client side configuration is covered in more detail in <>. +Client-side configuration is covered in more detail in <>. +[[bootstrap:cache:client:pool]] +=== GemFire's DEFAULT Pool and Spring Data GemFire Pool Definitions + +If a GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: + +[source,xml] +---- + + + +---- + +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] +(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 +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_ +will resolve the references automatically for you. + +For example: + +[source,xml] +---- + + + + + + + +---- + +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. + +_Spring Data GemFire_ basically 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 +are using separate Pools. + +Consider the following: + +[source,xml] +---- + + + + + + + + + + + + + + + +---- + +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 +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 +`pool-name` attribute. + +Finally, the "YetAnotherExample" Region will not use a Pool since it is `LOCAL`. + +NOTE: The "AnotherExample" Region would first look for a Pool bean named `gemfirePool`, but that would require +the definition of an anonymous Pool bean (i.e. ``) or a Pool bean explicitly named `gemfirePool` +(e.g. ``). + +NOTE: We could have either named "locatorPool", "gemfirePool", or made the Pool bean definition anonymous +and it would have the same effect as the above configuration. diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index ded11a0b..660aa4f1 100644 --- a/src/main/asciidoc/reference/region.adoc +++ b/src/main/asciidoc/reference/region.adoc @@ -914,7 +914,12 @@ The following table offers a quick overview of configuration options specific to [[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 in: peer-to-peer (p2p), client-server, and wide area cache network (or WAN). In the last two scenarios, 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. +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. Below is a typical client region configuration: