|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|AttributesMutator||Supports modification of certain region attributes after the region has been created.|
|Cache||Caches are obtained from static methods on the
|CacheCallback||User-defined objects that can be plugged into caching to receive callback notifications.|
|CacheEvent||A region- or entry-related event affecting the cache.|
|CacheListener||A listener that can be implemented to handle region- or entry-related events.|
|CacheLoader||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
|CacheWriter||A user-defined object defined in the
|Declarable||An object that can be described in a declarative caching XML file.|
|DiskWriteAttributes||Immutable parameter object for describing how region entries should be written to disk.|
|EntryEvent||Contains information about an event affecting an entry, including its identity and the the circumstances of the event.|
|EvictionAttributesMutator||The EvictionAttributesMutator allows changes to be made to a
|LoaderHelper||Provides a set of APIs to help the
implementation of the
|PartitionAttributes||Attributes that define the partitioned character of a Partitioned Region.|
|Region||Manages subregions and cached data.|
|Region.Entry||A key-value pair containing the cached data in a region.|
|RegionAttributes||Defines attributes for configuring a region.|
|RegionEvent||Contains information about an event affecting a region, including its identity and the circumstances of the event.|
|RegionMembershipListener||A listener that can be implemented to handle region membership events.|
|RegionRoleListener||A listener that can be implemented to handle region reliability membership events.|
|RoleEvent||Contains information about an event affecting a region reliability, including its identity and the circumstances of the event.|
|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.|
|AttributesFactory||Creates instances of
|CacheFactory||A factory class that must be used to obtain instances of
|DataPolicy||Enumerated type for region data policy.|
|DiskWriteAttributesFactory||Factory for getting DiskWriteAttribute objects|
|DynamicRegionFactory||DynamicRegionFactory provides a distributed region creation service.|
|DynamicRegionFactory.Config||Configuration for dynamic region factory.|
|EvictionAction||The action that an
|EvictionAlgorithm||The algorithm used to determine when to perform an
|EvictionAttributes||Attributes that describe how a
|ExpirationAction||Enumerated type for expiration actions.|
|ExpirationAttributes||Immutable parameter object for accessing and setting the attributes associated with
|InterestPolicy||Enumerated type for region subscription interest policy.|
|LossAction||Specifies how access to the region is affected when one or more required roles are lost.|
|MembershipAttributes||Configuration attributes for defining reliability requirements and behavior
|MirrorType||Deprecated. as of GemFire 5.0, use
|NotAvailable||Singleton token indicating an unavailable object, used in EntryEvent|
|Operation||Enumerated type for an event operation.|
A factory that creates instances of
|RequiredRoles||Provides information on presence or absence of a
|ResumptionAction||Specifies how the region is affected by resumption of reliability when one or more missing required roles return to the distributed membership.|
|Scope||Enumerated type for region distribution scope.|
|SubscriptionAttributes||Configuration attributes for defining subscriber requirements and behavior
|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
|CacheLoaderException||Thrown from the
|CacheRuntimeException||A generic runtime exception that indicates a cache error has occurred.|
|CacheWriterException||An exception thrown by a
|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
|DiskAccessException||Indicates that an
|EntryDestroyedException||Indicates that a method was invoked on an entry that has been destroyed.|
|EntryExistsException||Thrown when attempting to create a
|EntryNotFoundException||Thrown when an operation is invoked on
|EntryNotFoundInRegion||Deprecated. this class is no longer in use|
|FailedSynchronizationException||Thrown when a cache transaction fails to register with the
|GatewayException||An exception thrown by a
|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||Indicates that an attempt to access the region has failed.|
|RegionDestroyedException||Indicates that the region has been destroyed.|
|RegionDistributionException||Indicates that an attempt to send a distributed cache event to one or more
|RegionExistsException||Indicates that the requested region already exists when a region is being created.|
|RegionReinitializedException||Indicates that the region has been reinitialized.|
|RegionRoleException||Indicates that a
|RoleException||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
Provides an implementation of distributed object caching that can leverage GemFire's distribution capabilities. Refer to the programmer's guide for performance guidelines.
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.
CacheFactory class provides
the entry point to the caching API. A
configured to create a "cache instance" that resides in the VM. The cache may configured
to be part of a
Application data is cached in a "region". The
RegionFactory class provides the simpliest
entry point into the Region
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
Region properties such as the region's cache loader, mirroring policy, and
storage model are specified by an instance of
RegionAttributes. A region
RegionAttributes object can be specified when creating a
Region data can be partitioned across many distributed system members to create one large logical heap.
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.
As of GemFire 5.0, Partitioned Regions do not support the following GemFire features:
A region contains key/value pairs of objects known as the region's
Region class provides a number of methods for
manipulating the region's entries such as
destroy . The following
diagram describes the life cycle of a region entry.
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
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
"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.
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.
GemFire supports several modes of region persistence as determined
RegionAttributes.getEvictionAttributes()'s eviction action and persistBackup configuration attributes. The following table
summarizes the different modes and their configuration.
|false||No eviction controller or a eviction controller with an eviction action other than "overflow to disk"||No Disk||The cache
|false||An eviction controller using an EvictionAlgorithm with an eviction action of overflow to disk.||Disk for overflow||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||No evcition controller or an eviction controller with an eviction action other than "overflow to disk"||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||An eviction controller using an EvictionAlgorithm with an eviction action of overflow to disk.||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, least recently used data will only 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.
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.
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.
ExpirationAction), it will also be destroyed on disk.
A put on a region
that is configured to have a disk "backup" (
true) will result in the immediate scheduling of a
disk write according to the region's
(synchronous or asynchronous).
The actual backup data is stored in each of the 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
KEYS_. 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. Additionally, bulk loading reads only the keys of the region entries and not the values. Entry values will be lazily read into the VM as they are requested.
A common high-availability scenario may involve mirrored regions that are configured to have disk backups. When a mirrored backup region is created in a distributed system that already contains a mirrored 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 mirrored 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.
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
creates the value for the desired key by performing an operation such
as a database query. The
load may also perform a
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.
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.
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.
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 store the relicate data in memory and the the persistent replicate policy stores the data in memory and disk.
interface provides callback methods that are invoked synchronously in
response to certain operations (such as a
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).
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.
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
A "caching XML file" declares regions, entries, and attributes. When
Cache is created its contents can be initialized
according to a caching XML file.
The Document Type Definition for a declarative cache XML file can
be found in
"doc-files/cache5_0.dtd" and examples of
declarative cache XML files can be found here, here, and here.
Hierarchical CachingBack to Top
GemFire caches can be configured in a distributed hierarchical configuration. In this configuration, there are GemFire cache instances at the edge (a.k.a. Edge Caches) that talk to GemFire instances that sit in the backend (a.k.a. Server caches). The edge cache talks to the server cache when it records a miss. The server cache can either fulfill the request or it can load the data from the database and return it to the edge cache. The loaded data is cached on the server cache and used to serve future requests from edge caches. The communication between the edge and the server is implemented using a custom cache loader at the edge and a cache server process on the server.The cache loader transmits requests to the cache server which in turn looks in its local cache to fulfill the request. The custom cache loader and cache server use a communication protocol that is designed to reduce latency and provide failover capabilities.
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
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 AttributesBack 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
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
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.
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 replicated mirror, the
region will repopulate with entries available from other distributed
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.
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|