LATEST VERSION: 8.1.0 - CHANGELOG
Pivotal GemFire® v8.1

Data Region Management

Data Region Management

GemFire provides different APIs and XML configuration models to support configuration and management of your data regions.

You store your data in region entry key/value pairs, with keys and values being any object types your application needs.

The com.gemstone.gemfire.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.

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

The Region APIs

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 com.gemstone.gemfire.cache package. They correspond to declarations in the <cache> element for creating and configuring regions.
    • com.gemstone.gemfire.cache.Cache.createRegionFactory . This method takes a RegionShortcut enum to initiate region configuration, and returns a RegionFactory.
    • com.gemstone.gemfire.cache.RegionFactory. Provides methods to set individual region attributes and to create the region. The create call returns Region.
    • com.gemstone.gemfire.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 com.gemstone.gemfire.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.
    • com.gemstone.gemfire.cache.clientCache.createRegionFactory . This method takes a ClientRegionShortcut enum to initiate region configuration, and returns a ClientRegionFactory.
    • com.gemstone.gemfire.cache.client.ClientRegionFactory. Provides methods to set individual region attributes and to create the region. The create call returns Region.
    • com.gemstone.gemfire.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 com.gemstone.gemfire.cache package. They correspond to declarations under the <cache> and <client-cache> elements for creating and configuring regions.
    • com.gemstone.gemfire.cache.Region . Interface for managing your regions and their entries.
    • com.gemstone.gemfire.cache.RegionAttributes . Object holding region configuration settings.
    • com.gemstone.gemfire.cache.AttributesFactory. Can be used to create RegionAttributes to pass to RegionFactory and ClientRegionFactory.

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 and Region Shortcuts 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://schema.pivotal.io/gemfire/cache"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schema.pivotal.io/gemfire/cache http://schema.pivotal.io/gemfire/cache/cache-8.1.xsd"
          version="8.1"
          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:
      RegionFactory rf = cache.createRegionFactory(REPLICATE);
      Region pfloRegion = rf.create("Portfolios");

      With RegionFactory, if the cache does not already exist, it is created, then the region is created. The RegionFactory constructor is overloaded to accept member connection properties and region attributes.

    • Cache and Region API calls:
      // Create a region
      Cache cache = CacheFactory.create(system);
      AttributesFactory factory = new AttributesFactory();
      Region region = cache.createRegion("SampleRegion", factory.create());

Once you have created your regions, you can access them through the Cache and Region APIs as full region lists or individually.

Create and Access Data Subregions

An individual region can contain multiple subregions. You can use subregions to create a hierarchical namespace within your cache or to group cached objects for management purposes. The use of subregions is subject to the following restrictions:

  • A region with LOCAL scope can only have subregions with LOCAL scope.
  • You cannot create a subregion under a partitioned region or create a subregion with type PARTITION.
  • You cannot create a subregion that has different scope (GLOBAL, DISTRIBUTED_ACK, DISTRIBUTED_NO_ACK) settings than a region of the same name in another cache or than the parent region.
  • You cannot reuse an existing region or subregion name.

If the subregion is a distributed replicated region, it will be initialized with data from all other caches in this distributed system that have the same region.

You can create subregions using one of the following methods:

    • Declaration in the cache.xml:
      <?xml version="1.0"?>
      <cache
          xmlns="http://schema.pivotal.io/gemfire/cache"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schema.pivotal.io/gemfire/cache http://schema.pivotal.io/gemfire/cache/cache-8.1.xsd"
          version="8.1"
          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:
      RegionFactory rf = cache.createRegionFactory(REPLICATE);
      Region pfloRegion = rf.create("Portfolios");
         .createSubregion("Portfolios", "Private");

      With RegionFactory, if the cache does not already exist, the cache is created and then the region and subregion are created. The RegionFactory constructor is overloaded to accept member connection properties and region attributes.

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 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, Clear, and Destroy a Region

You can do these operations in three ways:
  • As automated data expiration actions.
  • As a gfsh destroy region command.
  • As API calls, through the Region instance:
    // Clear the local region
    Region.localClear(); 
    
    // Invalidate the entire distributed region 
    Region.InvalidateRegion(); 

You can remove all values or entries from the region or remove the region itself.

Operation type Behavior
Region invalidate Removes entry values from the region, leaving only data keys.
Region clear Removes entry keys and values from the region, leaving the region empty of data.
Region destroy Removes the region from the cache. For persistent regions, also removes data stored to disk.

Do this in the local cache only or as a distributed operation. The cache distributes the non-local operations according to the region’s scope.

Note: Local invalidate and clear cannot be performed in replicated regions as doing so would invalidate the replication contract.

These operations cause event notification. The CacheEvent object includes the flag getOperation.isExpiration that is set to true for events resulting from expiration activities and to false for all others.

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.

Using gfsh to Mange 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.

SeeCreating a Region with gfsh and Region Commands.