Configuring Regions

The region is the core building block of the GemFire distributed system. All cached data is organized into data regions and you do all of your data puts, gets, and querying activities against them.

In order to connect to a GemFire server, a client application must define a region that corresponds to a region on the server, at least in name. See Data Regions in the GemFire User Guide for details regarding server regions, and Region Attributes in this guide for client region configuration parameters.

You can create regions either programmatically or through declarative statements in a cache.xml file. Programmatic configuration is recommended, as it keeps the configuration close at hand and eliminates an external dependency. Region creation is subject to attribute consistency checks.

Programmatic Region Creation

To create a region:

1. Create a cache using CacheFactory to set its characteristics.
2. The cache includes an instance of PoolManager—use it to create a connection pool.
3. Use the cache to instantiate a RegionFactory and use it to create a region, specifying any desired attributes and an association with the connection pool.

C++ Region Creation Example

The following example illustrates how to create two regions with different characteristics using C++.

auto cache = CacheFactory()
    .set("log-level", "none")
    .create();

cache.getPoolManager()
    .createFactory()
    .addLocator("localhost", 10334)
    .create("examplePool");

auto regionFactory = cache.createRegionFactory(RegionShortcut::PROXY);
auto regionFactory2 = cache.createRegionFactory(RegionShortcut::CACHING_PROXY);

auto region = regionFactory
    .setPoolName("examplePool")
    .create("clientRegion1");

auto region2 = regionFactory2
    .setPoolName("examplePool")
    .setEntryTimeToLive(ExpirationAction::INVALIDATE, std::chrono::seconds(120))
    .create("clientRegion2");

Declarative Region Creation

Declarative region creation involves placing the region’s XML declaration, with the appropriate attribute settings, in a cache.xml file that is loaded at cache creation.

Like the programmatic examples above, the following example creates two regions with attributes and a connection pool:

<?xml version="1.0" encoding="UTF-8"?>
<client-cache
    xmlns="http://geode.apache.org/schema/cpp-cache"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://geode.apache.org/schema/cpp-cache
      http://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd"
    version="1.0">
    <pool name="examplePool" subscription-enabled="true">
        <server host="localhost" port="10334" />
    </pool>
    <region name="clientRegion1" refid="PROXY">
        <region-attributes pool-name="examplePool"/>
    </region>
    <region name="clientRegion2" refid="CACHING_PROXY">
        <region-attributes pool-name="examplePool">
            <region-time-to-live>
                <expiration-attributes timeout="120s" action="invalidate"/>
            </region-time-to-live>
        </region-attributes>
    </region>
</client-cache>
    

The cache.xml file contents must conform to the XML described in the cpp-cache-1.0.xsd file provided in your distribution’s xsds subdirectory and available online at https://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd.

Invalidating and Destroying Regions

Invalidation marks all entries contained in the region as invalid (with null values). Destruction removes the region and all of its contents from the cache.

You can execute these operations explicitly in the local cache in the following ways:

• Through direct API calls from the client using apache::geode::client::Region:invalidateRegion()
• Through expiration activities based on the region’s statistics and attribute settings.

In either case, you can perform invalidation and destruction as a local or a distributed operation.

• A local operation affects the region only in the local cache.
• A distributed operation works first on the region in the local cache and then distributes the operation to all other caches where the region is defined. This is the proper choice when the region is no longer needed, or valid, for any application in the distributed system.
• If the region on the server is configured as a partitioned region, it cannot be cleared using API calls from the client.

A user-defined cache writer can abort a region destroy operation. Cache writers are synchronous listeners with the ability to abort operations. If a cache writer is defined for the region anywhere in the distributed system, it is invoked before the region is explicitly destroyed.

Whether carried out explicitly or through expiration activities, invalidation and destruction cause event notification.

Region Access

You can use Cache::getRegion to retrieve a reference to a specified region.

Cache::getRegion returns nullptr if the region is not already present in the application’s cache. A server region must already exist.

A region name cannot contain these characters:

Ineligible Character description	Ineligible Character
whitespace	space or tab
angle brackets	<   >
colon	:
quote	"
forward slash and back slash	/   \
pipe (vertical bar)	|
question mark	?
asterisk	*

Getting the Region Size

The Region API provides a size method that gets the size of a region. For client regions, this gives the number of entries in the local cache, not on the servers. See the Region API documentation for details.