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