http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb b/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb new file mode 100644 index 0000000..d809635 --- /dev/null +++ b/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb @@ -0,0 +1,129 @@ +--- +title: Managing Data Entries +--- + +Program your applications to create, modify, and manage your cached data entries. + +<a id="managing_data_entries__section_AACC36127F17411F86D1E409B86C6E5C"></a> +**Note:** +If you do not have the cache's `copy-on-read` attribute set to true, do not change the objects returned from the Java entry access methods. Instead, create a copy of the object, then modify the copy and pass it to the Java `put` method. Modifying a value in place bypasses the entire distribution framework provided by Geode, including cache listeners and expiration activities, and can produce undesired results. + +## <a id="managing_data_entries__section_B095A4073EFB4A3C91AF7C03632EEBFB" class="no-quick-link"></a>Basic Create and Update + +To create or update an entry in the cache, use `Region.put`. For example: + +``` pre +String name = ... +String value = ... +this.currRegion.put(name,value); +``` + +**Note:** +You can also use the `gfsh put` command to add entries to a region, and the `get` command to retrieve entries from a region. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html) for more information. + +If you want only to create the entry (with a null value and with method failure if the entry already exists), use `Region.create` instead. + +## <a id="managing_data_entries__section_7578349EA26A4621B732FE851D71A84F" class="no-quick-link"></a>Batch Operations (getAll, putAll, removeAll) + +Geode provides three APIs to perform batch operations on multiple region entries: + +- `Region.getAll` +- `Region.putAll` +- `Region.removeAll` + +The `getAll` method takes a collection of keys and returns a `Map` of values for the provided keys. If a given key does not exist in the region, then that key's value in the returned map will be null. + +The `putAll` method takes a `Map` of key-value pairs and puts them into the cache and distributes them in a single operation. + +**Example:** + +``` pre +void putAll(String command) throws CacheException +{ +// Get Entry keys and values into Strings key1, ... keyN and value1, ... valueN + Map map = new LinkedHashMap(); + map.put(key1, value1)); + ... + map.put(keyN, valueN)); + this.currRegion.putAll(map); +} +``` + +The updates to the cache are done individually in the order in which they were placed in the `Map`. For partitioned regions, multiple events are sent as a single message to the primary buckets and then distributed to the secondary buckets. + +**Note:** +The processing of maps with very many entries and/or very large data may affect system performance and cause cache update timeouts, especially if the region uses overflow or persistence to disk. + +The `removeAll` method takes a collection of keys and removes all of the entries for the specified keys from this region. This call performs the equivalent of calling`destroy(Object)` on this region once for each key in the specified collection. If an entry does not exist, then that key is skipped. An `EntryNotFoundException` is not thrown. This operation will be distributed to other caches if the region's scope is not set to `Scope.LOCAL`. + +## <a id="managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809" class="no-quick-link"></a>Safe Entry Modification + +When you get an entry value from the cache, by default, the retrieval methods return a direct reference to the cached object. This provides the value as quickly as possible, but also opens the cache to direct, in-place changes. + +**Note:** +Do not directly modify cached values. Modifying a value in place bypasses the Geode distribution framework, including cache writers and listeners, expiration activities, and transaction management, and can produce undesired results. + +Always change your entries using copies of the retrieved objectsânever directly modify the returned objects. You can do this in one of two ways: + +1. Change the entry retrieval behavior for your cache by setting the cache attribute, `copy-on-read`, to true (the default is false). + + ``` pre + <cache copy-on-read="true"> + ... + </cache> + ``` + + When `copy-on-read` is true, the entry access methods return copies of the entries. This protects you from inadvertently modifying in-place, but negatively impacts performance and memory consumption when copying is not needed. + + These entry access methods return an entry reference if `copy-on-read` is false and a copy of the entry if `copy-on-read` is true: + + `Region.get` + result of `Region.put` + `EntryEvent.getNewValue` + `Region.values` + `Region.Entry.getValue` + `EntryEvent.getOldValue` + `Query.select` + +2. Create a copy of the returned object and work with that. For objects that are cloneable or serializable, you can copy the entry value to a new object using `org.apache.geode.CopyHelper.copy`. Example: + + ``` pre + Object o = (StringBuffer)region.get("stringBuf"); + StringBuffer s = (StringBuffer) CopyHelper.copy(o); + s.append("Changes to value, added using put."); + region.put("stringBuf", s); + ``` + +## <a id="managing_data_entries__section_78F6731642944DE594316B86ECB4E70F" class="no-quick-link"></a>Retrieving Region Entries from Proxy Members + +The `Region.values` method call applies to the local region instance only. If you call the `values` method from a client region using the PROXY shortcut, the method call will not be redirected to the server region. To obtain a collection of all values in the Region from a client, you should use interest registration on ALL\_KEYS, or use a query. + +If you use the `Region.get` method from a proxy member, the method call will redirect to the region on the server if it cannot find the key locally. + +## Using gfsh to get and put + +You can use the gfsh `get` and `put` commands to manage data. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html). + +For example: + +``` pre +get --key=('id':'133abg124') --region=region1 + +// Retrieving when key type is a wrapper(primitive)/String +get --key=('133abg124') --region=/region1/region12 --value-class=data.ProfileDetails + +get --key=('100L') --region=/region1/region12 --value-class=data.ProfileDetails +--key-class=java.lang.Long +``` + +``` pre +put --key=('id':'133abg125') --value=('firstname':'James','lastname':'Gosling') +--region=/region1 --key-class=data.ProfileKey --value-class=data.ProfileDetails + +put --key=('133abg124') --value=('Hello World!!') --region=/region2 + +put --key=('100F') --value=('2146547689879658564') --region=/region1/region12 +--key-class=java.lang.Float --value-class=java.lang.Long +``` + +
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb b/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb new file mode 100644 index 0000000..0fe6171 --- /dev/null +++ b/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb @@ -0,0 +1,34 @@ +--- +title: Requirements for Using Custom Classes in Data Caching +--- + +Follow these guidelines to use custom domain classes for your cached entry keys and values. + +## <a id="using_custom_classes__section_F098CAC546164094BE6872BF0C443A71" class="no-quick-link"></a>CLASSPATH + +Each memberâs `CLASSPATH` must include classes for all objects the member accesses. + +- For Java applications, use the standard Java `CLASSPATH`. +- For the cache server process, use the `CLASSPATH` environment variable or the `gfsh start server`'s `--classpath` parameter. See [Running Geode Server Processes](../../configuring/running/running_the_cacheserver.html). + +Data is sent between clients and servers in serialized form and the server stores client data in serialized form. The server does not need to deserialize data to send it to another client or to access it through a `PDXInstance`, but it does need to deserialize it to access it in other ways. The server `CLASSPATH` must include the classes for: + +- All entry keys +- Entry values in regions that the server persists to disk +- Entry values the server accesses for any reason other than access using a `PdxInstance` or transfer of the full entry value to a client + +For information on `PdxInstance`s, see [Data Serialization](../../developing/data_serialization/chapter_overview.html#data_serialization). + +## <a id="using_custom_classes__section_57EB5D02C06947B4BDE75A49286D581D" class="no-quick-link"></a>Data Serialization + +Geode serializes data entry keys and values for distribution, so all data that Geode moves out of the local cache for any reason must be serializable. Additionally, partitioned regions store data in serialized form. Almost every configuration requires serialization. + +For information on the requirements and options for data serialization, see [Data Serialization](../../developing/data_serialization/chapter_overview.html#data_serialization). + +## <a id="using_custom_classes__section_CE776B94EDCB4D269A71C3C9CFEDD5FD" class="no-quick-link"></a>Classes Used as Keys + +The region uses hashing on keys. If you define a custom class to use as a key, for the class, override: + +- `equals` +- `hashCode`. The default `hashCode` inherited from `Object` uses identity, which is different in every system member. In partitioned regions, hashing based on identity puts data in the wrong place. For details, see the Java API documentation for `java.lang.Object`. + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/chapter_overview.html.md.erb b/geode-docs/basic_config/data_regions/chapter_overview.html.md.erb new file mode 100644 index 0000000..3786906 --- /dev/null +++ b/geode-docs/basic_config/data_regions/chapter_overview.html.md.erb @@ -0,0 +1,48 @@ +--- +title: Data Regions +--- + +The region is the core building block of the Apache Geode distributed system. All cached data is organized into data regions and you do all of your data puts, gets, and querying activities against them. + +- **[Data Region Management](../../basic_config/data_regions/managing_data_regions.html)** + + Apache Geode provides different APIs and XML configuration models to support configuration and management of your data regions. + +- **[Creating a Region with gfsh](../../basic_config/data_regions/create_a_region_with_gfsh.html)** + + A simple and fast way to create a data region in the Apache Geode cache is to use the `gfsh` command-line tool. + +- **[Creating a Region Through the cache.xml File](../../basic_config/data_regions/create_a_region_with_cacheXML.html)** + + A common way to create a data region in the Apache Geode cache is through `cache.xml` declarations. + +- **[Creating a Region Through the API](../../basic_config/data_regions/create_a_region_with_API.html)** + + You can use the Geode caching API to create regions in your cache after startup. For run-time region creation, you need to use the API. + +- **[Region Naming](../../basic_config/data_regions/region_naming.html)** + + To be able to perform all available operations on your data regions, +follow these region naming guidelines. + +- **[Region Shortcuts and Custom Named Region Attributes](../../basic_config/data_regions/region_shortcuts.html)** + + Geode provides region shortcut settings, with preset region configurations for the most common region types. For the easiest configuration, start with a shortcut setting and customize as needed. You can also store your own custom configurations in the cache for use by multiple regions. + +- **[Storing and Retrieving Region Shortcuts and Custom Named Region Attributes](../../basic_config/data_regions/store_retrieve_region_shortcuts.html)** + + Use these examples to get started with Geode region shortcuts. + +- **[Managing Region Attributes](../../basic_config/data_regions/managing_region_attributes.html)** + + Use region attributes to fine-tune the region configuration provided by the region shortcut settings. + +- **[Creating Custom Attributes for Regions and Entries](../../basic_config/data_regions/creating_custom_attributes.html)** + + Use custom attributes to store information related to your region or its entries in your cache. These attributes are only visible to the local application and are not distributed. + +- **[Building a New Region with Existing Content](../../basic_config/data_regions/new_region_existing_data.html)** + + A new region or distributed system may need to be loaded with the data of an existing system. There are two approaches to accomplish this task. The approach used depends upon the organization of both the new and the existing distributed system. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/create_a_region_with_API.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/create_a_region_with_API.html.md.erb b/geode-docs/basic_config/data_regions/create_a_region_with_API.html.md.erb new file mode 100644 index 0000000..ba8e384 --- /dev/null +++ b/geode-docs/basic_config/data_regions/create_a_region_with_API.html.md.erb @@ -0,0 +1,63 @@ +--- +title: Creating a Region Through the API +--- + +You can use the Geode caching API to create regions in your cache after startup. For run-time region creation, you need to use the API. + +Before you start, configure your `Cache` or `ClientCache` and determine the region shortcut and other attributes settings your region needs. + +Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. + +1. + + Use a region shortcut to create your region factory. + - + + In peers and servers, use `org.apache.geode.cache.RegionFactory`. + - + + In clients, use `org.apache.geode.cache.client.ClientRegionFactory`. + +2. + + (Optional) Use the region factory to further configure your region. +3. + + Create your region from the configured region factory. + +When you run your member with the region creation code, the region will be created in the cache. + +## Examples + +Creating a partitioned region using RegionFactory: + +``` pre +RegionFactory rf = + cache.createRegionFactory(RegionShortcut.PARTITION); +rf.addCacheListener(new LoggingCacheListener()); +custRegion = rf.create("customer"); +``` + +Creating a modified partitioned region using RegionFactory: + +``` pre +PartitionAttributesFactory paf = new PartitionAttributesFactory<CustomerId, String>(); +paf.setPartitionResolver(new CustomerOrderResolver()); + +RegionFactory rf = + cache.createRegionFactory(RegionShortcut.PARTITION); +rf.setPartitionAttributes(paf.create()); +rf.addCacheListener(new LoggingCacheListener()); +custRegion = rf.create("customer"); +``` + +Creating a client region with a pool specification using ClientRegionFactory: + +``` pre +ClientRegionFactory<String,String> cRegionFactory = + cache.createClientRegionFactory(PROXY); +Region<String, String> region = + cRegionFactory.setPoolName("Pool3").create("DATA"); +``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb b/geode-docs/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb new file mode 100644 index 0000000..2737c88 --- /dev/null +++ b/geode-docs/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb @@ -0,0 +1,68 @@ +--- +title: Creating a Region Through the cache.xml File +--- + +A common way to create a data region in the Apache Geode cache is through `cache.xml` declarations. + +Before you start, configure your `<cache>` or `<client-cache>` in your `cache.xml` file and determine the region shortcut and other attributes settings your region needs. The `cache.xml` file must conform to the schema definition provided in the product's `cache-1.0.xsd`. + +Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. + +1. + + In your `cache.xml` file, create a `<region>` element for your new region as a subelement to the `<cache>` element or the `<client-cache>` element. +2. + + Define your regionâs name and a region attributes shortcut setting, if one applies. Find the shortcut setting that most closely fits your region configuration. +3. + + Add other attributes as needed to customize the regionâs behavior. + +When you start your member with the `cache.xml` file, the region will be created. + +## Examples + +Partitioned Region Declaration + +``` pre +<region name="myRegion" refid="PARTITION"/> +``` + +Partitioned Region Declaration with Backup to Disk + +``` pre +<region name="myRegion" refid="PARTITION_PERSISTENT"/> +``` + +Partitioned Region Declaration with HA and Modified Storage Capacity in Host Member + +``` pre +<region name="myRegion" refid="PARTITION_REDUNDANT"> + <region-attributes> + <partition-attributes local-max-memory="512" /> + </region-attributes> +</region> +``` + +Replicated Region Declaration + +``` pre +<region name="myRegion" refid="REPLICATE"/> +``` + +Replicated Region Declaration with Event Listener and Expiration + +``` pre +<region name="myRegion" refid="REPLICATE"> + <region-attributes statistics-enabled="true"> + <entry-time-to-live> + <expiration-attributes timeout="60" action="destroy"/> + </entry-time-to-live> + <cache-listener> + <class-name>myPackage.MyCacheListener</class-name> + </cache-listener> + </region-attributes> +</region> +``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb b/geode-docs/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb new file mode 100644 index 0000000..c15c5fc --- /dev/null +++ b/geode-docs/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb @@ -0,0 +1,38 @@ +--- +title: Creating a Region with gfsh +--- + +A simple and fast way to create a data region in the Apache Geode cache is to use the `gfsh` command-line tool. + +Before you start, configure your `Cache` or `ClientCache` and determine the region shortcut and other attributes settings your region needs. + +Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. + +1. + + Start a `gfsh` prompt. +2. + + Connect to a server that is currently acting as a JMX Manager node. +3. + + Enter the `create region` command providing any desired region attributes as arguments. + For example: + ``` pre + gfsh>create region --name=region1 --type=REPLICATE + ``` + +4. + + Add data into the region by using the [import data](../../tools_modules/gfsh/command-pages/import.html#topic_jw2_2ld_2l) command or [put](../../tools_modules/gfsh/command-pages/put.html) gfsh command. +5. + + After you modify data in the region you can use the [export data](../../tools_modules/gfsh/command-pages/export.html#topic_263B70069BFC4A7185F86B3272011734) command to generate a snapshot of the current region's data for later use. +6. + + Export the configuration files of your server so that you can save your region's configuration and recreate the region with the same attributes the next time you start up your cache server. See [export config](../../tools_modules/gfsh/command-pages/export.html#topic_C7C69306F93743459E65D46537F4A1EE) for details. + + **Note:** + The cluster configuration service, which is enabled by default, automatically saves the configuration on the locators in the distributed system. After you use the gfsh create region command, any new servers that you start that attach to the same locator receive the same configuration. You can also create alternate configurations within a distributed system by specifying a group when creating the region and starting servers. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/creating_custom_attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/creating_custom_attributes.html.md.erb b/geode-docs/basic_config/data_regions/creating_custom_attributes.html.md.erb new file mode 100644 index 0000000..c234016 --- /dev/null +++ b/geode-docs/basic_config/data_regions/creating_custom_attributes.html.md.erb @@ -0,0 +1,47 @@ +--- +title: Creating Custom Attributes for Regions and Entries +--- + +Use custom attributes to store information related to your region or its entries in your cache. These attributes are only visible to the local application and are not distributed. + +<a id="creating_custom_attributes__section_A8752F55C157480FAF435738D6244503"></a> +You can define custom user attributes so you can associate data with the region or entry and retrieve it later. Unlike the other configuration settings, these attributes are used only by your application. + +**Note:** +User attributes are not distributed. + +1. Create a Java `Object` with your attribute definitions. +2. Attach the object to the region or to an entry: + - `Region.setUserAttribute(userAttributeObject)` + - `Region.getEntry(key).setUserAttribute(userAttributeObject)` + +3. Get the attribute value: + - `Region.getUserAttribute()` + - `Region.getEntry(key).getUserAttribute()` + +This example stores attributes for later retrieval by a cache writer. + +``` pre +// Attach a user attribute to a Region with database info for table portfolio +Object myAttribute = "portfolio"; +final Region portfolios = + new RegionFactory().setCacheWriter(new PortfolioDBWriter()).create("Portfolios"); +Portfolios.setUserAttribute(myAttribute); +``` + +``` pre +//Implement a cache writer that reads the user attribute setting +public class PortfolioDBWriter extends CacheWriterAdapter { + public void beforeCreate(RegionEvent event) { + table = (String)event.getRegion().getUserAttribute(); + // update database table using name from attribute + . . . + } +} +``` + +## <a id="creating_custom_attributes__section_A5CB456E4E96410584F8856EAFB5BB83" class="no-quick-link"></a>Limitations and Alternatives + +User attributes are not distributed to other processes, so if you need to define each attribute in every process that uses the region or entry. You need to update every instance of the region separately. User attributes are not stored to disk for region persistence or overflow, so they cannot be recovered to reinitialize the region. + +If your application requires features not supported by user attributes, an alternative is to create a separate region to hold this data instead. For instance, a region, AttributesRegion, defined by you, could use region names as keys and the user attributes as values. Changes to AttributesRegion would be distributed to other processes, and you could configure the region for persistence or overflow if needed. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb b/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb new file mode 100644 index 0000000..cd9427b --- /dev/null +++ b/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb @@ -0,0 +1,205 @@ +--- +title: Data Region Management +--- + +Apache Geode provides different APIs and XML configuration models to support configuration and management of your data regions. + +<a id="data_regions__section_18A9481217204613958897FE64105097"></a> +You store your data in region entry key/value pairs, with keys and values being any object types your application needs. + +The `org.apache.geode.cache.Region` interface implements `java.util.Map`. + +Each region's attributes define how the data in the region is stored, distributed, and managed. Data regions can be distributed, partitioned among system members, or local to the member. + +You can create regions in the `cache.xml` file, by using the API, or with the gfsh command-line interface. You can use *region shortcuts* to configure commonly-used types of regions. For more information about region shortcuts, see [Region Shortcuts Reference](../../reference/topics/region_shortcuts_reference.html#reference_lt4_54c_lk). + +**Note:** +If you change attributes that define a region, you must restart the member for the changes to take effect. + +## <a id="data_regions__section_028F2602395646818680C906F205526B" class="no-quick-link"></a>The Region APIs + +Geode's regions APIs provide specialized behavior for different system member types. + +- **Peer/Server Region APIs**. Use these methods, interfaces, and classes for peer/server region creation. These are in the `org.apache.geode.cache` package. They correspond to declarations in the `<cache>` element for creating and configuring regions. + - **`org.apache.geode.cache.Cache.createRegionFactory`** . This method takes a `RegionShortcut` `enum` to initiate region configuration, and returns a `RegionFactory`. Use `createRegionFactory()`, not "`new RegionFactory`," to create a RegionFactory. + - **`org.apache.geode.cache.RegionFactory`**. Provides methods to set individual region attributes and to create the region. The `create` call returns `Region`. + - **`org.apache.geode.cache.RegionShortcut`**. Common region configurations can be retrieved through `Cache` `createRegionShortcut` and with the region attribute, `refid`. +- **Client Region APIs**. Use these methods, interfaces, and classes for client region creation. These are in the `org.apache.geode.cache.client` package. They correspond to declarations in the `<client-cache>` element for creating and configuring regions. + + These are client versions of the Peer/Server Region APIs. These client APIs provide similar functionality, but are tailored to the needs and behaviors of client regions. + + - **`org.apache.geode.cache.clientCache.createRegionFactory`** . This method takes a `ClientRegionShortcut` `enum` to initiate region configuration, and returns a `ClientRegionFactory`. + - **`org.apache.geode.cache.client.ClientRegionFactory`**. Provides methods to set individual region attributes and to create the region. The `create` call returns `Region`. + - **`org.apache.geode.cache.client.ClientRegionShortcut`** . Common region configurations can be retrieved through `ClientCache` `createClientRegionFactory` and with the region attribute, `refid`. +- **Region APIs Used For All Member Types**. These interfaces and classes are used universally for region management. These are in the `org.apache.geode.cache` package. They correspond to declarations under the `<cache>` and `<client-cache>` elements for creating and configuring regions. + - **`org.apache.geode.cache.Region`** . Interface for managing your regions and their entries. + - **`org.apache.geode.cache.RegionAttributes`** . Object holding region configuration settings. + - **`org.apache.geode.cache.createRegionFactory`**. Can be used to create `RegionAttributes` to pass to `RegionFactory` and `ClientRegionFactory`. + +## <a id="data_regions__section_9F898C23D2164ED5BB3789FD8B1F68C3" class="no-quick-link"></a>Create and Access Data Regions + +Before you start, have your cache configuration defined, along with any cache-wide configuration your region requires, like disk store configuration and client server pool configuration. + +1. Determine the region attributes requirements and identify the region shortcut setting that most closely matches your needs. See [Region Shortcuts and Custom Named Region Attributes](region_shortcuts.html) and [Region Shortcuts](../../reference/topics/chapter_overview_regionshortcuts.html) for more information. +2. Define any region attributes that are not provided in the shortcut you chose. +3. Create a region using any of the following methods: + - `gfsh`. After starting up servers, a JMX manager and connecting to the cluster, execute the following command: + + gfsh>create region --name=Portfolios --type=REPLICATE + - Declaration in the `cache.xml`: + + <?xml version="1.0" encoding="UTF-8"?> + <cache + xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0" + lock-lease="120" + lock-timeout="60" + search-timeout="300"> + <!-- Create a region named Portfolios --> + <region name="Portfolios" id="REPLICATE"/> + </cache> + + When the `cache.xml` is loaded at cache creation, the system automatically creates any declared regions. + - `RegionFactory` API calls: + + Cache cache = CacheFactory.create(); + RegionFactory rf = cache.createRegionFactory(REPLICATE); + Region pfloRegion = rf.create("Portfolios"); + +Once you have created your regions, you can access them through the `Cache` and `Region` APIs as full region lists or individually. + +## <a id="data_regions__section_jn1_sry_5m" class="no-quick-link"></a>Create and Access Data Subregions + +An individual region can contain multiple subregions. +Subregions are an older feature that will not be useful in new designs +and applications. +They are used to create a hierarchical namespace within a cache, +providing naming that feels like paths in a file system. +Here are limitations on the use of subregions: + +- A region with LOCAL scope can only have subregions with LOCAL scope. +- Partitioned region types may not be used with subregions. A subregion may not have a parent that is a partitioned region, and a subregion may not be of type PARTITION. +- A subregion must have the same scope (GLOBAL, DISTRIBUTED\_ACK, DISTRIBUTED\_NO\_ACK) as its parent region. +- Subregion names must be unique within the cache. + +You can create subregions using one of the following methods: + +- Declaration in the `cache.xml`: + + <?xml version="1.0"?> + <cache + xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0" + lock-lease="120" + lock-timeout="60" + search-timeout="300"> + <!-- Create a region named Portfolios --> + <region name="Portfolios" id="REPLICATE"> + <region name="Private" id="REPLICATE"> + ... + </region> + </region> + </cache> + + When the `cache.xml` is loaded at cache creation, the system automatically creates any declared regions and subregions. + +- `RegionFactory` API calls: + + Cache cache = CacheFactory.create(); + RegionFactory rf = cache.createRegionFactory(REPLICATE); + Region pfloRegion = rf.create("Portfolios"); + Region pvtSubregion = rf.createSubregion(pfloRegion, "Private"); + +`Region` method calls with a `recursive` parameter operate on the given +region(s) and then recursively on all contained subregions. + +## <a id="data_regions__section_7AD53DCC71064883BFA9C53E6040D85A" class="no-quick-link"></a>Update Data Regions + +Update your region properties and contents through `alter region` command, the API or from `cache.xml` file declarations. + +- Execute the [alter region](../../tools_modules/gfsh/command-pages/alter.html#topic_E74ED23CB60342538B2175C326E7D758) command. +- In the API, use `Cache` and `Region` methods to change configuration parameters and modify region structure and data. +- Load new XML declarations using the `Cache.loadCacheXml` method. Where possible, declarations in the new `cache.xml` file supersede existing definitions. For example, if a region declared in the `cache.xml` file already exists in the cache, its mutable attributes are modified according to the file declarations. Immutable attributes are not affected. If a region does not already exist, it is created. Entries and indexes are created or updated according to the state of the cache and the file declarations. + +## <a id="data_regions__section_953E19F03F4541BAA3AE58118E7EA7E4" class="no-quick-link"></a>Invalidate a Region + +An invalidate region operation removes all entry values for a region, while leaving the entry keys intact. This operation can be invoked only through the API on a `Region` instance. Event notification occurs. + +``` pre +// Invalidate the entire distributed region +Region.invalidateRegion(); +``` + +The API also offers a method to invalidate only the entries within the local cache. This method may not be used on a replicated region, as doing so would invalidate the replication contract. + +``` pre +// Invalidate the region within this member +Region.localInvalidateRegion(); +``` + +## Clear a Region + +A clear region operation removes all entries from a region. This operation is not available for partitioned regions. This operation can be invoked through the API on a `Region` instance: + +``` pre +// Remove all entries for the region +Region.clear(); +``` + +It can be invoked with the `gfsh` command: + +``` pre +gfsh>remove --region=Region1 --all +``` + +Event notification occurs for a clear region operation. + +## Destroy a Region + +A destroy region operation removes the entire region. This operation can be invoked through the API on a `Region` instance: + +``` pre +// Remove the entire region +Region.destroyRegion(); +``` + +A destroy region operation can be invoked with the `gfsh` command: + +``` pre +gfsh>destroy region --name=Region1 +``` + +Event notification occurs for a destroy region operation. + +A region can be destroyed by removing the region's specification from the `cache.xml` file. + +Destroying the region by an API invocation or by using the `gfsh destroy` command while all members are online is the best way to remove a region, as Geode handles all aspects of the removal, including removing the region's persistent disk stores across the online members hosting the region. Destroying the region by removing its specification from the `cache.xml` file does not remove the region's existing persistent disk stores. + +The destroy operation can be propagated only to online members. The system will encounter restart issues if a region is destroyed while some members are online and others are offline. As those members that were offline restart, they will block indefinitely, waiting for persistent region data that no longer exists. To fix this issue, shut down all members that are blocked waiting for the removed region. Once those members are in the offline state, use the `gfsh alter disk-store` command with the `--remove` option on each offline member to remove the region. Then, restart each member. + +An edge case results in issues when destroying a persistent region (R-removed) by removing its specification from the `cache.xml` file, and region R-removed was colocated with another persistent region (R-remains). The issue occurs because the persistent information contained within R-remains is inconsistent with the (lack of) specification of R-removed. Upon restart of R-remains, its persisted metadata refers to R-removed as a colocated region, and the startup of R-remains is dependent on that removed region. Thus, the startup of R-remains blocks, unable to complete. The issue may manifest with operations on the R-remains region such as a query, put, or get, that never finishes. To fix this issue, shut down all members with the persisted metadata that refers to the removed region. Once those members are in the offline state, use the `gfsh alter disk-store` command with the `--remove` option on each offline member to remove the region. Then, restart each member. + +## <a id="data_regions__section_3C0A7E088FDB413297ED8C0CD606968D" class="no-quick-link"></a>Close a Region + +Use this to stop local caching of persistent and partitioned regions without closing the entire cache: + +``` pre +Region.close(); +``` + +The `Region.close` operation works like the `Region.localDestroyRegion` operation with these significant differences: + +- The `close` method is called for every callback installed on the region. +- No events are invoked. Of particular note, the entry events, `beforeDestroy` and `afterDestroy`, and the region events, `beforeRegionDestroy` and `afterRegionDestroy`, are not invoked. See [Events and Event Handling](../../developing/events/chapter_overview.html#implementing_event_handlers). +- If persistent, the region is removed from memory but its disk files are retained. +- If partitioned, the region is removed from the local cache. If the partitioned region is redundant, local data caching fails over to another cache. Otherwise, local data is lost. + +## Using gfsh to Manage Regions + +You can also use gfsh commands to manage regions. There are commands to create, alter, describe, destroy, rebalance, and list the regions in your distributed system. By default, the cluster configuration service saves the cluster configuration as you execute gfsh commands. When you add new servers to the cluster, the servers receive this cluster-wide configuration and create the specified regions. You can also define *groups* that apply only to some of the servers in the cluster. Servers you start that specify a group also receive the group configuration from the cluster configuration service. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). + +See [Creating a Region with gfsh](create_a_region_with_gfsh.html#task_75639BFA7847461D9E006E91B728BB44) and the [create](../../tools_modules/gfsh/command-pages/create.html) command reference page. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb b/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb new file mode 100644 index 0000000..541c8dd --- /dev/null +++ b/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb @@ -0,0 +1,96 @@ +--- +title: Managing Region Attributes +--- + +Use region attributes to fine-tune the region configuration provided by the region shortcut settings. + +<a id="managing_region_attributes__section_B6363B281A994141B9B9BDD952173330"></a> +All region attributes have default settings, so you only need to use region attributes to set the ones you want to override. See [<region-attributes>](../../reference/topics/cache_xml.html#region-attributes). + +## <a id="managing_region_attributes__section_DDBF2810ABB54A55B1479AD786ED48DF" class="no-quick-link"></a>Define Region Attributes + +Create region attributes using any of these methods: + +- Declarations inside the `cache.xml` `<region>` element: + + ``` pre + <cache> + <region name="exampleRegion" refid="REPLICATE"> + <region-attributes statistics-enabled="true"> + <entry-idle-time> + <expiration-attributes timeout="10" action="destroy"/> + </entry-idle-time> + <cache-listener> + <class-name>quickstart.SimpleCacheListener</class-name> + </cache-listener> + </region-attributes> + </region> + </cache> + ``` + + When the `cache.xml` is loaded at startup, declared region attributes are automatically created and applied to the region. + +- `RegionFactory` API `set`\* method calls: + + ``` pre + // Creating a partitioned region using the RegionFactory + RegionFactory rf = cache.createRegionFactory(RegionShortcut.PARTITION); + rf.addCacheListener(new LoggingCacheListener()); + custRegion = rf.create("customer"); + ``` + + ``` pre + // Creating a partitioned region using the RegionFactory, with attribute modifications + RegionFactory rf = + cache.createRegionFactory(RegionShortcut.PARTITION); + rf.setPartitionResolver(new CustomerOrderResolver()); + rf.addCacheListener(new LoggingCacheListener()); + custRegion = rf.create("customer"); + ``` + + ``` pre + // Creating a client with a Pool Specification Using ClientRegionFactory + ClientRegionFactory<String,String> cRegionFactory = + cache.createClientRegionFactory(PROXY); + Region<String, String> region = + cRegionFactory.setPoolName("Pool3").create("DATA"); + ``` + +- By issuing the gfsh `create region` command. + +## <a id="managing_region_attributes__section_F69A7664F72D47BBA463D81B72C03B4D" class="no-quick-link"></a>Modify Region Attributes + +You can modify a regionâs event handlers and expiration and eviction attributes after the region is created. + +**Note:** +Do not modify attributes for existing regions unless absolutely necessary. Creating the attributes you need at region creation is more efficient. + +Modify attributes in one of these ways: + +- By loading a `cache.xml` with modified region attribute specifications: + + ``` pre + <!-- Change the listener for exampleRegion + ... + <region name="exampleRegion"> + <region-attributes statistics-enabled="true"> + <cache-listener> + <class-name>quickstart.ComplicatedCacheListener</class-name> + </cache-listener> + </region-attributes> + </region> + ... + ``` + +- Using the `AttributesMutator` API: + 1. Retrieve the `AttributesMutator` from the region + 2. Call the mutator set methods to modify attributes: + + ``` pre + currRegion = cache.getRegion("root"); + AttributesMutator mutator = this.currRegion.getAttributesMutator(); + mutator.addCacheListener(new LoggingCacheListener()); + ``` + +- By issuing the gfsh `alter region` command. See [alter region](../../tools_modules/gfsh/command-pages/alter.html#topic_E74ED23CB60342538B2175C326E7D758). + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb b/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb new file mode 100644 index 0000000..ad17ebd --- /dev/null +++ b/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Building a New Region with Existing Content +--- + +A new region or distributed system may need to be loaded with the data of an existing system. There are two approaches to accomplish this task. The approach used depends upon the organization of both the new and the existing distributed system. + +If both the number and the type of members is the same in both the new and the existing distributed system, then the simplest option is to use backup and restore on the persistent disk store contents. Make a full online backup of the persistent data in the disk store of the existing distributed system. Copy the files that comprise the backup to the new distributed system location. A restore instills the data into the new distributed system. See [Creating Backups for System Recovery and Operational Management](../../managing/disk_storage/backup_restore_disk_store.html) for details on how to make a backup and use the backup to restore a disk store. + +Take a different approach when the number or the type of members is *not* the same in both the new and the existing distributed system. This approach uses export and import of region data. Export the region data of the existing distributed system to create a snapshot. Copy the snapshot to the new distributed system location. Import the snapshot into the new distributed system. See appropriate sections within [Cache and Region Snapshots](../../managing/cache_snapshots/chapter_overview.html) for details on making and using a snapshot. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/region_naming.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/region_naming.html.md.erb b/geode-docs/basic_config/data_regions/region_naming.html.md.erb new file mode 100644 index 0000000..021079d --- /dev/null +++ b/geode-docs/basic_config/data_regions/region_naming.html.md.erb @@ -0,0 +1,14 @@ +--- +title: Region Naming +--- + +To be able to perform all available operations on your data regions, +follow these region naming guidelines. + +- Permitted characters within region names are alphanumeric characters +(`ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`), +the underscore character (`_`), and the hyphen character (`-`). +- Do not use the slash character (`/`). +- Do not begin region names with two underscore characters (`__`), +as this is reserved for internal use. + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb b/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb new file mode 100644 index 0000000..270987b --- /dev/null +++ b/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb @@ -0,0 +1,98 @@ +--- +title: Region Shortcuts and Custom Named Region Attributes +--- + +Geode provides region shortcut settings, with preset region configurations for the most common region types. For the easiest configuration, start with a shortcut setting and customize as needed. You can also store your own custom configurations in the cache for use by multiple regions. + +<a id="region_shortcuts__section_D9E58754D2B0435FA2986DBBF3063D4C"></a> +You configure automated management of data regions and their entries through region shortcuts and region attributes. These region configuration settings determine such things as where the data resides, how the region is managed in memory, reliability behavior, and the automatic loading, distribution, and expiration of data entries. + +**Note:** +Whenever possible, use region shortcuts to configure your region, and further customize behavior using region attributes. The shortcut settings are preset with the most common region configurations. + +Geode provides a number of predefined, shortcut region attributes settings for your use. You can also define your own custom region attributes and store them with an identifier for later retrieval. Both types of stored attributes are referred to as named region attributes. You can create and store your attribute settings in the `cache.xml` file and through the API. + +Retrieve region shortcuts and custom named attributes by providing the ID to the region creation, in the `refid` attribute setting. This example uses the shortcut REPLICATE attributes to create a region: + +``` pre +<region name="testREP" refid="REPLICATE"/> +``` + +You can create your own named attributes as needed, by providing an `id` in your region attributes declaration. The following region declaration: + +1. Retrieves all of the attribute settings provided by the persistent partitioned region shortcut +2. Modifies the shortcut attribute settings by specifying a disk store name to use for persistence +3. Assigns the new attribute settings to the new region named `testPR` +4. Stores the attribute settings in a new custom attributes named `testPRPersist`: + + ``` pre + <disk-store name="testDiskStore" > + <disk-dirs> + <disk-dir>PRPersist1</disk-dir> + <disk-dir>PRPersist2</disk-dir> + </disk-dirs> + </disk-store> + <region name="testPR" > + <region-attributes id="testPRPersist" + refid="PARTITION_PERSISTENT" disk-store-name="testDiskStore"/> + </region> + ``` + +## <a id="region_shortcuts__section_20548383511141B19EBC053E36877B1A" class="no-quick-link"></a>Shortcut Attribute Options + +You can select the most common region attributes settings from Geodeâs predefined named region attributes in these classes: + +- **`org.apache.geode.cache.RegionShortcut`**. For peers and servers. +- **`org.apache.geode.cache.client.ClientRegionShortcut`**. For clients. + +Shortcut attributes are a convenience only. They are just named attributes that Geode has already stored for you. You can override their settings by storing new attributes with the same id as the predefined attributes. + +For a full list of all available region shortcuts, see [Region Shortcuts Quick Reference](../../reference/topics/region_shortcuts_table.html#reference_ufj_5kz_4k). + +The `org.apache.geode.cache.RegionShortcut` Javadocs give complete listings of the options. + +## <a id="region_shortcuts__section_D0975C76572E41F79C1A6EE7CF371251" class="no-quick-link"></a>RegionShortcuts for Peers and Servers + +These are the primary options available in the region shortcut settings. The names listed appear in the shortcut identifier alone or in combination, like "`PARTITION`" in `PARTITION`, `PARTITION_PROXY`, and `PARTITION_REDUNDANT`. + +**Cache Data Storage Mode** + +- **`PARTITION`** . Creates a partitioned region. This is a data store for the region. You can also specify these options with `PARTITION`: + - **`PROXY`**. Data is not stored in the local cache and the member is a data accessor to the region. This requires other members to create non-proxy copies of the region, so the data is stored somewhere. + - **`REDUNDANT`**. The region stores a secondary copy of all data, for high availability. +- **`REPLICATE`**. Creates a replicated region. This is a data store for the region. You can also specify these options with `REPLICATE`: + - **`PROXY`**. Data is not stored in the local cache and the member is a data accessor to the region. This requires other members to create non-proxy copies of the region, so the data is stored somewhere. +- **`LOCAL`**. Creates a region private to the defining member. + +**Data Eviction** + +- **`HEAP_LRU`**. Causes least recently used data to be evicted from memory when the Geode resource manager determines that the cache has reached configured storage limits. + +**Disk Storage** + +You can specify these alone or in combination: + +- **`PERSISTENT`**. Backs up all data to disk, in addition to storing it in memory. +- **`OVERFLOW`**. Moves data out of memory and on to disk, when memory use becomes too high. + +## <a id="region_shortcuts__section_BD136ACEB8274B17ACFB9A5954D116E4" class="no-quick-link"></a>ClientRegionShortcuts for Clients + +These are the primary options available in the client region shortcut settings. The names listed appear in the shortcut identifier alone or in combination, like "`PROXY`" in `PROXY` and `CACHING_PROXY`. + +**Communication with Servers and Data Storage** + +- **`PROXY`**. Does not store data in the client cache, but connects the region to the servers for data requests and updates, interest registrations, and so on. The client is a data accessor to the region. +- **`CACHING_PROXY`**. Stores data in the client cache and connects the region to the servers for data requests and updates, interest registrations, and so on. +- **`LOCAL`**. Stores data in the client cache and does not connect the region to the servers. This is a client-side-only region. Note that this is not the same as setting the region's `scope` attribute to `LOCAL`. + +**Data Eviction** + +- **`HEAP_LRU`**. Causes least recently used data to be evicted from memory when the Geode resource manager determines that the cache has reached configured storage limits. + +**Disk Storage** + +With the LOCAL and CACHING data storage shortcut options, you can also specify these disk storage options, alone or in combination: + +- **`PERSISTENT`**. Backs up all data to disk, in addition to storing it in memory. +- **`OVERFLOW`**. Moves data out of memory and on to disk, when memory use becomes too high. + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb b/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb new file mode 100644 index 0000000..9d39bd5 --- /dev/null +++ b/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb @@ -0,0 +1,60 @@ +--- +title: Storing and Retrieving Region Shortcuts and Custom Named Region Attributes +--- + +Use these examples to get started with Geode region shortcuts. + +<a id="region_shortcuts__section_D9E58754D2B0435FA2986DBBF3063D4C"></a> +Geode region shortcuts, in `org.apache.geode.cache.RegionShortcut` for peers and servers and `org.apache.geode.cache.client.ClientRegionShortcut` for clients, are available wherever you create a region in the `cache.xml` or through the API. Custom named attributes, stored by you, are available from the moment you store them on. + +The region shortcuts are special Geode named region attributes, with identifying names. Create custom named region attributes by setting the attributes and storing them with a unique identifier in the region attribute `id`. Retrieve named attributes by providing the shortcut enum value or the name you assigned in the `id` to the region creation: + +- In the API, use the identifier in the region factory creation +- In the `cache.xml`, use the identifier in the `<region>` or `<region-attribute>` `refid` setting. The `refid` is available in both elements for convenience + +## <a id="region_shortcuts__section_8FCBCC4BDCDE4A85A27E5B9B70603F63" class="no-quick-link"></a>Examples + +**Example \#1** + +This example shows partitioned region creation in the `cache.xml`: + +- The first `region-attributes` declaration starts with the predefined `PARTITION_REDUNDANT` attributes, modifies the `local-max-memory` setting, and stores the resulting attributes in the custom-named `myPartition` attributes. +- The region declarations use the new stored attributes, but each has its own interest policy, which is specified in the individual region creation. + + ``` pre + <!-- Retrieving and storing attributes --> + <region-attributes id="myPartition" refid="PARTITION_REDUNDANT"> + <partition-attributes local-max-memory="512"/> + </region-attributes> + + <!-- Two partitioned regions, one colocated with the other --> + + <!-- Attributes are retrieved and applied in the first region --> + <region name="PartitionedRegion1" refid="myPartition"/> + + <!-- Same stored attributes, modification for this region--> + <region name="PartitionedRegion2" refid="myPartition"> + <region-attributes> + <partition-attributes colocated-with="PartitionedRegion1" /> + </region-attributes> + </region> + ``` + +**Example \#2** + +This example uses the `RegionFactory` API to create a region based on the predefined `PARTITION` region shortcut: + +``` pre +final Region diskPortfolios = + new RegionFactory("PARTITION").create("Portfolios"); +``` + +This example retrieves an attributes template and passes it to the region creation with a modified pool specification: + +``` pre +ClientRegionFactory<String,String> regionFactory = + cache.createClientRegionFactory(PROXY); +Region<String, String> region = regionFactory + .setPoolName("publisher") + .create("DATA"); +``` http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb b/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb new file mode 100644 index 0000000..db03d15 --- /dev/null +++ b/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb @@ -0,0 +1,64 @@ +--- +title: Setting Properties +--- + +Geode provides a default distributed system configuration for out-of-the-box systems. To use non-default configurations and to fine-tune your member communication, you can use a mix of various options to customize your distributed system configuration. + +<a id="setting_distributed_properties__section_67EBCC53EB174B108DA7271E2CD2B76C"></a> +Geode properties are used to join a distributed system and configure system member behavior. Configure your Geode properties through the `gemfire.properties` file, the Java API, or command-line input. Generally, you store all your properties in the `gemfire.properties` file, but you may need to provide properties through other means, for example, to pass in security properties for username and password that you have received from keyboard input. + +**Note:** +Check with your Geode system administrator before changing properties through the API, including the `gemfire.properties` and `gfsecurity.properties` settings. The system administrator may need to set properties at the command line or in configuration files. Any change made through the API overrides those other settings. + +**Note:** +The product `defaultConfigs` directory has a sample `gemfire.properties` file with all default settings. + +Set distributed system properties by any combination of the following. The system looks for the settings in the order listed: + +1. `java.lang.System` property setting. Usually set at the command line. For applications, set these in your code or at the command line. + + Naming: Specify these properties in the format `gemfire.property-name`, where `property-name` matches the name in the `gemfire.properties` file. To set the gemfire property file name, use `gemfirePropertyFile` by itself + - In the API, set the `System` properties before the cache creation call. Example: + + ``` pre + System.setProperty("DgemfirePropertyFile", "gfTest"); + System.setProperty("Dgemfire.mcast-port", "10999"); + + Cache cache = new CacheFactory().create(); + ``` + - At the `java` command line, pass in `System` properties using the `-D` switch. Example: + + ``` pre + java -DgemfirePropertyFile=gfTest -Dgemfire.mcast-port=10999 test.Program + ``` +2. Entry in a `Properties` object. + + Naming: Specify these properties using the names in the `gemfire.properties` file. To set the gemfire property file name, use `gemfirePropertyFile`. + - In the API, create a `Properties` object and pass it to the cache create method. Example: + + ``` pre + Properties properties= new Properties(); + properties.setProperty("log-level", "warning"); + properties.setProperty("name", "testMember2"); + ClientCache userCache = + new ClientCacheFactory(properties).create(); + ``` + - For the cache server, pass the properties files on the `gfsh` command line as command-line options. Example: + + ``` pre + gfsh>start server --name=server_name --mcast-port=10338 --properties-file=serverConfig/gemfire.properties --security-properties-file=gfsecurity.properties + ``` + + See [Running Geode Server Processes](../../configuring/running/running_the_cacheserver.html) for more information on running cache servers. + +3. Entry in a `gemfire.properties` file. See [Deploying Configuration Files without the Cluster Configuration Service](../../configuring/running/deploying_config_files.html). Example: + + ``` pre + cache-xml-file=cache.xml + conserve-sockets=true + disable-tcp=false + ``` + +4. Default value. The default property values are listed in the online Java documentation for `org.apache.geode.distributed.DistributedSystem`. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb b/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb new file mode 100644 index 0000000..c003e8b --- /dev/null +++ b/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb @@ -0,0 +1,31 @@ +--- +title: Cache Management +--- + +The Geode cache is the entry point to Geode caching management. Geode provides different APIs and XML configuration models to support the behaviors of different members. + +- **[Introduction to Cache Management](../../basic_config/the_cache/intro_cache_management.html)** + + The cache provides in-memory storage and management for your data. + +- **[Managing a Peer or Server Cache](../../basic_config/the_cache/managing_a_peer_server_cache.html)** + + You start your peer or server cache using a combination of XML declarations and API calls. Close the cache when you are done. + +- **[Managing a Client Cache](../../basic_config/the_cache/managing_a_client_cache.html)** + + You have several options for client cache configuration. Start your client cache using a combination of XML declarations and API calls. Close the client cache when you are done. + +- **[Managing a Cache in a Secure System](../../basic_config/the_cache/managing_a_secure_cache.html)** + + When you create your cache in a secure system, you provide credentials to the connection process for authentication by already-running, secure members. Clients connect to secure servers. Peers are authenticated by secure locators or peer members. + +- **[Managing RegionServices for Multiple Secure Users](../../basic_config/the_cache/managing_a_multiuser_cache.html)** + + In a secure system, you can create clients with multiple, secure connections to the servers from each client. The most common use case is a Geode client embedded in an application server that supports data requests from many users. Each user may be authorized to access a subset of data on the servers. For example, customer users may be allowed to see and update only their own orders and shipments. + +- **[Launching an Application after Initializing the Cache](../../basic_config/the_cache/setting_cache_initializer.html)** + + You can specify a callback application that is launched after the cache initialization. + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb b/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb new file mode 100644 index 0000000..2d21a60 --- /dev/null +++ b/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb @@ -0,0 +1,79 @@ +--- +title: Introduction to Cache Management +--- + +The cache provides in-memory storage and management for your data. + +<a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_B364B076EB5843DAAC28EE2805686453"></a> +You organize your data in the cache into *data regions*, each with its own configurable behavior. You store your data into your regions in key/value pairs called *data entries*. The cache also provides features like transactions, data querying, disk storage management, and logging. See the Javadocs for `org.apache.geode.cache.Cache`. + +You generally configure caches using the `gfsh` command-line utility or a combination of XML declarations and API calls. Geode loads and processes your XML declarations when you first create the cache. + +Geode has one cache type for managing server and peer caches and one for managing client caches. The cache server process automatically creates its server cache at startup. In your application process, the cache creation returns an instance of the server/peer or client cache. From that point on, you manage the cache through API calls in your application. + +## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_20973C59F1C94E35A02CE6582503205A" class="no-quick-link"></a>The Caching APIs + +Geode's caching APIs provide specialized behavior for different system member types and security settings. + +- **`org.apache.geode.cache.RegionService`**. Generally, you use the `RegionService` functionality through instances of `Cache` and `ClientCache`. You only specifically use instances of `RegionService` for limited-access users in secure client applications that service many users. The `RegionService` API provides access to existing cache data regions and to the standard query service for the cache. For client caches, queries are sent to the server tier. For server and peer caches, queries are run in the current cache and any available peers. `RegionService` is implemented by `GemFireCache`. +- **`org.apache.geode.cache.GemFireCache`**. You do not specifically use instances of `GemFireCache`, but you use `GemFireCache` functionality in your instances of `Cache` and `ClientCache`. `GemFireCache` extends `RegionService` and adds general caching features like region attributes, disk stores for region persistence and overflow, and access to the underlying distributed system. `GemFireCache` is implemented by `Cache` and `ClientCache`. +- **`org.apache.geode.cache.Cache`**. Use the `Cache` interface to manage server and peer caches. You have one `Cache` per server or peer process. The `Cache` extends `GemFireCache` and adds server/peer caching features like communication within the distributed system, region creation, transactions and querying, and cache server functionality. +- **`org.apache.geodeâsetting_cache_initializer.cache.ClientCache`**. Use the `ClientCache` interface to manage the cache in your clients. You have one `ClientCache` per client process. The `ClientCache` extends `GemFireCache` and adds client-specific caching features like client region creation, subscription keep-alive management for durable clients, querying on server and client tiers, and RegionService creation for secure access by multiple users within the client. + +## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_6486BDAF06EC4B91A548872066F3EC8C" class="no-quick-link"></a>The Cache XML + +Your `cache.xml` must be formatted according to the product XML schema definition `cache-1.0.xsd`. The schema definition file is available in the product distribution at `$GEMFIRE/schemas/geode.apache.org/schema/cache/cache-1.0.xsd`. + +You use one format for peer and server caches and another for client caches. + +`cache.xml` for Peer/Server: + +``` pre +<?xml version="1.0" encoding="UTF-8"?> +<cache xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0â> +... +</cache> +``` + +`cache.xml` for Client: + +``` pre +<?xml version="1.0" encoding="UTF-8"?> +<client-cache + xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0â> +... +</client-cache> +``` + +For more information on the `cache.xml` file, see [cache.xml](../../reference/topics/chapter_overview_cache_xml.html#cache_xml). + +## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_B113BC6921DA434C947D4326DDB4526E" class="no-quick-link"></a>Create and Close a Cache + +Your system configuration and cache configuration are initialized when you start your member processes and create each memberâs Geode cache. If you are using the cluster configuration service, member processes can pick up its cache configuration from the cluster or group's current configuration. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). + +The steps in this section use `gemfire.properties` and `cache.xml` file examples, except where API is required. You can configure your distributed system properties and cache through the API as well, and you can use a combination of file configuration and API configuration. + +The XML examples may not include the full `cache.xml` file listing. All of your declarative cache configuration must conform to the cache XSD in the product installation `$GEMFIRE/schemas/geode.apache.org/schema/cache/cache-1.0.xsd`. + +For all of your Geode applications: + +1. Create your `Cache`, for peer/server applications, or `ClientCache`, for client applications. This connects to the Geode system you have configured and initializes any configured data regions. Use your cache instance to access your regions and perform your application work. +2. Close your cache when you are done. This frees up resources and disconnects your application from the distributed system in an orderly manner. + +Follow the instructions in the subtopics under [Cache Management](chapter_overview.html#the_cache) to customize your cache creation and closure for your application needs. You may need to combine more than one of the sets of instructions. For example, to create a client cache in a system with security, you would follow the instructions for creating and closing a client cache and for creating and closing a cache in a secure system. + +## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_E8781B263D434F6A9104194AE7BE1647" class="no-quick-link"></a>Export and Import a Cache Snapshot + +To aid in the administration of cache data and speed the setup of new environments, you can export a snapshot of the entire cache (all regions) and then import the snapshot into a new cache. For example, you could take a snapshot of the production environment cache in order to import the cache's data into a testing environment. + +For more details on exporting and importing snapshots of a cache, see [Cache and Region Snapshots](../../managing/cache_snapshots/chapter_overview.html#concept_E6AC3E25404D4D7788F2D52D83EE3071). + +## Cache Management with gfsh and the Cluster Configuration Service + +You can use gfsh commands to mange a server cache. There are gfsh commands to create regions, start servers, and to create queues and other objects. As you issue these commands, the Cluster Configuration Service saves cache.xml and gemfire.properties files on the locators and distributes those configurations to any new members that join the cluster. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb new file mode 100644 index 0000000..94099aa --- /dev/null +++ b/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb @@ -0,0 +1,67 @@ +--- +title: Managing a Client Cache +--- + +You have several options for client cache configuration. Start your client cache using a combination of XML declarations and API calls. Close the client cache when you are done. + +<a id="managing_a_client_cache__section_566044C44C434926A7A9FBAB2BF463BF"></a> +Geode clients are processes that send most or all of their data requests and updates to a Geode server system. Clients run as standalone processes, without peers of their own. + +**Note:** +Geode automatically configures the distributed system for your `ClientCache` as standalone, which means the client has no peers. Do not try to set the `gemfire.properties` `mcast-port` or `locators` for a client application or the system will throw an exception. + +1. Create your client cache: + 1. In your `cache.xml`, use the `client-cache` DOCTYPE and configure your cache inside a `<client-cache>` element. Configure your server connection pool and your regions as needed. Example: + + ``` pre + <?xml version="1.0" encoding="UTF-8"?> + <client-cache + xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0"> + <pool name="serverPool"> + <locator host="host1" port="44444"/> + </pool> + <region name="exampleRegion" refid="PROXY"/> + </client-cache> + ``` + + **Note:** + Applications that use a `client-cache` may want to set `concurrency-checks-enabled` to false for a region in order to see all events for that region. Geode server members can continue using concurrency checks, but they will pass all events to the client cache. This configuration ensures that the client sees all region events, but it does not prevent the client cache region from becoming out-of-sync with the server cache. See [Consistency for Region Updates](../../developing/distributed_regions/region_entry_versions.html#topic_CF2798D3E12647F182C2CEC4A46E2045). + + 2. If you use multiple server pools, configure the pool name explicitly for each client region. Example: + + ``` pre + <pool name="svrPool1"> + <locator host="host1" port="40404"/> + </pool> + <pool name="svrPool2"> + <locator host="host2" port="40404"/> + </pool> + <region name="clientR1" refid="PROXY" pool-name="svrPool1"/> + <region name="clientR2" refid="PROXY" pool-name="svrPool2"/> + <region name="clientsPrivateR" refid="LOCAL"/> + ``` + + 3. In your Java client application, create the cache using the `ClientCacheFactory` `create` method. Example: + + ``` pre + ClientCache clientCache = new ClientCacheFactory().create(); + ``` + + This creates the server connections and initializes the clientâs cache according to your `gemfire.properties` and `cache.xml` specifications. + +2. Close your cache when you are done using the `close` method of your `Cache` instance: + + ``` pre + cache.close(); + ``` + + If your client is durable and you want to maintain your durable queues while the client cache is closed, use: + + ``` pre + clientCache.close(true); + ``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb new file mode 100644 index 0000000..76dc590 --- /dev/null +++ b/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb @@ -0,0 +1,49 @@ +--- +title: Managing RegionServices for Multiple Secure Users +--- + +In a secure system, you can create clients with multiple, secure connections to the servers from each client. The most common use case is a Geode client embedded in an application server that supports data requests from many users. Each user may be authorized to access a subset of data on the servers. For example, customer users may be allowed to see and update only their own orders and shipments. + +<a id="managing_a_multiuser_cache__section_A2A0F835DF35450E8E4B5304F4BC07E2"></a> + +In a single client, multiple authenticated users can all access the same `ClientCache` through instances of the `RegionService` interface. Because there are multiple users with varying authorization levels, access to cached data is done entirely through the servers, where each userâs authorization can be managed. +Follow these steps in addition to the steps in [Managing a Cache in a Secure System](managing_a_secure_cache.html#managing_a_secure_cache). + +1. Create your cache and `RegionService` instances: + 1. Configure your clientâs server pool for multiple secure user authentication. Example: + + ``` pre + <pool name="serverPool" multiuser-authentication="true"> + <locator host="host1" port="44444"/> + </pool> + ``` + + This enables access through the pool for the `RegionService` instances and disables it for the `ClientCache` instance. + + 2. After you create your `ClientCache`, from your `ClientCache` instance, for each user call the `createAuthenticatedView` method, providing the userâs particular credentials. These are create method calls for two users: + + ``` pre + Properties properties = new Properties(); + properties.setProperty("security-username", cust1Name); + properties.setProperty("security-password", cust1Pwd); + RegionService regionService1 = + clientCache.createAuthenticatedView(properties); + + properties = new Properties(); + properties.setProperty("security-username", cust2Name); + properties.setProperty("security-password", cust2Pwd); + RegionService regionService2 = + clientCache.createAuthenticatedView(properties); + ``` + + For each user, do all of your caching and region work through the assigned `RegionService` instance. Access to the server cache will be governed by the serverâs configured authorization rules for each individual user. +2. Close your cache by closing the `ClientCache` instance only. Do not close the `RegionService` instances first. This is especially important for durable clients. + +## <a id="managing_a_multiuser_cache__section_692D9961E8224739903E483BF8AB4F84" class="no-quick-link"></a>Requirements and Caveats for RegionService + +Once each region is created, you can perform operations on it through the `ClientCache` instance or the `RegionService` instances, but not both. + +**Note:** +You can use the `ClientCache` to create a region that uses a pool configured for multi-user authentication, then access and do work on the region using your `RegionService` instances. + +To use `RegionService`, regions must be configured as `EMPTY`. Depending on your data access requirements, this configuration might affect performance, because the client goes to the server for every get. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb new file mode 100644 index 0000000..89ad024 --- /dev/null +++ b/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb @@ -0,0 +1,64 @@ +--- +title: Managing a Peer or Server Cache +--- + +You start your peer or server cache using a combination of XML declarations and API calls. Close the cache when you are done. + +<a id="creating_and_closing_a_peer_cache__section_1633A80F0DB04794BB6C3A7F05EED97E"></a> +Geode peers are members of a Geode distributed system that do not act as clients to another Geode distributed system. Geode servers are peers that also listen for and process client requests. + +1. Create your cache: + 1. Start up a cluster and the cluster configuration service: + 1. Start a locator with `--enable-cluster-configuration` set to true. (It is set true by default.) + + ``` pre + gfsh>start locator --name=locator1 + ``` + + 2. Start up member processes that use the cluster configuration service (enabled by default): + + ``` pre + gfsh>start server --name=server1 --server-port=40404 + ``` + + 3. Create regions: + + ``` pre + gfsh>create region --name=customerRegion --type=REPLICATE + + gfsh>create region --name=ordersRegion --type=PARTITION + ``` + + 2. Or if you are not using the cluster configuration service, directly configure cache.xml in each member of your cluster. In your `cache.xml`, use the `cache` DOCTYPE and configure your cache inside a `<cache>` element. Example: + + ``` pre + <?xml version="1.0" encoding="UTF-8"?> + <cache + xmlns="http://geode.incubator.apache.org/schema/cache"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; + version="1.0â> + // NOTE: Use this <cache-server> element only for server processes + <cache-server port="40404"/> + <region name="customerRegion" refid="REPLICATE" /> + <region name="ordersRegion" refid="PARTITION" /> + </cache> + ``` + + 3. To programmatically create the `Cache` instance: + - In your Java application, use the `CacheFactory` create method: + + ``` pre + Cache cache = new CacheFactory().create(); + ``` + - If you are running a server using the Geode `cacheserver` process, it automatically creates the cache and connection at startup and closes both when it exits. + + The system creates the distributed system connection and initializes the cache according to your `gemfire.properties` and `cache.xml` specifications. + +2. Close your cache when you are done using the inherited `close` method of the `Cache` instance: + + ``` pre + cache.close(); + ``` + + http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb new file mode 100644 index 0000000..6bd109c --- /dev/null +++ b/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb @@ -0,0 +1,50 @@ +--- +title: Managing a Cache in a Secure System +--- + +To create a cache in a secured system, +authentication at connection time will require credentials. +Authorization permits operations as configured. + +<a id="managing_a_secure_cache__section_11BF0F3F64504B74B39CD4C1CF58E6FC"></a> +These steps demonstrate a programmatic cache creation. + +1. To create the cache: + 1. Add necessary security properties to the `gemfire.properties` or `gfsecurity.properties` file, to configure for your particular security implementation. Examples: + + ``` pre + security-client-auth-init=mySecurity.UserPasswordAuthInit.create + ``` + + ``` pre + security-peer-auth-init=myAuthPkg.myAuthInitImpl.create + ``` + + 2. When you create your cache, pass any properties required by your security implementation to the cache factory create call by using one of these methods: + - `ClientCacheFactory` or `CacheFactory` `set` methods. Example: + + ``` pre + ClientCache clientCache = new ClientCacheFactory() + .set("security-username", username) + .set("security-password", password) + .create(); + ``` + - Properties object passed to the `ClientCacheFactory` or `CacheFactory` `create` method. These are usually properties of a sensitive nature that you do not want to put inside the `gfsecurity.properties` file. Example: + + ``` pre + Properties properties = new Properties(); + properties.setProperty("security-username", username); + properties.setProperty("security-password", password); + Cache cache = new CacheFactory(properties).create(); + ``` + + **Note:** + Properties passed to a cache creation method override any settings in either the `gemfire.properties` file or `gfsecuirty.properties`. + +2. Close your cache when you are done, using the `close` method of the `ClientCache` instance or the inherited `close` method of the `Cache` instance. Example: + + ``` pre + cache.close(); + ``` + +
