This topic explains how to manage regions in VMware Tanzu GemFire.

Operations that create, destroy, invalidate, clear, and change the configuration of regions work with gfsh commands, through an XML description, and using 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 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 common way to create a data region in the VMware Tanzu GemFire 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 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

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

Creating a Region Through the cache.xml File

A common way to create a data region in the VMware Tanzu GemFire 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:

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

The region declaration of a partitioned region named myRegion:

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

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

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

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

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

Creating a Region Through the API

Tanzu GemFire’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.

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.
(Optional) Use the region factory to further configure your region.
Create your region from the configured region factory.

API Examples

Create a replicated region named Portfolios:

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

Create a partitioned region with a listener:

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:

PartitionAttributesFactory<CustomerId, String> paf = new PartitionAttributesFactory<>();
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:

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

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 regions and then recursively on all contained subregions.

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

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.

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

// 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:

// Remove all entries for the region
Region.clear();

It can be invoked with the gfsh command:

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:

// Remove the entire region
Region.destroyRegion();

A destroy region operation can be invoked with the gfsh command:

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

Close a Region

Use this to stop local caching of persistent and partitioned regions without closing the entire cache:

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