Data Region Management
Data Region Management
Pivotal 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.
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. Use createRegionFactory(), not "new RegionFactory," to create 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.
- 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.
- Define any region attributes that are not provided in the shortcut you chose.
- Create a region using any of the
- gfsh. After starting up servers, a JMX manager and connecting to
the cluster, execute the following
gfsh>create region --name=Portfolios --type=REPLICATE
- Declaration in the
<?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");
- gfsh. After starting up servers, a JMX manager and connecting to the cluster, execute the following command:
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. 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://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");
Region method calls with a recursive parameter operate on the given region(s) and then recursively on all contained subregions.
- Declaration in the cache.xml:
Update Data Regions
- 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
- As automated data expiration actions.
- As a gfsh destroy region command.
- As API calls, through the
// 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.
|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.
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
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 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.See Creating a Region with gfsh and Region Commands.