# Package org.apache.geode.cache

Provides an implementation of distributed object caching that can leverage GemFire's distribution capabilities.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AttributesMutator<K,V> | Supports modification of certain region attributes after the region has been created.
  Cache | Caches are obtained from the `CacheFactory.create()` method.
  CacheCallback | User-defined objects that can be plugged into caching to receive callback notifications.
  CacheEvent<K,V> | A region- or entry-related event affecting the cache.
  CacheListener<K,V> | A listener to handle region or entry related events.
  CacheLoader<K,V> | Allows data from outside of the VM to be placed into a region.
  CacheStatistics | Defines common statistics information for both region and entries.
  CacheTransactionManager | The CacheTransactionManager interface allows applications to manage transactions on a per `Cache` basis.
  CacheWriter<K,V> | A user-defined object defined in the `RegionAttributes` that is called synchronously before a region or entry in the cache is modified.
  ClientSession | Class `ClientSession` represents a client connection on the server.
  CustomExpiry<K,V> | This is the contract that a `custom-expiry` element must honor.
  Declarable | An object that can be described in a declarative caching XML file.
  DiskStore | Provides disk storage for one or more regions.
  DiskStoreFactory | Factory for creating instances of `DiskStore`.
  DiskWriteAttributes | Deprecated as of 6.5 use `DiskStore` instead
  DynamicRegionListener | `DynamicRegionListener` is an interface that can be implemented to handle dynamic region-related events.
  EntryEvent<K,V> | Contains information about an event affecting an entry, including its identity and the the circumstances of the event.
  EntryOperation<K,V> | Gemfire Context passed to `PartitionResolver` to compute the data location
  EvictionAttributesMutator | The EvictionAttributesMutator allows changes to be made to a `EvictionAttributes`.
  FixedPartitionResolver<K,V> | Implementers of interface `FixedPartitionResolver` helps to achieve explicit mapping of a "user defined" partition to a data member node.
  GemFireCache | GemFireCache represents the singleton cache that must be created in order to use GemFire in a Java virtual machine.
  InterestRegistrationEvent | Interface `InterestRegistrationEvent` encapsulated interest event information like region and keys of interest.
  InterestRegistrationListener | Interface `InterestRegisterationListener` provides the ability for applications to be notified of interest registration and unregistration events.
  LoaderHelper<K,V> | Provides a set of APIs to help the implementation of the `CacheLoader` load method.
  PartitionAttributes<K,V> | Attributes that define the partitioned character of a Partitioned Region.
  PartitionResolver<K,V> | Implementers of interface `PartitionResolver` enable custom standard partitioning on the `PartitionedRegion`. See `FixedPartitionResolver` to enable custom fixed partitioning.
  Region<K,V> | Manages subregions and cached data.
  Region.Entry<K,V> | A key-value pair containing the cached data in a region.
  RegionAttributes<K,V> | Defines attributes for configuring a region.
  RegionEvent<K,V> | Contains information about an event affecting a region, including its identity and the circumstances of the event.
  RegionMembershipListener<K,V> | A listener that can be implemented to handle region membership events.
  RegionRoleListener<K,V> | Deprecated this feature is scheduled to be removed
  RegionService | A RegionService provides access to existing `regions` that exist in a `GemFire cache`.
  RoleEvent<K,V> | Deprecated this feature is scheduled to be removed
  SerializedCacheValue<V> | Class `SerializedCacheValue` represents a serialized cache value.
  TransactionEvent | An event that describes the culmination of an entire transaction.
  TransactionId | The TransactionId interface is a "marker" interface that represents a unique GemFire transaction.
  TransactionListener | A listener that can be implemented to handle transaction related events.
  TransactionWriter | A callback that is allowed to veto a transaction.

- Class Summary
  Class | Description
  --- | ---
  AttributesFactory<K,V> | Deprecated as of 6.5 use `Cache.createRegionFactory(RegionShortcut)` or `ClientCache.createClientRegionFactory(ClientRegionShortcut)` instead.
  CacheFactory | Factory class used to create the singleton `cache` and connect to the GemFire singleton `distributed system`.
  DataPolicy | Enumerated type for region data policy.
  DiskWriteAttributesFactory | Deprecated as of 6.5 use `DiskStoreFactory` instead
  DynamicRegionFactory | Deprecated This class is deprecated.
  DynamicRegionFactory.Config | Configuration for dynamic region factory.
  EvictionAction | The action that an `EvictionAlgorithm` takes.
  EvictionAlgorithm | The algorithm used to determine when to perform an `EvictionAction`
  EvictionAttributes | Attributes that describe how a `Region`'s size is managed through an eviction controller.
  ExpirationAction | Enumerated type for expiration actions.
  ExpirationAttributes | Immutable parameter object for accessing and setting the attributes associated with `timeToLive` and `idleTimeout`.
  FixedPartitionAttributes | Composite date type used to distribute the attributes for a fixed partition.
  InterestPolicy | Enumerated type for region subscription interest policy.
  InterestResultPolicy | Class `InterestResultPolicy` is an enumerated type for a register interest result.
  LossAction | Deprecated this feature is scheduled to be removed
  MembershipAttributes | Deprecated this feature is scheduled to be removed
  MirrorType | Deprecated as of GemFire 5.0, use `DataPolicy` instead.
  Operation | Enumerated type for an event operation.
  PartitionAttributesFactory<K,V> | A factory that creates instances of `PartitionAttributes` which are used to create a partitioned `Region`.
  RegionFactory<K,V> | `RegionFactory` is used to create `regions` in a `cache`.
  RequiredRoles | Deprecated this feature is scheduled to be removed
  ResumptionAction | Deprecated this API is scheduled to be removed
  Scope | Enumerated type for region distribution scope.
  SubscriptionAttributes | Configuration attributes for defining subscriber requirements and behavior for a `Region`.

- Enum Summary
  Enum | Description
  --- | ---
  RegionShortcut | Each enum represents a predefined `RegionAttributes` in a `Cache`.

- Exception Summary
  Exception | Description
  --- | ---
  CacheClosedException | Indicates that the caching system has been closed.
  CacheException | A generic exception, which indicates a cache error has occurred.
  CacheExistsException | Thrown when attempting to create a `Cache` if one already exists.
  CacheLoaderException | Thrown from the `CacheLoader.load(org.apache.geode.cache.LoaderHelper<K, V>)` method indicating that an error occurred when a CacheLoader was attempting to load a value.
  CacheRuntimeException | A generic runtime exception that indicates a cache error has occurred.
  CacheWriterException | An exception thrown by a `CacheWriter` method.
  CacheXmlException | Thrown when a problem is encountered while parsing a declarative caching XML file.
  CommitConflictException | Thrown when a commit fails due to a write conflict.
  CommitDistributionException | Indicates that an attempt to notify required participants of a transaction involving one or more regions that are configured with `MembershipAttributes` may have failed.
  CommitIncompleteException | Thrown when a commit fails to complete due to errors
  DiskAccessException | Indicates that an `IOException` during a disk region operation.
  DuplicatePrimaryPartitionException | This exception is thrown when two nodes are defined with same primary partitions
  EntryDestroyedException | Indicates that a method was invoked on an entry that has been destroyed.
  EntryExistsException | Thrown when attempting to create a `Region.Entry` that already exists in the `Region`.
  EntryNotFoundException | Thrown when an operation is invoked on `Region` for an entry that doesn't exist in the `Region`.
  FailedSynchronizationException | Thrown when a cache transaction fails to register with the `UserTransaction` (aka JTA transaction), most likely the cause of the `UserTransaction`'s `javax.transaction.Status#STATUS_MARKED_ROLLBACK` status.
  GatewayConfigurationException | An exception indicating that a gateway configuration will not work with the remote side of the gateway's configuration.
  GatewayException | An exception thrown by a `Gateway`.
  IncompatibleVersionException | An `IncompatibleVersionException` that the client version was not compatible with the server version.
  LowMemoryException | Indicates a low memory condition either on the local or a remote `Cache`.
  NoQueueServersAvailableException | Indicates that this client cannot contact any queue servers and therefore cannot perform operations that require a queue, such as registering interest.
  NoSubscriptionServersAvailableException | Indicates that this client cannot contact any servers and therefore cannot perform operations that require subscriptions, such as registering interest.
  OperationAbortedException | Indicates that the operation that would have otherwise affected the cache has been aborted.
  PartitionedRegionDistributionException | Indicates a failure to perform a distributed operation on a Partitioned Region after multiple attempts.
  PartitionedRegionStorageException | Description of the conditions under which this exception is thrown
  RegionAccessException | Deprecated the MembershipAttributes API is scheduled to be removed
  RegionDestroyedException | Indicates that the region has been destroyed.
  RegionDistributionException | Deprecated the MembershipAttributes API is scheduled to be removed
  RegionExistsException | Indicates that the requested region already exists when a region is being created.
  RegionReinitializedException | Indicates that the region has been reinitialized.
  RegionRoleException | Deprecated this feature is scheduled to be removed
  ResourceException | A Generic exception to indicate that a resource exception has occurred.
  RoleException | Deprecated this feature is scheduled to be removed
  StatisticsDisabledException | Thrown if statistics are requested when statistics are disabled on the region.
  SynchronizationCommitConflictException | Thrown when a commit operation of a JTA enlisted cache transaction fails
  TimeoutException | Thrown if a `netSearch` times out without getting a response back from a cache, or when attempting to acquire a distributed lock.
  TransactionDataNodeHasDepartedException | Thrown when the transactional data host has shutdown or no longer has the data being modified by the transaction.
  TransactionDataNotColocatedException | Indicates that an attempt was made to transactionally modify multiple keys that are not colocated on the same data host.
  TransactionDataRebalancedException | Thrown when a `RebalanceOperation` occurs concurrently with a transaction.
  TransactionException | This is the superclass for all Exceptions that may be thrown by a GemFire transaction.
  TransactionInDoubtException | This Exception is thrown in presence of node failures, when GemFire cannot know with certainty about the outcome of the transaction.
  TransactionWriterException | Exception thrown by implementors of `TransactionWriter.beforeCommit(org.apache.geode.cache.TransactionEvent)` to signal that the current transaction should be aborted.
  UnsupportedOperationInTransactionException | Indicates that an attempt was mode to invoke an operation that is not allowed in a transaction.
  UnsupportedVersionException | An `UnsupportedVersionException` indicates an unsupported version.
  VersionException | An `VersionException` is an exception that indicates a client / server version mismatch exception has occurred.

## Package org.apache.geode.cache Description

Provides an implementation of distributed object caching that can leverage GemFire's distribution capabilities. Refer to the programmer's guide for performance guidelines.

- Function Execution
- Distributed Caching
- Cache Regions
- Partitioned Regions
- Region Entries
- Distribution and Consistency Models
- Storage Model
- Cache Loaders
- Cache Writers
- Expiration
- Cache Events
- Eviction Attributes
- Statistics
- Declarative Caching
- Client/Server Caching
- Cache Transactions
- Membership Attributes

## Function Execution

Back to Top

Function execution facilitates movement of behavior in the form of Functions executed using the Function Execution Service. A Function may generate results from parallel execution on many members , or several Cache Servers, or perhaps evaluating `Region` data. A ResultCollector collects and possibly processes those results for consumption. For more information look to the org.apache.geode.cache.execute package.

## Distributed Caching

Back to Top

GemFire's distributed caching implementation allows application data to be efficiently shared among multiple threads in a VM, multiple VMs running on the same physical machine, and multiple VMs running on multiple machines. Cached data resides in "regions" whose contents are stored in a VM's heap.

The `CacheFactory` class provides the entry point to the caching API. A `CacheFactory` is configured to create a "cache instance" that resides in the VM. The cache factory also allows the `DistributedSystem` to be configured.

## Cache Regions

Back to Top

Application data is cached in a "region". The `RegionFactory` class provides the simpliest entry point into the Region API. A `Region` implements `Map`, however, it also provides caching behavior such as data loading, eviction control, and distribution. Every region has a name and regions may be nested to provide a cache-naming hierarchy ("parent regions" with "subregions"). The root regions of the naming hierarchy (that is, the regions with no parent) are obtained with the `RegionService.rootRegions()` method. Any region may be obtained with the `RegionService.getRegion(java.lang.String)` method.

Region properties such as the region's cache loader, data policy, and storage model are specified by an instance of `RegionAttributes`. A region `RegionAttributes` object can be specified when creating a region.

## Partitioned Regions

Back to Top

Region data can be partitioned across many distributed system members to create one large logical heap. The data policy must be set to `DataPolicy.PARTITION` or `DataPolicy.PERSISTENT_PARTITION`. `PartitionAttributes` are used to configure a partitioned region. A partitioned region can be configured to be highly available, surviving the loss of one or more system members, by maintaining copies of data. These extra copies also benefit read operations by allowing load balancing across all the copies.

Partitioned Regions have the added feature of allowing storage sizes larger than a single Java VM can provide and with multiple Java VMs comes multiple garbage collectors, improving the performance of the entire Region in the face of a full garbage collection cycle.

Partitioned Regions support custom partitioning with the use of a `PartitionResolver` and can be associated together or colocated to allow for efficient data usage.

A `PartitionRegionHelper` class provides methods to facilitate usage of Partitioned Regions with other features, for example when used in conjunction with function execution.

## Region Entries

Back to Top

A region contains key/value pairs of objects known as the region's "entries". The `Region` class provides a number of methods for manipulating the region's entries such as `create`, `put`, `invalidate`, and `destroy` . The following diagram describes the life cycle of a region entry.

## Distribution and Consistency Models

Back to Top

A region's scope attribute determines how the region's entries will be distributed to other caches. A region with local scope will not distribute any of its changes to any other members of the distributed system, nor will it receive changes when another cache instance is updated.

When a change (such as a `put` or `invalidate`) is made to a region with non-local scope, that change is distributed to the other members of the distributed system that have created that region in their cache instance. There are three kinds of distributed scope, each of which guarantees a different level of consistency for distributed data. "Global" scope provides the highest level of data consistency by obtaining a distributed lock on a region entry before propagating a change to other members of the distributed system. With globally-scoped regions, only one thread in the entire distributed system may modify the region entry at a time.

"Distributed ACK" scope provides slightly weaker data consistency than global scope. With distributed ACK scope, the method that modifies the region (such as a call to `Region.destroy(java.lang.Object)`) will not return until an acknowledgment of the change has been received from every member of the distributed system. Multiple threads may modify the region concurrently, but the modifying thread may proceed knowing that its change to the region has been seen by all other members.

"Distributed NO ACK" scope provides the weakest data consistency of all the scopes, but also provides the best performance. A method invocation that modifies a region with distributed NO ACK scope will return immediately after it has updated the contents of the region in its own cache instance. The updates are distributed asynchronously.

## Storage Model

Back to Top

The contents of a region (that is, the region's key/value pairs) may be stored in either the JVM's heap or on a disk drive.

### Data Policy

Back to Top

A region's "data policy" attribute determines if data is stored in the local cache. The normal policy will store region data in the local cache. The empty policy will never store region data in the local cache. They act as proxy regions that distribute write operations to others and receive events from others. The replication policies may reduce the number of net searches that a caching application has to be perform, and can provide a backup mechanism. The replicated region initializes itself when it is created with the keys and value of the region as found in other caches. The replicate policy simply stores the relicate data in memory and the persistent replicate policy stores the data in memory and disk. The partition policies are used for partitioned regions. The partition policy simply stores the partitioned data in memory and the persistent partition policy stores the partitioned data in memory and disk.

### Disk Storage

GemFire supports several modes of region persistence as determined by the persistent data policies and the `RegionAttributes.getEvictionAttributes()`'s eviction action of overflow-to-disk. The following table summarizes the different modes and their configuration.

persistence | overflow-to-disk | mode | description
false | false | No Disk | The cache `Region` persists no data to the disk. This is the default configuration.
false | true | Disk for overflow only | Once the amount of data stored in the region exceeds the eviction controller's threshold, least recently used data is written to disk and removed from the VM until the region's size is below the threshold.
true | false | Disk for persistence | All data in the region is scheduled to be written to disk as soon as it is placed in the region. Thus, the data on disk contains a complete backup of the region. No information about recently used data is maintained and, therefore, the size of the VM will continue to grow as more data is added to the region. "Disk for persistence" mode is appropriate for situations in which the user wants to back up a region whose data fits completely in the VM.
true | true | Disk for overflow and persistence | All data in the region is scheduled to be written to disk as soon as it is placed in the region. But unlike "disk for persistence" mode, the least recently used data will be removed from the VM once the eviction controller's threshold is reached.

There are several things to keep in mind when working with regions that store data on disk.

- Operations (such as `invalidate` and `Region.destroy(java.lang.Object)`) that remove data from the cache also remove data from disk. In order for data to be removed from the VM and not from disk, EvictionAction.OVERFLOW_TO_DISK overflow} must be used.
- When disk overflow is enabled, only the value of the least recently used entry is removed from the VM. That is, the entry's key and the entry itself remain in the VM.
- When disk overflow is enabled, and backup is not then in each disk directory files whose name start with `OVERFLOW_` will be created. These files are deleted automatically when they are no longer being used. If a VM crashes it may not clean up its overflow files. In that case they will be cleaned up the next time the same region is created.
- GemFire will look for the value of a region entry on disk before it will look in other cache instances. That is, it will not perform a net search or a load if the value exists on disk.
- When data is read from or written to disk, no cache events are fired.
- Region operations such as destroy and invalidate effect the data that is stored on disk in addition to the data stored in the VM. That is, if an entry is destroyed in the VM (even by an `ExpirationAction`), it will also be destroyed on disk.

### Region backup and restore

Any GemFire resource that stores data on disk does so by configuring itself to use a `disk store`. Disk stores are created using the `disk store factory API` or by configuring them in XML using the "disk-store" element. Region's specify the disk store they are in by setting the `disk store name region attribute`.

A put on a region that is configured to have a disk "backup" (by using a persistent data policy) will result in the immediate scheduling of a disk write according to the region's `disk store` and the disk synchronous region attribute.

The actual backup data is stored in each of the disk store's specified disk directories. If any one of these directories runs out of space then any further writes to the backed up region will fail with a DiskAccessException. The actual file names begin with `BACKUP_`. If you wish to store a backup in another location or offline, then all of these files need to be saved. All of the files in the same directory must always be kept together in the same directory. It is ok to change the directory name.

When a region with a disk backup is created, it initializes itself with a "bulk load" operation that reads region entry data from its disk files. Note that the bulk load operation does not create cache events and it does not send update messages to other members of the distributed system. Bulk loading reads both the key and value of each region entry into memory. If region also has overflow-to-disk enabled then it will only load values until the LRU limit is reached. If the system property "gemfire.disk.recoverValues" is set to "false" then the entry values will not be loaded into memory during the bulk load but will be lazily read into the VM as they are requested.

A common high-availability scenario may involve replicated regions that are configured to have disk backups. When a replicated backup region is created in a distributed system that already contains a replicated backup region, GemFire optimizes the initialization of the backup region by streaming the contents of the backup file to the region being initialized. If there is no other replicated backup region in the distributed system, the backup file for the region being initialized may contain stale data. (That is, the value of region entries may have changed while the backup VM was down.) In this situation, the region being initialized will consult other VMs in the distributed system to obtain an up-to-date version of the cached data.

## Cache Loaders

Back to Top

A cache loader allows data from outside of the VM to be placed into a region. When `Region.get(java.lang.Object)` is called for a region entry that has a `null` value, the `load` method of the region's cache loader is invoked. The `load` method creates the value for the desired key by performing an operation such as a database query. The `load` may also perform a net search that will look for the value in a cache instance hosted by another member of the distributed system.

If a region was not created with a user-specified cache loader, the `get` operation will, by default, perform a special variation of net search: if the value cannot be found in any of the members of the distributed system, but one of those members has defined a cache loader for the region, then that remote cache loader will be invoked (a "net load") and the loaded value returned to the requester. Note that a net load does not store the loaded value in the remote cache's region.

## Cache Writers

Back to Top

The `CacheWriter` is a type of event handler that is invoked synchronously before the cache is modified, and has the ability to abort the operation. Only one CacheWriter in the distributed system is invoked before the operation that would modify a cache. A CacheWriter is typically used to update an external database.

## Expiration

Back to Top

Sometimes cached data has a limited lifetime. The region attributes regionTimeToLive, regionIdleTimeout, entryTimeToLive, and entryIdleTimeout, specify how data is handled when it becomes too old. There are two conditions under which cache data is considered too old: data has resided unchanged in a region for a given amount of time ("time to live") and data has not been accessed for a given amount of time ("idle time"). GemFire's caching implementation launches an "expiration thread" that periodically monitors region entries and will expire those that have become too old. When a region entry expires, it can either be invalidated, destroyed, locally invalidated, or locally destroyed.

## Cache Events

Back to Top

The `CacheListener` interface provides callback methods that are invoked synchronously in response to certain operations (such as a `put` or `invalidate`) being performed on a region. The event listener for a region is specified with the `setCacheListener` method. Each callback method on the `CacheListener` receives a `CacheEvent` describing the operation that caused the callback to be invoked and possibly containing information relevant to the operation (such as the old and new values of a region entry).

## Eviction Attributes

Back to Top

Before a new entry is created in a region, the region's eviction controller is consulted. The eviction controller may perform some action on the region (usually an action that makes the region smaller) based on certain criteria. For instance, an eviction controller could keep track of the sizes of the entry values. Before a new entry is added, the eviction controller could remove the entry with the largest value to free up space in the cache instance for new data. GemFire provides `EvictionAttributes` that will create an eviction controller that destroys the "least recently used" Region Entry once the Region exceeds a given number of entries.

## Statistics

Back to Top

The `CacheStatistics` class provides statistics information about the usage of a region or entry. Statistics are often used by eviction controllers to determine which entries should be invalidated or destroyed when the region reaches its maximum size.

## Declarative Caching

Back to Top

A "caching XML file" declares regions, entries, and attributes. When a `Cache` is created its contents can be initialized according to a caching XML file. The top level element must be a cache element.

The Document Type Definition for a declarative cache XML file can be found in `"doc-files/cache6_5.dtd"`. For examples of declarative cache XML files see example1, example2, and example3.

## Client/Server Caching

Back to Top

GemFire caches can be configured in a client/server hierarchy. In this configuration, GemFire cache regions are configured as clients to regions in GemFire server caches running in a separate distributed system. The GemFire servers are generally run as cacheserver processes. Clients are configured with a client cache which has a default pool that manages connections to the server caches which are used by the client regions. When a client updates its region, the update is forwarded to the server. When a client get results in a local cache miss, the get request is forwarded to the server. The clients may also subscribe to server-side events. For more information on the client see the client. For more information on the server see the server.

## Cache Transactions

Back to Top

The GemFire cache supports transactions providing enhanced data consistency across multiple Regions. GemFire Transactions are designed to run in a highly concurrent environment and as such have optimistic conflict behavior. They are optimistic in the sense that they assume little data overlap between transactions. Using that assumption, they do not reserve entries that are being changed by the transaction until the commit operation. For example, when two transactions operate on the same Entry, the last one to commit will detect a conflict and fail to commit. The changes made by the successful transaction are only available to other threads after the commit has finished, or in other words GemFire Transactions exhibit Read Committed behavior.

To provide application integration with GemFire transactions, a `TransactionListener` with associated `TransactionEvents` is provided as a `Cache` attribute. The listener is notified of commits, both failed and successful as well as explicit rollbacks. When a commit message is received by a distributed member with the same Region, again the TransactionListener is invoked.

GemFire transactions also integrate well with JTA transactions. If a JTA transaction has begun and an existing GemFire transaction is not already present, any transactional region operation will create a GemFire transaction and register it with the JTA transaction, causing the JTA transaction manager to take control of the GemFire commit/rollback operation.

Similar to JTA transactions, GemFire transactions are associated with a thread. Only one transaction is allowed at a time per thread and a transaction is not allowed to be shared amount threads. The changes made changed by a GemFire transaction are distributed to other distributed memebers as per the Region's Scope.

Finally, GemFire transactions allow for the "collapse" of multiple operations on an Entry, for example if an application destroys an Entry and follows with a `create` operation and then a `put` operations, all three operations are combined into one action reflecting the sum of all three.

## Membership Attributes

Back to Top

The GemFire region can be configured to require the presence of one or more user-defined membership roles. Each `Role` is assigned to any number of applications when each application connects to the GemFire distributed system. `MembershipAttributes` are then used to specify which roles are required to be online and present in that region's membership for access to the cache region being configured.

In addition to specifying which roles are required, `MembershipAttributes` are used to specify the `LossAction`. The loss action determines how access to the region is affected when one or more required roles are offline and no longer present in the system membership. The region can be made completely "NO_ACCESS", which means that the application cannot read from or write to that region. "LIMITED_ACCESS" means that the application cannot write to that region. "FULL_ACCESS" means that the application can read from and write to that region as normal. If "FULL_ACCESS" is selected, then the application would only be aware of the missing required role if it registered a `RegionRoleListener`. This listener provides callbacks to notify the application when required roles are gained or lost, thus providing for custom integration of required roles with the application.

`ResumptionAction` defined in the `MembershipAttributes` specifies how the application responds to having a missing required role return to the distributed membership. "None" results in no special action, while "Reinitialize" causes the region to be reinitialized. Reinitializing the region will clear all entries from that region. If it is a replicate, the region will repopulate with entries available from other distributed members.

`RequiredRoles` provides methods to check for missing required roles for a region and to wait until all required roles are present. In addition, this class can be used to check if a role is currently present in a region's membership.