DynamicRegionFactory provides a distributed region creation service. Any other member of the
GemFire DistributedSystem that has created an instance of this class will automatically
instantiate regions created through the factory from anywhere else in the DistributedSystem.
Instructions for Use:
- If your application is a client in a client/server installation, either specify the pool name
in the
DynamicRegionFactory.Config you'll use to create a DynamicRegionFactory or
specify it in a dynamic-region-factory element in your cache.xml.
- Before you've created a GemFire Cache in your application, add a line of code as follows:
{
DynamicRegionFactory factory = DynamicRegionFactory.get();
factory.open(config);
}
{
DynamicRegionFactory myFactoryHandle = DynamicRegionFactory.get().open(config);
}
or just use a dynamic-region-factory element in the cache.xml.
- Create the GemFire Cache. During cache creation, the list of dynamic Regions will either be
discovered by recovering their names from disk (see
DynamicRegionFactory.Config#persistBackup) or from other members of the distributed
system. These dynamic Regions will be created before Cache creation completes.
- Thereafter, when you want to create dynamic distributed Regions, create them using the
#createDynamicRegion. Regions created with the factory will inherit their
RegionAttributes from their parent Region, though you can override callbacks when you configure
the factory.
All other instances of GemFire across the distributed system that instantiate and open a
DynamicRegionFactory will also get the dynamic distributed Regions.
- Non-dynamic parent Regions should be declared in cache.xml so that they can be created before
the dynamic Region factory goes active and starts creating Regions. You will have cache creation
problems if this isn't done.
- A DynamicRegionListener can be registered before open is called and before cache creation so
that the listener will be called if dynamic Regions are created during cache creation.
Saving the factory on disk: If
DynamicRegionFactory.Config#persistBackup is configured
for the factory, dynamic Region information is written to disk for recovery. By default the
current directory is used for this information. The
DynamicRegionFactory.Config#diskDircan be used to change this default.
Registering interest in cache server information: The
DynamicRegionFactory.Config#registerInterest setting determines whether clients will
register interest in server keys or not. You will generally want this to be turned on so that
clients will see updates made to servers. In server processes, DynamicRegionFactory forces use of
NotifyBySubscription.
Notes:
- DynamicRegionFactories in non-client VMs must not be configured with a pool.
- If
#open() is called before cache creation and the cache.xml has a
dynamic-region-factory element then the cache.xml will override the open call's configuration.
- Since the RegionAttributes of a dynamically created Region are copied from the parent Region,
any callbacks, (
CacheListener,
CacheWriter, and
CacheLoader are shared by
the parent and all its dynamic children so make sure the callback is thread-safe and that its
CacheCallback#close implementation does not stop it from functioning. However the
products EvictionAlgorithm instances will be cloned so that each dynamic Region has its own
callback.
- The root Region name "DynamicRegions" is reserved. The factory creates a root Region of that
name and uses it to keep track of what dynamic Regions exist. Applications should not directly
access this Region; instead use the methods on this factory.