com.gemstone.gemfire.cache
Interface Region<K,V>

Manages subregions and cached data. Each region
can contain multiple subregions and entries for data.
Regions provide a hierarchical name space
within the cache. Also, a region can be used to group cached
objects for management purposes.

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 (/).
Regions 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:

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.

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 as Early Access functionality. 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.

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.

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.

getAttributes

Returns the 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.

invalidateRegion

Invalidates this region. Invalidation cascades to
all entries and subregions. After
the 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.

invalidateRegion

Invalidates this region. 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. The region invalidate will be distributed
to other caches if the scope is not Scope.LOCAL.

Does not update any CacheStatistics.

Parameters:

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.

localInvalidateRegion

void localInvalidateRegion()

Invalidates this region in the local cache only. Invalidation
cascades to all entries and subregions. After
the 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.

localInvalidateRegion

Invalidates this region in the local cache only,
and provides a user-defined argument to the 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.

Parameters:

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null.

destroyRegion

Destroys the whole region.
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.
The region destroy will be distributed to other caches if the scope is
not Scope.LOCAL.

Does not update any CacheStatistics.

Throws:

CacheWriterException - if a CacheWriter aborts the operation; if this
occurs some subregions may have already been successfully destroyed.

destroyRegion

Destroys the whole region and provides a user-defined parameter
object to any 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.

Parameters:

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.

Throws:

CacheWriterException - if a CacheWriter aborts the operation; if this
occurs some subregions may have already been successfully destroyed.

localDestroyRegion

void localDestroyRegion()

Destroys the whole region in the local cache only. No 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.

localDestroyRegion

Destroys the whole region in the local cache only, and provides a
user-defined argument to a 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.

Parameters:

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this call. Can be null.

saveSnapshot

Saves the data in this region in a snapshot file. The data is a
"concurrent" snapshot in that modifications to the region
while the snapshot is being written are not guaranteed to be included
or excluded from the snapshot. In other words, if there are concurrent
modifications to the region while the snapshot is being written, the
snapshot may not reflect a consistent state of the entire region at any
moment in time.

loadSnapshot

Loads data from a file that was previously created with the saveSnapshot
method. This method essentially destroys the region and automatically
recreates it with the data in the snapshot. Any current data in the region
is lost, replaced with the data in the snapshot file.
Causes this region and all other regions with the same
name in remote caches in this distributed system to be reinitialized:
remote regions are cleared of all data and distributed 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.

getSubregion

Returns a subregion with the specified name or null if doesn't exist. The
name is relative from this region, so it can be either a simple region name
or a relative region path. If regionName is the empty string, then this
region itself is returned.

Parameters:

path - the path to the subregion

Returns:

a subregion with the specified relative path from this region,
or null if it doesn't exist

createSubregion

Creates a subregion with the specified name and 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.

subregions

Returns a Set of all subregions. If the recursive parameter is
set to true, this call will recursively collect all subregions
contained in this region. Otherwise, this call will only
return the Set of direct subregions.

This Set is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationExceptions
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.

get

Returns the value associated with the specified key. If the value
is not present locally for this entry, a netSearch and/or a CacheLoader
may be invoked to get the value, depending on the scope of this region.
A netSearch looks for a value in every node of the system that defines
this region. A netLoad invokes remote loaders one at a time until one
returns a value or throws an exception.
If any of these methods successfully retrieves a value than the value
is immediately returned.

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.

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

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. If the value
is not present locally for this entry, a netSearch and/or a CacheLoader
may be invoked to get the value, depending on the scope of this region.
A netSearch looks for a value in every node of the system that defines
this region. A netLoad invokes remote loaders one at a time until one
returns a value or throws an exception.
If any of these methods successfully retrieves a value than the value
is immediately returned.

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.

key - whose associated value is to be returned. The key Object must
implement the equals and hashCode methods.

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.
Can be null. Should be serializable.

Returns:

the value with specified key, or null if the value
is not found and can't be loaded

put

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.
If there is already an entry associated with the specified key in this region,
the entry's previous value is overwritten.

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.

Parameters:

key - the key for which to create the entry in this region

value - the value for the new entry, which may be null meaning
the new entry starts as if it had been locally invalidated

create

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.
If this region has a distributed scope, then the value may be updated
subsequently if other caches update the value.

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.

Parameters:

key - the key for which to create the entry in this region

value - 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.

invalidate

Invalidates the entry with the specified key. Invalidate
only removes the value from the entry, the key is kept intact.
To completely remove the entry, destroy should be used.
The invalidate will be distributed to other caches if
the scope is not Scope.LOCAL.

invalidate

Invalidates the entry with the specified key,
and provides a user-defined argument to the 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.

Parameters:

key - the key of the value to be invalidated

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.

localInvalidate

Invalidates the value with the specified key in the local cache only.
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.

localInvalidate

Invalidates the value with the specified key in the local cache only,
and provides a user-defined argument to the 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.

Parameters:

key - the key of the value to be invalidated

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null.

destroy

Destroys the entry with the specified key, and provides a user-defined
parameter object to any 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.

Parameters:

key - the key of the entry to destroy

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null. Should be serializable.

Returns:

the value associated with key.
In some cases null may be returned even
if a previous value exists.

localDestroy

Destroys the value with the specified key in the local cache
only, and provides a user-defined
parameter object to the 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.

Parameters:

key - the key of the entry to destroy

aCallbackArgument - a user-defined parameter to pass to callback events
triggered by this method. Can be null.

keys

This Set is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationExceptions
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.

Returns:

a Set of all the keys

keySet

This Set is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationExceptions
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.

values

This Collection is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this collection. No ConcurrentModificationExceptions
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.

entries

Returns the 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 ConcurrentModificationExceptions
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.

Parameters:

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 region

entrySet

Returns the 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 ConcurrentModificationExceptions
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.

Parameters:

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 region

getRegionDistributedLock

For 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.

getDistributedLock

For 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:

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.

existsValue

Determines whether there is a value in this 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.

Parameters:

queryPredicate - A query language boolean query predicate.

Returns:

true if there is a value in region that
matches the predicate, otherwise false.

query

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 element being filtered.
This method evaluates the passed in where clause and returns results.
It is supported on servers as well as clients. When executed on a
client, this method always runs on the server and returns results.
When invoking this method from the client, applications can pass in a
where clause or a complete query.
However to execute complete queries on regions from the client, application
should use Pool.getQueryService().newQuery(String query).execute()
Support for executing complete queries from the client using Region.query
is likely to be deprecated in future versions.

Parameters:

queryPredicate - A query language boolean query predicate.

Returns:

A SelectResults containing the values of this
Region that match the
predicate.

selectValue

Selects the single value in this 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.

Parameters:

queryPredicate - A query language boolean query predicate.

Returns:

The single element that evaluates to true for the
predicate. If no value in this Region
matches the predicate, null is returned.

forceRolling

Asks the region to start writing to a new oplog (if persistence/overflow
is turned on). The old one will be asynchronously compressed if compaction is set to true. If the region
is not persistent/overflow no change in the region will be reflected. The new log will
be created in the next available directory with free space. If there is no directory with free space
available and compaction is set to false, then a 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.

becomeLockGrantor

void becomeLockGrantor()

Specifies this member to become the grantor for this region's lock
service. The grantor will be the lock authority which is responsible
for handling all lock requests for this service. Other members will
request locks from this member. Locking for this member will be optimal
as it will not require messaging to acquire a given lock.

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.

containsValue

Returns true if this region maps one or more keys to the specified value.
More formally, returns true if and only if this region contains at least one
entry to a value v such that (value==null ? v==null : value.equals(v)).
This operation is not distributed and only the current region will be
checked for this value.

entrySet

This Set is unmodifiable. It is
backed by this region. Synchronization is not necessary to access or
iterate over this set. No ConcurrentModificationExceptions
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.

putAll

Copies all of the entries from the specified map to this region.
The effect of this call is equivalent to that of calling put(Object, Object) on
this region once for each entry in the specified map.
putAll will be distributed to other caches if the scope
is not Scope.LOCAL.

remove

Removes the entry with the specified key. The operation removes
not only the value but also the key and entry from this region.
Remove will be distributed to other caches if the scope
is not Scope.LOCAL.

size

int size()

Returns the number of entries present in this region.
For 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.

equals

Compares the specified object with this region for equality.
Regions are only equal to themselves (identity based) so 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.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and current value for this
key is inserted into the local cache before this call returns.

Parameters:

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.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and current value for this
key is inserted into the local cache before this call returns. (if
requested).

Parameters:

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:

InterestResultPolicy.NONE - does not initialize the local cache

InterestResultPolicy.KEYS - initializes the local cache with the
keys satisfying the request

InterestResultPolicy.KEYS_VALUES - initializes the local cache with
the keys and current values satisfying the request

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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.

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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.

unregisterInterest

Sends a request to the CacheServer to unregister interest in a key for
this client. Updates to this key by other clients will be no longer be
pushed to this client by the CacheServer. This method is currently
supported only on clients in a client server topology.

Parameters:

key - The key on which to register interest. If the key is a
List, then all the keys in the List will
be unregistered.

unregisterInterestRegex

Sends a request to the CacheServer to unregister interest in a regular
expression pattern for this client. Updates to any keys satisfying this
regular expression by other clients will no longer be pushed to this client
by the CacheServer. This method is currently supported only on clients in a
client server topology.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and the current value for this
key is inserted into the local cache before this call returns.

Parameters:

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.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and the current value for this
key is inserted into the local cache before this call returns.

Parameters:

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 durable

receiveValues - defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and the current value for this
key is inserted into the local cache before this call returns (if
requested).

Parameters:

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:

InterestResultPolicy.NONE - does not initialize the local cache

InterestResultPolicy.KEYS - initializes the local cache with the
keys satisfying the request

InterestResultPolicy.KEYS_VALUES - initializes the local cache with
the keys and current values satisfying the request

isDurable - true if the register interest is durable

receiveValues - defaults to true. set to false to receive create or update events
as invalidates similar to notify-by-subscription false.

registerInterest

Sends a request to the CacheServer to register interest in a key for
this client. Updates to this key 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. This key is first
locally cleared from the client and the current value for this
key is inserted into the local cache before this call returns (if
requested).

Parameters:

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:

InterestResultPolicy.NONE - does not initialize the local cache

InterestResultPolicy.KEYS - initializes the local cache with the
keys satisfying the request

InterestResultPolicy.KEYS_VALUES - initializes the local cache with
the keys and current values satisfying the request

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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.

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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.

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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.

registerInterestRegex

Sends a request to the CacheServer to register interest in a regular
expression pattern for this client. Updates to any keys of type 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 previous value associated with the specified key, or
null if there was no mapping for the key.
(A null return can also indicate that the map
previously associated null with the key,
if the implementation supports null values.)

the previous value associated with the specified key, or
null if there was no mapping for the key.
(A null return can also indicate that the map
previously associated null with the key,
if the implementation supports null values.)