public interface Region<K,V> extends ConcurrentMap<K,V>
The Region interface basically contains two set of APIs: Region management
APIs; and (potentially) distributed operations on entries. Non-distributed
operations on entries
are provided by the inner interface, Region.Entry
.
Each Cache
defines a single top region called the root region.
User applications can use the root region to create subregions
for isolated name space and object grouping.
A region's name can be any String except that it should not contain
the region name separator, a forward slash (/).
Region
s can be referenced by a relative path name from any region
higher in the hierarchy in getSubregion(java.lang.String)
. You can get the relative
path from the root region with getFullPath()
. The name separator
is used to concatenate all the region names together from the root, starting
with the root's subregions.
Relative region names can provide a convenient method to locate a subregion directly from some higher region. For example, a region structure is as follows: a region named 3rd_level_region has parent region 2nd_level_region; region 2nd_level_region in turn has parent region 1st_level_region; and region 1st_level_region is a child of the root region. Then,the user can get the region 3rd_level_region from the root region by issuing:
region3 = root.getSubregion("1st_level_region/2nd_level_region/3rd_level_region");
or the user can get the region 3rd_level_region from region 1st_level_region
by issuing
region3 = region1.getSubregion("2nd_level_region/3rd_level_region");
Region entries are identified by their key. Any Object can be used as a key as long as the key Object is region-wide unique and implements both the equals and hashCode methods. For regions with distributed scope, the key must also be Serializable.
Regions and their entries can be locked. The Lock
obtained from getRegionDistributedLock()
is a distributed lock on the
entire Region, and the Lock
obtained from
getDistributedLock(java.lang.Object)
is a distributed lock on the individual
entry.
If the scope is Scope.GLOBAL
, the methods
that modify, destroy, or invalidate the entries in this region will also get a
distributed lock. See the documentations for getDistributedLock(java.lang.Object)
and
getRegionDistributedLock()
for details on the implicit locking that
occurs for regions with Scope.GLOBAL
.
Unless otherwise specified, all of these methods throw a
CacheClosedException
if the Cache is closed at the time of
invocation, or a RegionDestroyedException
if this region has been
destroyed.
Serializability Requirements for arguments: Several methods in the region API
take parameters such as key, value and callback parameters.All of these parameters
are typed as objects.
For distributed regions, keys, values and callback parameters have to be serializable
Failure to meet these serialization requirements
causes API methods to throw IllegalArgumentException.
Implementation of the java.util.concurrent.ConcurrentMap interface was added in version 6.5. These methods give various levels of concurrency guarantees based on the scope and data policy of the region. They are implemented in the peer cache and client/server cache but are disallowed in peer Regions having NORMAL or EMPTY data policies.
The semantics of the ConcurrentMap methods on a Partitioned Region are consistent with those expected on a ConcurrentMap. In particular multiple writers in different JVMs of the same key in the same Partitioned Region will be done atomically.
The same is true for a region with GLOBAL scope. All operations will be done atomically since a distributed lock will be held while the operation is done.
The same is true for a region with LOCAL scope. All ops will be done atomically since the underlying map is a concurrent hash map and no distribution is involved.
For peer REPLICATE and PRELOADED regions atomicity is limited to threads in the JVM the operation starts in. There is no coordination with other members of the system unless the operation is performed in a transaction.
For client server regions the atomicity is determined by the scope and data policy of the server region as described above. The operation is actually performed on the server as described above. Clients will always send the ConcurrentMap operation to the server and the result returned by the ConcurrentMap method in client will reflect what was done on the server. Same goes for any CacheListener called on the client. Any local state on the client will be updated to be consistent with the state change made on the server.
RegionAttributes
,
AttributesFactory
,
AttributesMutator
,
Region.Entry
Modifier and Type | Interface and Description |
---|---|
static interface |
Region.Entry<K,V>
A key-value pair containing the cached data in a region.
|
Modifier and Type | Field and Description |
---|---|
static String |
SEPARATOR
The region name separator character, represented as a string for convenience.
|
static char |
SEPARATOR_CHAR
The region name separator character.
|
Modifier and Type | Method and Description |
---|---|
void |
becomeLockGrantor()
Specifies this member to become the grantor for this region's lock
service.
|
void |
clear()
Removes all entries from this region.
|
void |
close()
Does a localDestroyRegion, but leaves behind the disk files if this
is a region with persistBackup set to true.
|
boolean |
containsKey(Object key)
Returns whether the specified key currently exists in this region.
|
boolean |
containsKeyOnServer(Object key)
Returns whether the specified key currently exists in this region on the
server.
|
boolean |
containsValue(Object value)
Returns true if this region maps one or more keys to the specified value.
|
boolean |
containsValueForKey(Object key)
Returns whether there is a valid (non-null) value present for the specified
key.
|
void |
create(K key,
V value)
Creates a new entry in this region with the specified key and value.
|
void |
create(K key,
V value,
Object aCallbackArgument)
Creates a new entry in this region with the specified key and value,
providing a user-defined parameter
object to any
CacheWriter invoked in the process. |
<SK,SV> Region<SK,SV> |
createSubregion(String subregionName,
RegionAttributes<SK,SV> aRegionAttributes)
Deprecated.
|
V |
destroy(Object key)
Destroys the entry with the specified key.
|
V |
destroy(Object key,
Object aCallbackArgument)
Destroys the entry with the specified key, and provides a user-defined
parameter object to any
CacheWriter invoked in the process. |
void |
destroyRegion()
Destroys the whole region.
|
void |
destroyRegion(Object aCallbackArgument)
Destroys the whole region and provides a user-defined parameter
object to any
CacheWriter invoked in the process. |
Set<Region.Entry<?,?>> |
entries(boolean recursive)
Deprecated.
Use
entrySet(boolean recursive) instead. |
Set<Map.Entry<K,V>> |
entrySet()
Returns the
Set of Region.Entry objects in this region. |
Set<Region.Entry<?,?>> |
entrySet(boolean recursive)
Returns the
Set of Region.Entry objects in this region. |
boolean |
equals(Object other)
Compares the specified object with this region for equality.
|
boolean |
existsValue(String queryPredicate)
Determines whether there is a value in this
Region
that matches the given queryPredicate . |
void |
forceRolling()
Deprecated.
use
DiskStore.forceRoll() instead. |
V |
get(Object key)
Returns the value associated with the specified key.
|
V |
get(Object key,
Object aCallbackArgument)
Returns the value associated with the specified key, passing the callback
argument to any cache loaders or cache writers that are invoked in the
operation.
|
Map<K,V> |
getAll(Collection<?> keys)
Gets values for all the keys in the input Collection.
|
<T extends K> |
getAll(Collection<T> keys,
Object aCallbackArgument)
Gets and returns values for all the keys in the input Collection.
|
RegionAttributes<K,V> |
getAttributes()
Returns the
RegionAttributes for this region. |
AttributesMutator<K,V> |
getAttributesMutator()
Returns a mutator object used for modifying this region's attributes
after region creation.
|
Cache |
getCache()
Deprecated.
as of 6.5 use
getRegionService() instead. |
Lock |
getDistributedLock(Object key)
For
Scope.GLOBAL regions, gets a distributed
lock on the entry with the specified key. |
Region.Entry<K,V> |
getEntry(Object key)
Returns the
Region.Entry for the specified key, or null if it doesn't
exist. |
String |
getFullPath()
Returns the full path of this region starting with a forward slash, followed
by the root, including every subregion in the path to this region.
|
List<K> |
getInterestList()
Returns the list of keys on which this client is interested and will be
notified of changes.
|
List<String> |
getInterestListRegex()
Returns the list of regular expresssions on which this client is interested
and will be notified of changes.
|
String |
getName()
Returns the name of this region.
|
<PK,PV> Region<PK,PV> |
getParentRegion()
Gets the parent region of this region.
|
Lock |
getRegionDistributedLock()
For
Scope.GLOBAL regions, gets a distributed
lock on this whole region. |
RegionService |
getRegionService()
Returns the
cache associated with this region. |
RegionSnapshotService<K,V> |
getSnapshotService()
Obtains the snapshot service to allow the cache data to be imported
or exported.
|
CacheStatistics |
getStatistics()
Returns the
CacheStatistics for this region. |
<SK,SV> Region<SK,SV> |
getSubregion(String path)
Returns a subregion with the specified name or null if doesn't exist.
|
Object |
getUserAttribute()
Returns the application-defined object associated with this region.
|
int |
hashCode()
Returns the hash code value for this region.
|
void |
invalidate(Object key)
Invalidates the entry with the specified key.
|
void |
invalidate(Object key,
Object aCallbackArgument)
Invalidates the entry with the specified key,
and provides a user-defined argument to the
CacheListener . |
void |
invalidateRegion()
Invalidates this region.
|
void |
invalidateRegion(Object aCallbackArgument)
Invalidates this region.
|
boolean |
isDestroyed()
Returns whether this region has been destroyed.
|
boolean |
isEmpty()
Returns true if this region contains no entries.
|
Set<K> |
keys()
Deprecated.
Use
keySet instead; |
Set<K> |
keySet()
Returns a set of keys in the region.
|
Set<K> |
keySetOnServer()
Returns a set of keys in the region on the server.
|
void |
loadSnapshot(InputStream inputStream)
Deprecated.
as of 7.0 use
getSnapshotService() |
void |
localClear()
Removes all local entries from this region.
|
void |
localDestroy(Object key)
Destroys the value with the specified key in the local cache only,
No
CacheWriter is
invoked. |
void |
localDestroy(Object key,
Object aCallbackArgument)
Destroys the value with the specified key in the local cache
only, and provides a user-defined
parameter object to the
CacheListener , if any. |
void |
localDestroyRegion()
Destroys the whole region in the local cache only.
|
void |
localDestroyRegion(Object aCallbackArgument)
Destroys the whole region in the local cache only, and provides a
user-defined argument to a
CacheListener if any. |
void |
localInvalidate(Object key)
Invalidates the value with the specified key in the local cache only.
|
void |
localInvalidate(Object key,
Object aCallbackArgument)
Invalidates the value with the specified key in the local cache only,
and provides a user-defined argument to the
CacheListener . |
void |
localInvalidateRegion()
Invalidates this region in the local cache only.
|
void |
localInvalidateRegion(Object aCallbackArgument)
Invalidates this region in the local cache only,
and provides a user-defined argument to the
CacheListener . |
V |
put(K key,
V value)
Places a new value into an entry in this region with the specified key.
|
V |
put(K key,
V value,
Object aCallbackArgument)
Places a new value into an entry in this region with the specified key,
providing a user-defined parameter
object to any
CacheWriter invoked in the process. |
void |
putAll(Map<? extends K,? extends V> map)
Copies all of the entries from the specified map to this region.
|
void |
putAll(Map<? extends K,? extends V> map,
Object aCallbackArgument)
Copies all of the entries from the specified map to this region.
|
V |
putIfAbsent(K key,
V value)
If the specified key is not already associated
with a value, associate it with the given value.
|
<E> SelectResults<E> |
query(String queryPredicate)
Filters the values of this region using the
queryPredicate . |
void |
registerInterest(K key)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterest(K key,
boolean isDurable)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterest(K key,
boolean isDurable,
boolean receiveValues)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterest(K key,
InterestResultPolicy policy)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterest(K key,
InterestResultPolicy policy,
boolean isDurable)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterest(K key,
InterestResultPolicy policy,
boolean isDurable,
boolean receiveValues)
Sends a request to the CacheServer to register interest in a key for
this client.
|
void |
registerInterestRegex(String regex)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
void |
registerInterestRegex(String regex,
boolean isDurable)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
void |
registerInterestRegex(String regex,
boolean isDurable,
boolean receiveValues)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
void |
registerInterestRegex(String regex,
InterestResultPolicy policy)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
void |
registerInterestRegex(String regex,
InterestResultPolicy policy,
boolean isDurable)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
void |
registerInterestRegex(String regex,
InterestResultPolicy policy,
boolean isDurable,
boolean receiveValues)
Sends a request to the CacheServer to register interest in a regular
expression pattern for this client.
|
V |
remove(Object key)
Removes the entry with the specified key.
|
boolean |
remove(Object key,
Object value)
Removes the entry for a key only if currently mapped to a given value.
|
void |
removeAll(Collection<? extends K> keys)
Removes all of the entries for the specified keys from this region.
|
void |
removeAll(Collection<? extends K> keys,
Object aCallbackArgument)
Removes all of the entries for the specified keys from this region.
|
V |
replace(K key,
V value)
Replaces the entry for a key only if currently mapped to some value.
|
boolean |
replace(K key,
V oldValue,
V newValue)
Replaces the entry for a key only if currently mapped to a given value.
|
void |
saveSnapshot(OutputStream outputStream)
Deprecated.
as of 7.0 use
getSnapshotService() |
Object |
selectValue(String queryPredicate)
Selects the single value in this
Region that matches
the given query predicate . |
void |
setUserAttribute(Object value)
Sets the application-defined object associated with this region.
|
int |
size()
Returns the number of entries present in this region.
|
Set<Region<?,?>> |
subregions(boolean recursive)
Returns a Set of all subregions.
|
void |
unregisterInterest(K key)
Sends a request to the CacheServer to unregister interest in a key for
this client.
|
void |
unregisterInterestRegex(String regex)
Sends a request to the CacheServer to unregister interest in a regular
expression pattern for this client.
|
Collection<V> |
values()
Returns a Collection of values in this region.
|
void |
writeToDisk()
Deprecated.
use
DiskStore.flush() instead. |
static final char SEPARATOR_CHAR
static final String SEPARATOR
String getName()
Does not throw a CacheClosedException
or a
RegionDestroyedException
.
String getFullPath()
Does not throw a CacheClosedException
or a
RegionDestroyedException
.
<PK,PV> Region<PK,PV> getParentRegion()
Does not throw a CacheClosedException
or a
RegionDestroyedException
.
createSubregion
RegionAttributes<K,V> getAttributes()
RegionAttributes
for this region.
This object is backed by this region, so if attributes
are modified using this region's AttributesMutator
,
this RegionAttributes
object will immediately reflect the change.
Does not throw a CacheClosedException
or a
RegionDestroyedException
.
RegionAttributes
of this regioncreateSubregion(String, RegionAttributes)
,
AttributesMutator
,
AttributesFactory
,
getAttributesMutator()
AttributesMutator<K,V> getAttributesMutator()
AttributesMutator
objectgetAttributes()
CacheStatistics getStatistics() throws StatisticsDisabledException
CacheStatistics
for this region.CacheStatistics
of this regionStatisticsDisabledException
- if statistics have been disabled for this regionUnsupportedOperationException
- If the region is a partitioned regionvoid invalidateRegion() throws TimeoutException
invalidateRegion
, this region and the entries in it still
exist. To remove all the entries and this region,
destroyRegion
should be used. The region invalidate will be distributed
to other caches if the scope is not Scope.LOCAL
.
Does not update any CacheStatistics
.
LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
CacheListener.afterRegionInvalidate(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void invalidateRegion(Object aCallbackArgument) throws TimeoutException
invalidateRegion
, the region and the entries in it still
exist. In order to remove all the entries and the region,
destroyRegion
should be used. The region invalidate will be distributed
to other caches if the scope is not Scope.LOCAL
.
Does not update any CacheStatistics
.
aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBAL
TimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
IllegalArgumentException
- if aCallbackArgument is not serializableCacheListener.afterRegionInvalidate(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void localInvalidateRegion()
invalidateRegion
, this region and the entries in it still
exist. To remove all the entries and this region,
destroyRegion should be used.
Does not update any CacheStatistics
.IllegalStateException
- if this region is distributed and
replicated
UnsupportedOperationException
- If the region is a partitioned regionCacheListener.afterRegionInvalidate(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void localInvalidateRegion(Object aCallbackArgument)
CacheListener
.
The invalidation will cascade to
all the subregions and cached entries. After
the invalidateRegion
, the region and the entries in it still
exist. In order to remove all the entries and the region,
destroyRegion should be used.
Does not update any CacheStatistics
.aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null.IllegalStateException
- if the region is distributed and
replicated
UnsupportedOperationException
- If the region is a partitioned regionCacheListener.afterRegionInvalidate(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void destroyRegion() throws CacheWriterException, TimeoutException
RegionDestroyedException
.
The region destroy will be distributed to other caches if the scope is
not Scope.LOCAL
.
Does not update any CacheStatistics
.
CacheWriterException
- if a CacheWriter aborts the operation; if this
occurs some subregions may have already been successfully destroyed.LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheListener.afterRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
,
CacheWriter.beforeRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void destroyRegion(Object aCallbackArgument) throws CacheWriterException, TimeoutException
CacheWriter
invoked in the process.
Destroy cascades to all entries
and subregions. After the destroy, this region object can not be used
any more. Any attempt to use this region object will get a
RegionDestroyedException
exception. The region destroy is
distributed to other caches if the scope is not Scope.LOCAL
.
Does not update any CacheStatistics
.
aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.CacheWriterException
- if a CacheWriter aborts the operation; if this
occurs some subregions may have already been successfully destroyed.LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALIllegalArgumentException
- if aCallbackArgument is not serializableCacheListener.afterRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
,
CacheWriter.beforeRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void localDestroyRegion()
CacheWriter
is invoked.
Destroy cascades to all entries and subregions.
After the destroy, this region object can not be used
any more and any attempt to use this region object will get
RegionDestroyedException
exception.
This operation is not distributed to any other cache.
Does not update any CacheStatistics
.
void localDestroyRegion(Object aCallbackArgument)
CacheListener
if any.
No CacheWriter
is invoked.
Destroy will cascade to all the entries
and subregions. After the destroy, this region object can not be used
any more. Any attempt to use this region object will get
RegionDestroyedException
exception.
Does not update any CacheStatistics
.
aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this call. Can be null.CacheListener.afterRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void close()
CacheListener.afterRegionDestroy(com.gemstone.gemfire.cache.RegionEvent<K, V>)
on each cache listener
on the closed region(s).
Also calls CacheCallback.close()
on each callback on the closed
region(s).
Does not update any CacheStatistics
.
RegionSnapshotService<K,V> getSnapshotService()
void saveSnapshot(OutputStream outputStream) throws IOException
getSnapshotService()
outputStream
- the output stream to write toIOException
- if encountered while writing the fileUnsupportedOperationException
- If the region is a partitioned regionloadSnapshot(java.io.InputStream)
void loadSnapshot(InputStream inputStream) throws IOException, ClassNotFoundException, CacheWriterException, TimeoutException
getSnapshotService()
replicated
remote regions will do
a new getInitialImage operation to get the data from this snapshot. Any
existing references to this region or any region that is reinitialized in
this manner become unusable in that any subsequent methods invoked on those
references will throw a RegionReinitializedException (which is a subclass
of RegionDestroyedException).In order to continue working with this region, a new reference needs to be acquired using Cache#getRegion or Region#getSubregion (which will block until reinitialization is complete).
NOTE: SUBREGIONS ARE DESTROYED. Since loading a snapshot effectively destroys the region and recreates it, all subregions of this region in this cache as well as other remote caches in the same distributed system are destroyed.
If any error occurs while loading the snapshot, this region is destroyed and threads in remote caches that are attempting to get a reference to this region will get null instead of a region reference. The only callbacks that are invoked are called for the destroyRegion operation, i.e. the CacheWriter and the close methods on callbacks. CacheListeners and other callback objects have their close() methods called when the region is destroyed, and then those same callback objects will be reinstalled on the new region. Therefore, the callback objects should be able to handle a close() followed by events associated with the newly created region.
inputStream
- the inputStream to load the snapshot fromClassNotFoundException
- if a class cannot be found while loading
dataIOException
- if error encountered while reading file.CacheWriterException
- if a CacheWriter aborts the destroyRegion
operation; if this occurs some subregions may have already been
successfully destroyed.LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALUnsupportedOperationException
- If the region is a partitioned regionRegionReinitializedException
<SK,SV> Region<SK,SV> getSubregion(String path)
regionName
is the empty string, then this
region itself is returned.path
- the path to the subregionIllegalArgumentException
- if path starts with a forward slash orRegion
,
getFullPath()
<SK,SV> Region<SK,SV> createSubregion(String subregionName, RegionAttributes<SK,SV> aRegionAttributes) throws RegionExistsException, TimeoutException
RegionFactory.createSubregion(Region, String)
or ClientRegionFactory.createSubregion(Region, String)
.RegionAttributes
.
The name must not contain a region name separator.
If the subregion is a distributed replicated
region, it
will be initialized with data from all other caches in this
distributed system that have the same region.
Updates the CacheStatistics.getLastAccessedTime()
and
CacheStatistics.getLastModifiedTime()
for this region.
subregionName
- the subregion nameaRegionAttributes
- the RegionAttributes to be used for the subregionIllegalArgumentException
- if aRegionAttributes is null or if
regionName is null, the empty string, or contains a '/'IllegalStateException
- If the supplied RegionAttributes violate the
region creation constraints
with a region of the same name in another cache in the distributed system
or with this (parent) region.LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALRegionExistsException
- if a subregion by the specified name already existsUnsupportedOperationException
- If the region is a partitioned regionAttributesFactory
,
getFullPath()
Set<Region<?,?>> subregions(boolean recursive)
This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but subregions may be added or removed while a thread is
iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
recursive
- if false, collects direct subregions only; if true,
collects all subregions recursivelyRegion.Entry<K,V> getEntry(Object key)
Region.Entry
for the specified key, or null if it doesn't
exist.key
- the key corresponding to the Entry to returnNullPointerException
- if key is nullV get(Object key) throws CacheLoaderException, TimeoutException
For local scope, a local CacheLoader will be invoked if there is one. For global scope, the order is netSearch, localLoad, netLoad. For any other distributed scope, the order is localLoad, netSearch, netLoad.
netSearch and netLoad are never performed more than once, so if a loader attempts to do a netSearch and one was already done, then another one will not be done.
The value returned by get is not copied, so multi-threaded applications should not modify the value directly, but should use the update methods.
Updates the CacheStatistics.getLastAccessedTime()
,
CacheStatistics.getHitCount()
, CacheStatistics.getMissCount()
,
and CacheStatistics.getLastModifiedTime()
(if a new value is loaded)
for this region and the entry.
If the CacheWriter
throws a
CacheWriterException
when a new value is retrieved
from a loader, the value will not be put into the cache (a new
entry will not be created) but the get will return the value and
not propagate the exception.
get
in interface Map<K,V>
key
- whose associated value is to be returned. The key Object must
implement the equals and hashCode methods. Note that even though key is typed as "Object"
if a CacheLoader is used then make sure you only pass instances of "K" in this parameter.NullPointerException
- if the key is nullIllegalArgumentException
- if the key does not meet
the serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out doing a search
for distributed or getting a distributed lock for Scope.GLOBALCacheLoaderException
- if a cache loader throws an exception, or if
the cache loader returns an object that is not serializable and this
is a distributed regionPartitionedRegionStorageException
- for a partitioned region fails to invoke a CacheLoader
CacheLoader.load(com.gemstone.gemfire.cache.LoaderHelper<K, V>)
,
CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
V get(Object key, Object aCallbackArgument) throws TimeoutException, CacheLoaderException
For local scope, a local CacheLoader will be invoked if there is one. For global scope, the order is netSearch, localLoad, netLoad. For any other distributed scope, the order is localLoad, netSearch, netLoad.
netSearch and netLoad are never performed more than once, so if a loader attempts to do a netSearch and one was already done, then another one will not be done.
The value returned by get is not copied, so multi-threaded applications should not modify the value directly, but should use the update methods.
Updates the CacheStatistics.getLastAccessedTime()
,
CacheStatistics.getHitCount()
, CacheStatistics.getMissCount()
,
and CacheStatistics.getLastModifiedTime()
(if a new value is loaded)
for this region and the entry.
If the CacheWriter
throws a CacheWriterException
when
a new value is retrieved from a loader, then the value will not be put
into the cache (a new entry will not be created) but the get will return
the value and not propagate the exception.
key
- whose associated value is to be returned. The key Object must
implement the equals and hashCode methods. Note that even though key is typed as "Object"
if a CacheLoader is used then make sure you only pass instances of "K" in this parameter.aCallbackArgument
- an argument passed into the CacheLoader if
loader is used. This same argument will also be subsequently passed
to a CacheWriter if the loader returns a non-null value to be placed in
the cache. Modifications to this argument made in the CacheLoader will
be visible to the CacheWriter even if the loader and the writer are
installed in different cache VMs. It will also be passed to any other
callback events triggered by this method.
May be null. Should be serializable.NullPointerException
- if key is nullIllegalArgumentException
- if aCallbackArgument is not serializableLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out doing a search
for distributed or getting a distributed lock for Scope.GLOBALCacheLoaderException
- if a cache loader throws an exception, or if
the cache loader returns an object that is not serializable and this
is a distributed regionPartitionedRegionStorageException
- for a partitioned region fails to invoke a CacheLoader
RegionAttributes
,
CacheLoader.load(com.gemstone.gemfire.cache.LoaderHelper<K, V>)
,
CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
V put(K key, V value) throws TimeoutException, CacheWriterException
Updates the CacheStatistics.getLastAccessedTime()
and
CacheStatistics.getLastModifiedTime()
for this region and the entry.
put
in interface Map<K,V>
key
- a key associated with the value to be put into this region.
The key object must implement the equals and hashCode methods.value
- the value to be put into the cachenull
is returned.
If the entry was "invalid" then null
is returned.
In some cases null
may be returned even
if a previous value exists.
If the region is a client proxy then null
is returned.
If the region is partitioned and the put is done on a non-primary then null
is returned.
If the value is not currently stored in memory but is on disk
and if the region does not have cqs
then null
is returned.NullPointerException
- if key is null or if value
is null (use invalidate instead), or if the key or value do not
meet serializability requirementsClassCastException
- if key does not satisfy the keyConstraintLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.invalidate(Object)
,
CacheLoader.load(com.gemstone.gemfire.cache.LoaderHelper<K, V>)
,
CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
V put(K key, V value, Object aCallbackArgument) throws TimeoutException, CacheWriterException
CacheWriter
invoked in the process.
If there is already an entry associated with the specified key in this region,
the entry's previous value is overwritten.
Updates the CacheStatistics.getLastAccessedTime()
and
CacheStatistics.getLastModifiedTime()
for this region and the entry.
key
- a key associated with the value to be put into this region.
The key object must implement the equals and hashCode methods.value
- the value to be put into the cacheaCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.null
is returned.
If the entry was "invalid" then null
is returned.
In some cases null
may be returned even
if a previous value exists.
If the region is a client proxy then null
is returned.
If the region is partitioned and the put is done on a non-primary then null
is returned.
If the value is not currently stored in memory but is on disk
and if the region does not have cqs
then null
is returned.NullPointerException
- if key is nullIllegalArgumentException
- if key, value, or
aCallbackArgument do not meet serializability requirementsClassCastException
- if key does not satisfy the keyConstraintLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.invalidate(Object)
,
CacheLoader.load(com.gemstone.gemfire.cache.LoaderHelper<K, V>)
,
CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void create(K key, V value) throws TimeoutException, EntryExistsException, CacheWriterException
Updates the CacheStatistics.getLastAccessedTime()
and
CacheStatistics.getLastModifiedTime()
for this region and the entry.
If this region has a distributed scope, this operation
may cause update events in caches that already have
this region with this entry, and it will cause create events in other caches
that have all events
configured.
This operation gets a distributed lock on the entry if the scope is
Scope.GLOBAL
.
key
- the key for which to create the entry in this regionvalue
- the value for the new entry, which may be null meaning
the new entry starts as if it had been locally invalidatedNullPointerException
- if key is nullIllegalArgumentException
- if the key or value
is not serializable and this is a distributed regionClassCastException
- if key does not satisfy the keyConstraintLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
EntryExistsException
- if an entry with this key already existsCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void create(K key, V value, Object aCallbackArgument) throws TimeoutException, EntryExistsException, CacheWriterException
CacheWriter
invoked in the process.
If this region has a distributed scope, then the value may be updated
subsequently if other caches update the value.
Updates the CacheStatistics.getLastAccessedTime()
and
CacheStatistics.getLastModifiedTime()
for this region and the entry.
If this region has a distributed scope, this operation
may cause update events in caches that already have
this region with this entry, and it will cause create events in other caches
that have all events
configured.
key
- the key for which to create the entry in this regionvalue
- the value for the new entry, which may be null meaning
the new entry starts as if it had been locally invalidated.aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.NullPointerException
- if key is nullIllegalArgumentException
- if the key, value, or
aCallbackArgument do not meet serializability requirementsClassCastException
- if key does not satisfy the keyConstraintLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
EntryExistsException
- if an entry with this key already existsCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.CacheListener.afterCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheListener.afterUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeCreate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeUpdate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void invalidate(Object key) throws TimeoutException, EntryNotFoundException
Does not update any CacheStatistics
.
key
- the key of the value to be invalidatedNullPointerException
- if key is nullIllegalArgumentException
- if the key does not
meet serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
EntryNotFoundException
- if the entry does not exist in this regionCacheListener.afterInvalidate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void invalidate(Object key, Object aCallbackArgument) throws TimeoutException, EntryNotFoundException
CacheListener
.
Invalidate only removes the value from the entry, the key is kept intact.
To completely remove the entry, destroy should be used.
Does not update any CacheStatistics
.
key
- the key of the value to be invalidatedaCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.NullPointerException
- if key is nullIllegalArgumentException
- if the key or the
aCallbackArgument do not meet serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBAL
TimeoutException
- if timed out getting distributed lock for Scope.GLOBAL
EntryNotFoundException
- if this entry does not exist in this regionCacheListener.afterInvalidate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void localInvalidate(Object key) throws EntryNotFoundException
Does not update any CacheStatistics
.
key
- the key of the value to be invalidatedNullPointerException
- if key is nullIllegalArgumentException
- if the key
does not meet serializability requirementsIllegalStateException
- if this region is distributed and
replicated
EntryNotFoundException
- if the entry does not exist in this region locallyUnsupportedOperationException
- If the region is a partitioned regionUnsupportedOperationInTransactionException
- If called in a transactional contextCacheListener.afterInvalidate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void localInvalidate(Object key, Object aCallbackArgument) throws EntryNotFoundException
CacheListener
.
Invalidate will only remove the value from the entry, the key will be kept intact.
In order to completely remove the key, entry and value, destroy should
be called.
Does not update any CacheStatistics
.
key
- the key of the value to be invalidatedaCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null.NullPointerException
- if key is nullIllegalStateException
- if this region is distributed and
replicated
EntryNotFoundException
- if this entry does not exist in this region locallyUnsupportedOperationException
- If the region is a partitioned regionUnsupportedOperationInTransactionException
- If called in a transactional contextCacheListener.afterInvalidate(com.gemstone.gemfire.cache.EntryEvent<K, V>)
V destroy(Object key) throws TimeoutException, EntryNotFoundException, CacheWriterException
Scope.LOCAL
.
Does not update any CacheStatistics
.
key
- the key of the entrynull
is returned.
In some cases null
may be returned even
if a previous value exists.
If the region is a client proxy then null
is returned.
If the region is partitioned and the destroy is done on a non-primary then null
is returned.
If the value is not currently stored in memory but is on disk
and if the region does not have cqs
then null
is returned.NullPointerException
- if key is nullIllegalArgumentException
- if key does not meet
serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALEntryNotFoundException
- if the entry does not exist in this regionCacheWriterException
- if a CacheWriter aborts the operationCacheListener.afterDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
V destroy(Object key, Object aCallbackArgument) throws TimeoutException, EntryNotFoundException, CacheWriterException
CacheWriter
invoked in the process.
Destroy removes
not only the value but also the key and entry from this region.
Destroy will be distributed to other caches if the scope is not
Scope.LOCAL
.
Does not update any CacheStatistics
.
key
- the key of the entry to destroyaCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.null
is returned.
In some cases null
may be returned even
if a previous value exists.
If the region is a client proxy then null
is returned.
If the region is partitioned and the destroy is done on a non-primary then null
is returned.
If the value is not currently stored in memory but is on disk
and if the region does not have cqs
then null
is returned.NullPointerException
- if key is nullIllegalArgumentException
- if the key or aCallbackArgument
do not meet serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALEntryNotFoundException
- if the entry does not exist in this regionCacheWriterException
- if a CacheWriter aborts the operationCacheListener.afterDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void localDestroy(Object key) throws EntryNotFoundException
CacheWriter
is
invoked. Destroy removes not only the value but also the key and entry
from this region.
Does not update any CacheStatistics
.
key
- the key of the entry to destroyNullPointerException
- if key is nullIllegalStateException
- if this region is distributed and
replicated
EntryNotFoundException
- if the entry does not exist in this region locallyUnsupportedOperationException
- If the region is a partitioned regionUnsupportedOperationInTransactionException
- If called in a transactional contextCacheListener.afterDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
void localDestroy(Object key, Object aCallbackArgument) throws EntryNotFoundException
CacheListener
, if any. No CacheWriter
is
invoked. Destroy removes
not only the value but also the key and entry from this region.
Does not update any CacheStatistics
.
key
- the key of the entry to destroyaCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. Can be null.NullPointerException
- if key is nullIllegalStateException
- if this region is distributed and
replicated
EntryNotFoundException
- if the entry does not exist in this region locallyUnsupportedOperationException
- If the region is a partitioned regionUnsupportedOperationInTransactionException
- If called in a transactional contextCacheListener.afterDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
@Deprecated Set<K> keys()
keySet
instead;This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but keys may be added or removed to this set while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock.
Set<K> keySet()
This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but keys may be added or removed to this set while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock.
Collection<V> values()
This Collection
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this collection. No ConcurrentModificationException
s
will be thrown, but values may be added or removed to this collection while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the collection is required, then call
one of the toArray methods on the collection and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock on the
region.
Null values are not included in the result collection.
@Deprecated Set<Region.Entry<?,?>> entries(boolean recursive)
entrySet(boolean recursive)
instead.Set
of Region.Entry
objects in this region.
If the recursive parameter is set to true, this call will
recursively collect all the entries
in this region and its subregions and return them in the Set; if false,
it only returns entries directly contained in this region.
This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but entries may be added or removed to this set while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock.
recursive
- if true, this call recursively collects all the
entries in this region and its subregions; if false, it only returns
the entries directly contained in this regionRegion.Entry
Set<Region.Entry<?,?>> entrySet(boolean recursive)
Set
of Region.Entry
objects in this region.
If the recursive parameter is set to true, this call will
recursively collect all the entries
in this region and its subregions and return them in the Set; if false,
it only returns entries directly contained in this region.
This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but entries may be added or removed to this set while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock.
recursive
- if true, this call recursively collects all the
entries in this region and its subregions; if false, it only returns
the entries directly contained in this regionRegion.Entry
Cache getCache()
getRegionService()
instead.Cache
associated with this region.
Does not throw a CacheClosedException
if the Cache is closed.
RegionService getRegionService()
cache
associated with this region.
Does not throw a CacheClosedException
if the cache is closed.
Object getUserAttribute()
void setUserAttribute(Object value)
value
- the application-defined objectboolean isDestroyed()
Does not throw a RegionDestroyedException
if this region
has been destroyed.
boolean containsValueForKey(Object key)
Entry e = getEntry(key); return e != null && e.getValue() != null;
key
- the key to check for a valid valueboolean containsKey(Object key)
getEntry(key) != null
.containsKey
in interface Map<K,V>
key
- the key to check for an existing entryLock getRegionDistributedLock() throws IllegalStateException
Scope.GLOBAL
regions, gets a distributed
lock on this whole region. This region lock
cannot be acquired until all other caches release both region locks and any
entry locks they hold in this region. Likewise, new entry locks cannot be
acquired until outstanding region locks are released.
The only place that a region distributed lock is acquired automatically
is during region creation for distributed replicated
regions when they acquire their initial data.
The operations invalidateRegion and destroyRegion do not automatically acquire a distributed lock at all, so it is possible for these operations to cause an entry to be invalidated or the region to be destroyed even if a distributed lock is held on an entry. If an application requires all entry level locks to be released when a region is destroyed or invalidated as a whole, then it can call this method explicitly to get a ock on the entire region before calling invalidateRegion or destroyRegion.
See
getDistributedLock(java.lang.Object)
for the list of operations that automatically
acquire distributed entry locks for regions with global scope.
Note that Region locks are potentially very expensive to acquire.
Lock
used for acquiring a distributed lock on the entire regionIllegalStateException
- if the scope of this region is not globalUnsupportedOperationException
- If the region is a partitioned regionLock getDistributedLock(Object key) throws IllegalStateException
Scope.GLOBAL
regions, gets a distributed
lock on the entry with the specified key.
Use of this Lock
enables an application to synchronize
operations on entries at a higher level than provided for by
Scope.GLOBAL
. This is the same lock that GemFire uses internally
for operations that modify the cache with global scope, so this lock can
be used for high-level synchronization with other caches that have
this region with global scope. For example, if an application needs to
get two values out of a region with global scope and guarantee that the
first value is not modified before the second value is retrieved,
it can use this lock in the following manner:
Lock entry1Lock = myRegion.getDistributedLock(key1); Lock entry2Lock = myRegion.getDistributedLock(key2); entry1Lock.lock(); entry2Lock.lock(); try { Object val1 = myRegion.get(key1); Object val2 = myRegion.get(key2); // do something with val1 and val2 } finally { entry2Lock.unlock(); entry1Lock.unlock(); }You can also get a lock on an entry that does not exist in the local cache. Doing so guarantees that no other cache with the same region using global scope or using the same lock will create or update that entry while you have the lock. When a region has global scope, the following operations automatically acquire a distributed lock on an entry:
create
,
put
, destroy
, invalidate
,
and get
that causes a loader to be invoked.Lock
used for acquiring a distributed lock on an
entryIllegalStateException
- if the scope of this region is not globalNullPointerException
- if key is nullUnsupportedOperationException
- If the region is a partitioned region@Deprecated void writeToDisk()
DiskStore.flush()
instead.IllegalStateException
- If this region is not configured to write to diskDiskAccessException
- If problems are encounter while writing to diskUnsupportedOperationException
- If the region is a partitioned regionAttributesFactory.setPersistBackup(boolean)
boolean existsValue(String queryPredicate) throws FunctionDomainException, TypeMismatchException, NameResolutionException, QueryInvocationTargetException
Region
that matches the given queryPredicate
. Filters the
values of this region using the predicate given as a string with
the syntax of the WHERE
clause of the query
language. The predefined variable this
may be used
inside the predicate to denote the current value being filtered.queryPredicate
- A query language boolean query predicate.true
if there is a value in region that
matches the predicate, otherwise false
.QueryInvalidException
- If predicate does not correspond to valid query language
syntax.FunctionDomainException
TypeMismatchException
NameResolutionException
QueryInvocationTargetException
QueryService
<E> SelectResults<E> query(String queryPredicate) throws FunctionDomainException, TypeMismatchException, NameResolutionException, QueryInvocationTargetException
queryPredicate
.
The queryPredicate should follow the syntax of query WHERE clause.
When executed from a client, this method always runs on the server.
However application should use QueryService to execute queries.
When executed from a client, this method always runs on the server.
However application should use QueryService to execute queries.queryPredicate
- A query language boolean query predicate.SelectResults
containing the values of this
Region
that match the
predicate
.QueryInvalidException
- If exception occurs during query compilation or processing.FunctionDomainException
TypeMismatchException
NameResolutionException
QueryInvocationTargetException
Pool.getQueryService()
,
RegionService.getQueryService()
,
QueryService
Object selectValue(String queryPredicate) throws FunctionDomainException, TypeMismatchException, NameResolutionException, QueryInvocationTargetException
Region
that matches
the given query predicate
.
Filters the values of this region using the predicate given as a string
with the syntax of the where clause of the query language.
The predefined variable this
may be used inside the predicate
to denote the element currently being filtered.queryPredicate
- A query language boolean query predicate.Region
matches the predicate, null
is returned.QueryInvalidException
- If predicate does not correspond to valid query language
syntax.FunctionDomainException
- If more than one element evaluates to true.TypeMismatchException
NameResolutionException
QueryInvocationTargetException
QueryService
@Deprecated void forceRolling()
DiskStore.forceRoll()
instead.DiskAccessException
saying that the disk is full will be
thrown. If compaction is true, the application will wait for the other oplogs to be compressed and more
space to be created.DiskAccessException
void becomeLockGrantor()
Calls to this method will block until grantor authority has been transferred to this member.
If another member later calls becomeLockGrantor
, that
member will transfer grantor authority from this member to itself.
Multiple calls to this operation will have no effect unless another
member has transferred grantor authority, in which case, this member will
transfer grantor authority back to itself.
This region's scope must be Scope.GLOBAL
to become a lock
grantor.
This operation should not be invoked repeatedly in an application. It is possible to create a lock service and have two or more members endlessly calling becomeLockGrantor to transfer grantorship back and forth.
IllegalStateException
- if scope is not GLOBALUnsupportedOperationException
- If the region is a partitioned regionvoid localClear()
UnsupportedOperationException
- If the region is a replicated regionUnsupportedOperationException
- If the region is a partitioned regionCacheListener.afterRegionClear(com.gemstone.gemfire.cache.RegionEvent<K, V>)
void clear()
Scope.LOCAL
.
clear
in interface Map<K,V>
UnsupportedOperationException
- If the region is a partitioned regionMap.clear()
,
CacheListener.afterRegionClear(com.gemstone.gemfire.cache.RegionEvent<K, V>)
,
CacheWriter.beforeRegionClear(com.gemstone.gemfire.cache.RegionEvent<K, V>)
boolean containsValue(Object value)
containsValue
in interface Map<K,V>
Map.containsValue(Object)
Set<Map.Entry<K,V>> entrySet()
Set
of Region.Entry
objects in this region.
This Set
is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationException
s
will be thrown, but entries may be added or removed to this set while a thread
is iterating. Iterators are intended to be used by one thread at a time.
If a stable "snapshot" view of the set is required, then call
one of the toArray methods on the set and iterate over the array.
If you need to lock down the region so this set is not modified while
it is being accessed, use global scope with a distributed lock.
A remove called on an entry via the iterator will result in an UnsupportedOperationException
The Region.Entry obtained via the iterator is backed by the region. If a setValue on
that entry is called, it will be similar in effect as calling a put on that key.
entrySet
in interface Map<K,V>
Map.entrySet()
boolean isEmpty()
isEmpty
in interface Map<K,V>
Map.isEmpty()
void putAll(Map<? extends K,? extends V> map)
put(Object, Object)
on
this region once for each entry in the specified map.
This operation will be distributed to other caches if the scope
is not Scope.LOCAL
.putAll
in interface Map<K,V>
map
- the key/value pairs to put in this region.LowMemoryException
- if a low memory condition is detected.Map.putAll(Map map)
void putAll(Map<? extends K,? extends V> map, Object aCallbackArgument)
put(Object, Object, Object)
on
this region once for each entry in the specified map.
This operation will be distributed to other caches if the scope
is not Scope.LOCAL
.map
- the key/value pairs to put in this region.aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. May be null. Must be serializable if this operation is distributed.LowMemoryException
- if a low memory condition is detected.Map.putAll(Map map)
void removeAll(Collection<? extends K> keys)
destroy(Object)
on
this region once for each key in the specified collection.
If an entry does not exist that key is skipped; EntryNotFoundException is not thrown.
This operation will be distributed to other caches if the scope
is not Scope.LOCAL
.keys
- the keys to remove from this region.destroy(Object)
void removeAll(Collection<? extends K> keys, Object aCallbackArgument)
destroy(Object, Object)
on
this region once for each key in the specified collection.
If an entry does not exist that key is skipped; EntryNotFoundException is not thrown.
This operation will be distributed to other caches if the scope
is not Scope.LOCAL
.keys
- the keys to remove from this region.aCallbackArgument
- a user-defined parameter to pass to callback events
triggered by this method. May be null. Must be serializable if this operation is distributed.destroy(Object, Object)
Map<K,V> getAll(Collection<?> keys)
null
.
Note that the keys collection should extend K since a load may be done and the key in that case will be stored in the region. The keys parameter was not changed to extend K for backwards compatibility.
keys
- A Collection of keys<T extends K> Map<T,V> getAll(Collection<T> keys, Object aCallbackArgument)
null
.T
- the type of the keys passed to getAllkeys
- A Collection of keysaCallbackArgument
- an argument passed into the CacheLoader if
a loader is used. This same argument will also be subsequently passed
to a CacheWriter if the loader returns a non-null value to be placed in
the cache. Modifications to this argument made in the CacheLoader will
be visible to the CacheWriter even if the loader and the writer are
installed in different cache VMs. It will also be passed to any other
callback events triggered by this method.
May be null. Must be serializable if this operation is distributed.V remove(Object key)
Scope.LOCAL
.
Does not update any CacheStatistics
.
remove
in interface Map<K,V>
key
- the key of the entrynull
is returned if an entry for key does not exist
otherwise the value that was stored locally for the removed entry is returned.
If the entry was "invalid" then null
is returned.
In some cases null
may be returned even
if a previous value exists.
If the region is a client proxy then null
is returned.
If the region is partitioned and the remove is done on a non-primary then null
is returned.
If the value is not currently stored in memory but is on disk
and if the region does not have cqs
then null
is returned.NullPointerException
- if key is nullIllegalArgumentException
- if key does not meet
serializability requirementsLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationdestroy(Object)
,
CacheListener.afterDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
CacheWriter.beforeDestroy(com.gemstone.gemfire.cache.EntryEvent<K, V>)
,
Map.remove(Object)
int size()
DataPolicy.PARTITION
, this is a distributed operation that
returns the number of entries present in entire region.
For all other types of regions, it returns the number of entries present
locally, and it is not a distributed operation.size
in interface Map<K,V>
Map.size()
boolean equals(Object other)
Object.equals(java.lang.Object)
is used.
Note that some other class that implements Map
may say that
it is equal to an instance of Region (since Region implements Map)
even though Region will never say that it is equal to that instance.int hashCode()
Object.hashCode()
.void registerInterest(K key)
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
This method uses the default InterestResultPolicy
.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys any type are
pushed to the client and inserted into the local cache.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterest(K key, InterestResultPolicy policy)
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys of any type are
pushed to the client and inserted into the local cache.
policy
- The interest result policy. This can be one of:
UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subcriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterestRegex(String regex)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
Note that if the regex
is ".*"
then all keys of any type will be pushed to the client.
This method uses the default InterestResultPolicy
.
The regular expression string is compiled using the Pattern
class.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
regex
- The regular expression on which to register interest.UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
void registerInterestRegex(String regex, InterestResultPolicy policy)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
The regular expression string is compiled using the Pattern
class.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
regex
- The regular expression on which to register interest.policy
- The interest result policy. This can be one of:
UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
void unregisterInterest(K key)
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be unregistered.UnsupportedOperationException
- if the region is not configured with a pool name.void unregisterInterestRegex(String regex)
regex
- The regular expression on which to unregister interest.UnsupportedOperationException
- if the region is not configured with a pool name.List<K> getInterestList()
UnsupportedOperationException
- if the region is not configured with a pool name.void registerInterest(K key, boolean isDurable)
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
This method uses the default InterestResultPolicy
.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys any type are
pushed to the client and inserted into the local cache.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
isDurable
- true if the register interest is durableUnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterest(K key, boolean isDurable, boolean receiveValues)
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
This method uses the default InterestResultPolicy
.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys any type are
pushed to the client and inserted into the local cache.
isDurable
- true if the register interest is durablereceiveValues
- defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterest(K key, InterestResultPolicy policy, boolean isDurable, boolean receiveValues)
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys of any type are
pushed to the client and inserted into the local cache.
policy
- The interest result policy. This can be one of:
isDurable
- true if the register interest is durablereceiveValues
- defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterest(K key, InterestResultPolicy policy, boolean isDurable)
key
- The key on which to register interest. If the key is a
List
, then all the keys in the List
will
be registered. The key can also be the special token 'ALL_KEYS', which
will register interest in all keys in the region. In effect, this will
cause an update to any key in this region in the CacheServer to be pushed
to the client.
Using 'ALL_KEYS' is the same as calling registerInterestRegex(String)
with ".*" as the argument. This means that all keys of any type are
pushed to the client and inserted into the local cache.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
policy
- The interest result policy. This can be one of:
isDurable
- true if the register interest is durableUnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
void registerInterestRegex(String regex, boolean isDurable)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
Note that if the regex
is ".*"
then all keys of any type will be pushed to the client.
This method uses the default InterestResultPolicy
.
The regular expression string is compiled using the Pattern
class.
regex
- The regular expression on which to register interest.isDurable
- true if the register interest is durableUnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
void registerInterestRegex(String regex, boolean isDurable, boolean receiveValues)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
Note that if the regex
is ".*"
then all keys of any type will be pushed to the client.
This method uses the default InterestResultPolicy
.
The regular expression string is compiled using the Pattern
class.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
regex
- The regular expression on which to register interest.isDurable
- true if the register interest is durablereceiveValues
- defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
void registerInterestRegex(String regex, InterestResultPolicy policy, boolean isDurable)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
The regular expression string is compiled using the Pattern
class.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
regex
- The regular expression on which to register interest.policy
- The interest result policy. This can be one of:
isDurable
- true if the register interest is durableUnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
void registerInterestRegex(String regex, InterestResultPolicy policy, boolean isDurable, boolean receiveValues)
String
satisfying this regular expression by other clients will be pushed to
this client by the CacheServer. This method is currently supported only
on clients in a client server topology. These keys are first
locally cleared from the client and the current values for keys of type String
that satisfy the regular expression are inserted into the local cache before this call returns.
The regular expression string is compiled using the Pattern
class.
If you locally-destroy a key and your region has concurrency-checks-enabled turned off you will not receive invalidation events from your interest subscription for that key. When concurrency-checks-enabled is turned on GemFire will accept invalidation and deliver these events to your client cache.
regex
- The regular expression on which to register interest.policy
- The interest result policy. This can be one of:
isDurable
- true if the register interest is durablereceiveValues
- defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.UnsupportedOperationException
- if the region is not configured with a pool name.SubscriptionNotEnabledException
- if the region's pool does not have subscriptions enabled.UnsupportedOperationException
- if the region is a replicate with distributed scope.InterestResultPolicy
,
Pattern
List<String> getInterestListRegex()
UnsupportedOperationException
- if the region is not configured with a pool name.Set<K> keySetOnServer()
UnsupportedOperationException
- if the region is not configured with a pool name.boolean containsKeyOnServer(Object key)
key
- the key to check for an existing entryUnsupportedOperationException
- if the region is not configured with a pool name.V putIfAbsent(K key, V value)
if (!map.containsKey(key)) return map.put(key, value); else return map.get(key);except that the action is performed atomically.
ConcurrentMap operations are supported on partitioned and replicated regions and in client caches. They are also supported on non-empty local regions.
Please read the notes on ConcurrentMap operations in the javadoc for Region.
Region allows the value parameter to be null, which will create an invalid entry.
putIfAbsent
in interface ConcurrentMap<K,V>
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified keyUnsupportedOperationException
- if the put operation
is not supported by this mapClassCastException
- if the class of the specified key or value
prevents it from being stored in this mapNullPointerException
- if the specified key or value is null,
and this map does not permit null keys or valuesIllegalArgumentException
- if some property of the specified key
or value prevents it from being stored in this mapLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.boolean remove(Object key, Object value)
if (map.containsKey(key) && map.get(key).equals(value)) { map.remove(key); return true; } else return false;except that the action is performed atomically.
ConcurrentMap operations are supported on partitioned and replicated regions and in client caches. They are also supported on non-empty local regions.
Please read the notes on ConcurrentMap operations in the javadoc for Region.
Region allows the value parameter to be null, which will match an invalid entry.
remove
in interface ConcurrentMap<K,V>
key
- key with which the specified value is associatedvalue
- value expected to be associated with the specified keyUnsupportedOperationException
- if the remove operation
is not supported by this mapClassCastException
- if the key or value is of an inappropriate
type for this map (optional)NullPointerException
- if the specified key or value is null,
and this map does not permit null keys or values (optional)LeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.boolean replace(K key, V oldValue, V newValue)
if (map.containsKey(key) && map.get(key).equals(oldValue)) { map.put(key, newValue); return true; } else return false;except that the action is performed atomically.
ConcurrentMap operations are supported on partitioned and replicated regions and in client caches. They are also supported on non-empty local regions.
Please read the notes on ConcurrentMap operations in the javadoc for Region.
Region allows the oldValue parameter to be null, which will match an invalid entry.
replace
in interface ConcurrentMap<K,V>
key
- key with which the specified value is associatedoldValue
- value expected to be associated with the specified keynewValue
- value to be associated with the specified keyUnsupportedOperationException
- if the replace operation
is not supported by this mapClassCastException
- if the class of a specified key or value
prevents it from being stored in this mapNullPointerException
- if a specified key is null,
and this map does not permit null keysIllegalArgumentException
- if some property of a specified key
or value prevents it from being stored in this mapLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.V replace(K key, V value)
if (map.containsKey(key)) { return map.put(key, value); } else return null;except that the action is performed atomically.
ConcurrentMap operations are supported on partitioned and replicated regions and in client caches. They are also supported on non-empty local regions.
Please read the notes on ConcurrentMap operations in the javadoc for Region.
replace
in interface ConcurrentMap<K,V>
key
- key with which the specified value is associatedvalue
- value to be associated with the specified keyUnsupportedOperationException
- if the put operation
is not supported by this mapClassCastException
- if the class of the specified key or value
prevents it from being stored in this mapNullPointerException
- if the specified key or value is null,
and this map does not permit null keys or valuesIllegalArgumentException
- if some property of the specified key
or value prevents it from being stored in this mapLeaseExpiredException
- if lease expired on distributed lock for Scope.GLOBALTimeoutException
- if timed out getting distributed lock for Scope.GLOBALCacheWriterException
- if a CacheWriter aborts the operationPartitionedRegionStorageException
- if the operation could not be completed on a partitioned region.LowMemoryException
- if a low memory condition is detected.Copyright © 1997-2017 Pivotal Software, Inc. All rights reserved.