geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb - geode - Git at Google

 ---
 title: Region Management
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 <a id="data_regions__section_18A9481217204613958897FE64105097"></a>
 Operations that create, destroy, invalidate, clear, and change the
 configuration of regions work with gfsh commands, through an XML description,
 and via API calls.

 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.

 *Region shortcuts* identify commonly-used types of regions.
 See [Region Shortcuts](../../reference/topics/chapter_overview_regionshortcuts.html) for more information.

 **Note:**
 If you change attributes that define a region, you must restart the member for the changes to take effect.

 #  Creating a Region

 ###  Creating a Region with gfsh

 A simple and fast way to create a data region in the <%=vars.product_name_long%> cache is to use the `gfsh` command-line tool.

 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 `gfsh create region` [command reference page](../../tools_modules/gfsh/command-pages/create.html) details command line options for creating a region with `gfsh`.

 With `gfsh` connected to a JMX server,
 an example command that creates a replicated region is

 ``` pre
 gfsh>create region --name=region1 --type=REPLICATE
 ```

 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 cluster. 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 cluster by specifying a group when creating the region and starting servers. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html).


 ###  Creating a Region Through the cache.xml File

 A common way to create a data region in the <%=vars.product_name_long%> cache is through `cache.xml` declarations.
 When starting the member with the `cache.xml` file,
 the region will be created.

 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.

 -   In the `cache.xml` file, create a `<region>` element for the new region as a subelement to the `<cache>` element or the `<client-cache>` element.
 -   Define the region's name and use a region shortcut, if one applies.
 -   Add other attributes as needed to customize the region’s behavior.

 ### cache.xml File Examples

 The `region` declaration of a replicated region named Portfolios:

 ``` pre
 <region name="Portfolios" refid="REPLICATE"/>
 ```

 The `region` declaration of a partitioned region named myRegion:

 ``` pre
 <region name="myRegion" refid="PARTITION"/>
 ```

 The `region` declaration of a partitioned region that backs up content
 to disk:

 ``` pre
 <region name="myRegion" refid="PARTITION_PERSISTENT"/>
 ```

 The `region` declaration of a partitioned region configured with
 high availability and a modified storage capacity in the host member:

 ``` pre
 <region name="myRegion" refid="PARTITION_REDUNDANT">
     <region-attributes>
         <partition-attributes local-max-memory="512" />
     </region-attributes>
 </region>
 ```

 The `region` declaration of a replicated region configured with
 an event listener in which entries expire:

 ``` 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>
 ```

 ### <a id="data_regions__section_028F2602395646818680C906F205526B" class="no-quick-link"></a>Creating a Region Through the API

 <%=vars.product_name%>'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 `cache.xml` declarations within 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 it 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 a `Region`.
     -   **`org.apache.geode.cache.RegionShortcut`**.
 Defines common region configurations.
 -   **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 `cache.xml` 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`** . Defines
 common region configurations.
 -   **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 `cache.xml` declarations in the `<cache>` and `<client-cache>` elements for creating and configuring regions.
     -   **`org.apache.geode.cache.Region`** . Interface for managing regions and their entries.
     -   **`org.apache.geode.cache.RegionAttributes`** . Object holding region configuration settings.

 Use the API to create regions in the cache after startup.
 For run-time region creation, you need to use the API.

 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.

 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.


 ### API Examples

 Create a replicated region named Portfolios:

 ``` pre
 Cache cache = CacheFactory.create();
 RegionFactory rf = cache.createRegionFactory(REPLICATE);
 Region pfloRegion = rf.create("Portfolios");
 ```

 Create a partitioned region with a listener:

 ``` pre
 RegionFactory rf =
     cache.createRegionFactory(RegionShortcut.PARTITION);
 rf.addCacheListener(new LoggingCacheListener());
 custRegion = rf.create("customer");
 ```

 Create a partitioned region with a partition resolver for colocated
 regions:

 ``` 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");
 ```

 Create a client region with a pool specification:

 ``` pre
 ClientRegionFactory<String,String> cRegionFactory =
     cache.createClientRegionFactory(PROXY);
 Region<String, String> region =
     cRegionFactory.setPoolName("Pool3").create("DATA");
 ```


 ## <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.apache.org/schema/cache"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://geode.apache.org/schema/cache http://geode.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" refid="REPLICATE">
               <region name="Private" refid="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 the Configuration of Data Regions

 Update your region properties and contents through `alter region` command, the API or from `cache.xml` file declarations.

 -   Use the [gfsh 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 <%=vars.product_name%> 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.
	---
	title: Region Management
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<a id="data_regions__section_18A9481217204613958897FE64105097"></a>
	Operations that create, destroy, invalidate, clear, and change the
	configuration of regions work with gfsh commands, through an XML description,
	and via API calls.

	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.

	Region shortcuts identify commonly-used types of regions.
	See [Region Shortcuts](../../reference/topics/chapter_overview_regionshortcuts.html) for more information.

	Note:
	If you change attributes that define a region, you must restart the member for the changes to take effect.

	# Creating a Region

	### Creating a Region with gfsh

	A simple and fast way to create a data region in the <%=vars.product_name_long%> cache is to use the `gfsh` command-line tool.

	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 `gfsh create region` [command reference page](../../tools_modules/gfsh/command-pages/create.html) details command line options for creating a region with `gfsh`.

	With `gfsh` connected to a JMX server,
	an example command that creates a replicated region is

	``` pre
	gfsh>create region --name=region1 --type=REPLICATE
	```

	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 cluster. 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 cluster by specifying a group when creating the region and starting servers. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html).


	### Creating a Region Through the cache.xml File

	A common way to create a data region in the <%=vars.product_name_long%> cache is through `cache.xml` declarations.
	When starting the member with the `cache.xml` file,
	the region will be created.

	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.

	- In the `cache.xml` file, create a `<region>` element for the new region as a subelement to the `<cache>` element or the `<client-cache>` element.
	- Define the region's name and use a region shortcut, if one applies.
	- Add other attributes as needed to customize the region’s behavior.

	### cache.xml File Examples

	The `region` declaration of a replicated region named Portfolios:

	``` pre
	<region name="Portfolios" refid="REPLICATE"/>
	```

	The `region` declaration of a partitioned region named myRegion:

	``` pre
	<region name="myRegion" refid="PARTITION"/>
	```

	The `region` declaration of a partitioned region that backs up content
	to disk:

	``` pre
	<region name="myRegion" refid="PARTITION_PERSISTENT"/>
	```

	The `region` declaration of a partitioned region configured with
	high availability and a modified storage capacity in the host member:

	``` pre
	<region name="myRegion" refid="PARTITION_REDUNDANT">
	<region-attributes>
	<partition-attributes local-max-memory="512" />
	</region-attributes>
	</region>
	```

	The `region` declaration of a replicated region configured with
	an event listener in which entries expire:

	``` 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>
	```

	### <a id="data_regions__section_028F2602395646818680C906F205526B" class="no-quick-link"></a>Creating a Region Through the API

	<%=vars.product_name%>'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 `cache.xml` declarations within 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 it 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 a `Region`.
	- `org.apache.geode.cache.RegionShortcut`.
	Defines common region configurations.
	- 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 `cache.xml` 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` . Defines
	common region configurations.
	- 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 `cache.xml` declarations in the `<cache>` and `<client-cache>` elements for creating and configuring regions.
	- `org.apache.geode.cache.Region` . Interface for managing regions and their entries.
	- `org.apache.geode.cache.RegionAttributes` . Object holding region configuration settings.

	Use the API to create regions in the cache after startup.
	For run-time region creation, you need to use the API.

	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.

	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.


	### API Examples

	Create a replicated region named Portfolios:

	``` pre
	Cache cache = CacheFactory.create();
	RegionFactory rf = cache.createRegionFactory(REPLICATE);
	Region pfloRegion = rf.create("Portfolios");
	```

	Create a partitioned region with a listener:

	``` pre
	RegionFactory rf =
	cache.createRegionFactory(RegionShortcut.PARTITION);
	rf.addCacheListener(new LoggingCacheListener());
	custRegion = rf.create("customer");
	```

	Create a partitioned region with a partition resolver for colocated
	regions:

	``` 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");
	```

	Create a client region with a pool specification:

	``` pre
	ClientRegionFactory<String,String> cRegionFactory =
	cache.createClientRegionFactory(PROXY);
	Region<String, String> region =
	cRegionFactory.setPoolName("Pool3").create("DATA");
	```


	## <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.apache.org/schema/cache"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://geode.apache.org/schema/cache http://geode.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" refid="REPLICATE">
	<region name="Private" refid="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 the Configuration of Data Regions

	Update your region properties and contents through `alter region` command, the API or from `cache.xml` file declarations.

	- Use the [gfsh 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 <%=vars.product_name%> 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.