You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by rv...@apache.org on 2015/04/28 23:40:26 UTC
[21/51] [partial] incubator-geode git commit: Init
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Region.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Region.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Region.java
new file mode 100644
index 0000000..9c02030
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Region.java
@@ -0,0 +1,2385 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *========================================================================
+ */
+
+package com.gemstone.gemfire.cache;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.locks.Lock;
+
+import com.gemstone.gemfire.cache.client.ClientRegionFactory;
+import com.gemstone.gemfire.cache.client.Pool;
+import com.gemstone.gemfire.cache.client.SubscriptionNotEnabledException;
+import com.gemstone.gemfire.cache.query.FunctionDomainException;
+import com.gemstone.gemfire.cache.query.NameResolutionException;
+import com.gemstone.gemfire.cache.query.QueryInvalidException;
+import com.gemstone.gemfire.cache.query.QueryInvocationTargetException;
+import com.gemstone.gemfire.cache.query.QueryService;
+import com.gemstone.gemfire.cache.query.SelectResults;
+import com.gemstone.gemfire.cache.query.TypeMismatchException;
+import com.gemstone.gemfire.cache.snapshot.RegionSnapshotService;
+
+/** 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.
+ * <p>
+ *
+ * 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, {@link com.gemstone.gemfire.cache.Region.Entry}.
+ * <p>
+ *
+ * Each {@link com.gemstone.gemfire.cache.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.
+ * <p>
+ *
+ * A region's name can be any String except that it should not contain
+ * the region name separator, a forward slash (/).
+ *
+ * <code>Region</code>s can be referenced by a relative path name from any region
+ * higher in the hierarchy in {@link #getSubregion}. You can get the relative
+ * path from the root region with {@link #getFullPath}. The name separator
+ * is used to concatenate all the region names together from the root, starting
+ * with the root's subregions.
+ * <p>
+ * 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 <i>3rd_level_region</i> has parent region <i>2nd_level_region</i>; region
+ * <i>2nd_level_region</i> in turn has parent region <i>1st_level_region</i>; and region
+ * <i>1st_level_region</i> is a child of the root region. Then,the user can get the region
+ * <i>3rd_level_region</i> from the root region by issuing:
+ * <pre>
+ * <code>
+ * region3 = root.getSubregion("1st_level_region/2nd_level_region/3rd_level_region");
+ * </code>
+ * </pre>
+ * or the user can get the region <i>3rd_level_region</i> from region <i>1st_level_region</i>
+ * by issuing
+ * <pre>
+ * <code>
+ * region3 = region1.getSubregion("2nd_level_region/3rd_level_region");
+ * </code>
+ * </pre>
+ * <p>
+ * 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.
+ * <p>
+ * Regions and their entries can be locked. The <code>Lock</code>
+ * obtained from {@link #getRegionDistributedLock} is a distributed lock on the
+ * entire Region, and the <code>Lock</code> obtained from
+ * {@link Region#getDistributedLock} is a distributed lock on the individual
+ * entry.
+ *
+ * <p>If the scope is <code>Scope.GLOBAL</code>, the methods
+ * that modify, destroy, or invalidate the entries in this region will also get a
+ * distributed lock. See the documentations for {@link #getDistributedLock} and
+ * {@link #getRegionDistributedLock} for details on the implicit locking that
+ * occurs for regions with <code>Scope.GLOBAL</code>.
+ *<p>
+ * Unless otherwise specified, all of these methods throw a
+ * <code>CacheClosedException</code> if the Cache is closed at the time of
+ * invocation, or a <code>RegionDestroyedException</code> 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ *<p>
+ * 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.
+ *<p>
+ * @see RegionAttributes
+ * @see AttributesFactory
+ * @see AttributesMutator
+ * @see Region.Entry
+ * @since 2.0
+ */
+
+public interface Region<K,V> extends ConcurrentMap<K, V> {
+ /** The region name separator character. */
+ public static final char SEPARATOR_CHAR = '/';
+
+ /** The region name separator character, represented as a string for convenience. */
+ public static final String SEPARATOR = "/";
+
+ /** Returns the name of this region. A region's name
+ * can be any non-empty String providing it does not
+ * contain the name separator, a forward slash (/).
+ * If this is the root region, returns "root".
+ * <p>
+ * Does not throw a <code>CacheClosedException</code> or a
+ * <code>RegionDestroyedException</code>.
+ *
+ * @return the name of this region
+ */
+ public String getName();
+
+ /**
+ * 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.
+ * The path separator is a forward slash.
+ * <p>
+ * Does not throw a <code>CacheClosedException</code> or a
+ * <code>RegionDestroyedException</code>.
+ *
+ * @return the full path of this region
+ */
+ public String getFullPath();
+
+ /**
+ * Gets the parent region of this region. If
+ * this region is a root region, returns null.
+ * <p>
+ * Does not throw a <code>CacheClosedException</code> or a
+ * <code>RegionDestroyedException</code>.
+ *
+ * @return the parent region which contains this region;
+ * null, if this region is the root region
+ * @see Region#createSubregion(String, RegionAttributes) createSubregion
+ */
+ public <PK, PV> Region<PK, PV> getParentRegion();
+
+ /** Returns the <code>RegionAttributes</code> for this region.
+ * This object is backed by this region, so if attributes
+ * are modified using this region's <code>AttributesMutator</code>,
+ * this <code>RegionAttributes</code> object will immediately reflect the change.
+ * <p>
+ * Does not throw a <code>CacheClosedException</code> or a
+ * <code>RegionDestroyedException</code>.
+ *
+ * @return the <code>RegionAttributes</code> of this region
+ * @see Region#createSubregion(String, RegionAttributes)
+ * @see AttributesMutator
+ * @see AttributesFactory
+ * @see #getAttributesMutator
+ */
+ public RegionAttributes<K, V> getAttributes();
+
+
+ /** Returns a mutator object used for modifying this region's attributes
+ * after region creation.
+ * Note that some attributes are immutable after region creation.
+ *
+ * @return the <code>AttributesMutator</code> object
+ * @see #getAttributes
+ */
+ public AttributesMutator<K,V> getAttributesMutator();
+
+ /** Returns the <code>CacheStatistics</code> for this region.
+ *
+ * @return the <code>CacheStatistics</code> of this region
+ * @throws StatisticsDisabledException if statistics have been disabled for this region
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ */
+ public CacheStatistics getStatistics() throws StatisticsDisabledException;
+
+ /** Invalidates this region. Invalidation cascades to
+ * all entries and subregions. After
+ * the <code>invalidateRegion</code>, this region and the entries in it still
+ * exist. To remove all the entries and this region,
+ * <code>destroyRegion</code> should be used. The region invalidate will be distributed
+ * to other caches if the scope is not <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @see CacheListener#afterRegionInvalidate
+ */
+ public void invalidateRegion() throws TimeoutException;
+
+ /** Invalidates this region. The invalidation will cascade to
+ * all the subregions and cached entries. After
+ * the <code>invalidateRegion</code>, the region and the entries in it still
+ * exist. In order to remove all the entries and the region,
+ * <code>destroyRegion</code> should be used. The region invalidate will be distributed
+ * to other caches if the scope is not <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null. Should be serializable.
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for <code>Scope.GLOBAL</code>
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @throws IllegalArgumentException if aCallbackArgument is not serializable
+ * @see CacheListener#afterRegionInvalidate
+ */
+ public void invalidateRegion(Object aCallbackArgument) throws TimeoutException;
+
+
+
+ /** Invalidates this region in the local cache only. Invalidation
+ * cascades to all entries and subregions. After
+ * the <code>invalidateRegion</code>, 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 <code>CacheStatistics</code>.
+ *
+ * @throws IllegalStateException if this region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see CacheListener#afterRegionInvalidate
+ */
+ public void localInvalidateRegion();
+
+ /** Invalidates this region in the local cache only,
+ * and provides a user-defined argument to the <code>CacheListener</code>.
+ * The invalidation will cascade to
+ * all the subregions and cached entries. After
+ * the <code>invalidateRegion</code>, 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 <code>CacheStatistics</code>.
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null.
+ * @throws IllegalStateException if the region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see CacheListener#afterRegionInvalidate
+ */
+
+ public void localInvalidateRegion(Object aCallbackArgument);
+
+
+ /** 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 <code>RegionDestroyedException</code>.
+ * The region destroy will be distributed to other caches if the scope is
+ * not <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @throws CacheWriterException if a CacheWriter aborts the operation; if this
+ * occurs some subregions may have already been successfully destroyed.
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @see CacheListener#afterRegionDestroy
+ * @see CacheWriter#beforeRegionDestroy
+ */
+ public void destroyRegion() throws CacheWriterException, TimeoutException;
+
+ /** Destroys the whole region and provides a user-defined parameter
+ * object to any <code>CacheWriter</code> 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
+ * <code>RegionDestroyedException</code> exception. The region destroy is
+ * distributed to other caches if the scope is not <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param 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.
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws IllegalArgumentException if aCallbackArgument is not serializable
+ * @see CacheListener#afterRegionDestroy
+ * @see CacheWriter#beforeRegionDestroy
+ */
+ public void destroyRegion(Object aCallbackArgument) throws CacheWriterException, TimeoutException;
+
+ /** Destroys the whole region in the local cache only. No <code>CacheWriter</code>
+ * 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
+ * {@link RegionDestroyedException} exception.
+ * This operation is not distributed to any other cache.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @see CacheListener#afterRegionDestroy
+ */
+ public void localDestroyRegion();
+
+ /** Destroys the whole region in the local cache only, and provides a
+ * user-defined argument to a <code>CacheListener</code> if any.
+ *
+ * No <code>CacheWriter</code> 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
+ * {@link RegionDestroyedException} exception.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this call. Can be null.
+ * @see CacheListener#afterRegionDestroy
+ */
+ public void localDestroyRegion(Object aCallbackArgument);
+
+ /**
+ * Does a localDestroyRegion, but leaves behind the disk files if this
+ * is a region with persistBackup set to true.
+ * Calls {@link CacheListener#afterRegionDestroy} on each cache listener
+ * on the closed region(s).
+ * Also calls {@link CacheCallback#close} on each callback on the closed
+ * region(s).
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @see Region#localDestroyRegion()
+ * @see CacheListener#afterRegionDestroy
+ */
+ public void close();
+
+ /**
+ * Obtains the snapshot service to allow the cache data to be imported
+ * or exported.
+ *
+ * @return the snapshot service for the region
+ */
+ public RegionSnapshotService<K, V> getSnapshotService();
+
+ /**
+ * 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.
+ *
+ * @param outputStream the output stream to write to
+ * @throws IOException if encountered while writing the file
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see #loadSnapshot
+ *
+ * @deprecated as of 7.0 use {@link #getSnapshotService()}
+ */
+ public void saveSnapshot(OutputStream outputStream) throws IOException;
+
+ /**
+ * 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 {@link DataPolicy#withReplication 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).<p>
+ *
+ * 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).<p>
+ *
+ * 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.<p>
+ *
+ * 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.
+ *
+ * @param inputStream the inputStream to load the snapshot from
+ * @throws ClassNotFoundException if a class cannot be found while loading
+ * data
+ * @throws IOException if error encountered while reading file.
+ * @throws CacheWriterException if a CacheWriter aborts the destroyRegion
+ * operation; if this occurs some subregions may have already been
+ * successfully destroyed.
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ *
+ * @see RegionReinitializedException
+ *
+ * @deprecated as of 7.0 use {@link #getSnapshotService()}
+ */
+ public void loadSnapshot(InputStream inputStream)
+ throws IOException, ClassNotFoundException, CacheWriterException, TimeoutException;
+
+ /** 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 <code>regionName</code> is the empty string, then this
+ * region itself is returned.
+ *
+ * @param path the path to the subregion
+ * @return a subregion with the specified relative path from this region,
+ * or null if it doesn't exist
+ * @throws IllegalArgumentException if path starts with a forward slash or
+ * @see Region Region
+ * @see Region#getFullPath
+ */
+ public <SK, SV> Region<SK, SV> getSubregion(String path);
+
+
+ /** Creates a subregion with the specified name and <code>RegionAttributes</code>.
+ * The name must not contain a region name separator.
+ * If the subregion is a distributed {@link DataPolicy#withReplication replicated} region, it
+ * will be initialized with data from all other caches in this
+ * distributed system that have the same region.
+ *
+ * <p>Updates the {@link CacheStatistics#getLastAccessedTime} and
+ * {@link CacheStatistics#getLastModifiedTime} for this region.
+ *
+ * @param subregionName the subregion name
+ * @param aRegionAttributes the RegionAttributes to be used for the subregion
+ * @return a subregion with the specified name
+ * @throws IllegalArgumentException if aRegionAttributes is null or if
+ * regionName is null, the empty string, or contains a '/'
+ * @throws IllegalStateException If the supplied RegionAttributes violate the
+ * <a href="AttributesFactory.html#creationConstraints">region creation constraints</a>
+ * with a region of the same name in another cache in the distributed system
+ * or with this (parent) region.
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws RegionExistsException if a subregion by the specified name already exists
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see AttributesFactory
+ * @see Region#getFullPath
+ * @deprecated as of 7.0 use {@link RegionFactory#createSubregion(Region, String)} or {@link ClientRegionFactory#createSubregion(Region, String)}.
+ */
+ public <SK,SV> Region<SK,SV> createSubregion(String subregionName, RegionAttributes<SK,SV> aRegionAttributes)
+ throws RegionExistsException, TimeoutException;
+
+ /** 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.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ * @param recursive if false, collects direct subregions only; if true,
+ * collects all subregions recursively
+ * @return a Set of subregions
+ */
+ public Set<Region<?, ?>> subregions(boolean recursive);
+
+
+ /** Returns the <code>Region.Entry</code> for the specified key, or null if it doesn't
+ * exist.
+ *
+ * @param key the key corresponding to the Entry to return
+ * @return the Region.Entry for the specified key or null if not found in this
+ * region
+ * @throws NullPointerException if key is null
+ */
+ public Entry<K,V> getEntry(Object key);
+
+ /** 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.
+ *<p>
+ * 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.
+ *<p>
+ * 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.
+ *<p>
+ * The value returned by get is not copied, so multi-threaded applications
+ * should not modify the value directly, but should use the update methods.
+ *<p>
+ * Updates the {@link CacheStatistics#getLastAccessedTime},
+ * {@link CacheStatistics#getHitCount}, {@link CacheStatistics#getMissCount},
+ * and {@link CacheStatistics#getLastModifiedTime} (if a new value is loaded)
+ * for this region and the entry.
+ *<p>
+ *
+ * If the <code>CacheWriter</code> throws a
+ * <code>CacheWriterException</code> 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.
+ *
+ * @param 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.
+ * @return the value with specified key, or null if the value
+ * is not found and can't be loaded
+ * @throws NullPointerException if the key is null
+ * @throws IllegalArgumentException if the key does not meet
+ * the serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out doing a {@link Cache#getSearchTimeout search} for distributed or getting a distributed lock for Scope.GLOBAL
+ * @throws CacheLoaderException if a cache loader throws an exception, or if
+ * the cache loader returns an object that is not serializable and this
+ * is a distributed region
+ * @throws PartitionedRegionStorageException for a partitioned region fails to invoke a {@link CacheLoader}
+ * @see CacheLoader#load
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public V get(Object key) throws CacheLoaderException, TimeoutException;
+
+ /** 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.
+ *<p>
+ * 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.
+ *<p>
+ * 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.
+ *<p>
+ * The value returned by get is not copied, so multi-threaded applications
+ * should not modify the value directly, but should use the update methods.
+ *<p>
+ * Updates the {@link CacheStatistics#getLastAccessedTime},
+ * {@link CacheStatistics#getHitCount}, {@link CacheStatistics#getMissCount},
+ * and {@link CacheStatistics#getLastModifiedTime} (if a new value is loaded)
+ * for this region and the entry.
+ *
+ * If the <code>CacheWriter</code>
+ * throws a <code>CacheWriterException</code> 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.
+ *
+ * @param 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.
+ * @param 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.
+ * @return the value with specified key, or null if the value
+ * is not found and can't be loaded
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if aCallbackArgument is not serializable
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out doing a {@link Cache#getSearchTimeout search} for distributed or getting a distributed lock for Scope.GLOBAL
+ * @throws CacheLoaderException if a cache loader throws an exception, or if
+ * the cache loader returns an object that is not serializable and this
+ * is a distributed region
+ * @throws PartitionedRegionStorageException for a partitioned region fails to invoke a {@link CacheLoader}
+ * @see RegionAttributes
+ * @see CacheLoader#load
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public V get(Object key, Object aCallbackArgument)
+ throws TimeoutException, CacheLoaderException;
+
+ /** Places a new value into an entry in this region with the specified key.
+ * If there is already an entry associated with the specified key in this region,
+ * the entry's previous value is overwritten.
+ *
+ * <p>Updates the {@link CacheStatistics#getLastAccessedTime} and
+ * {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
+ *
+ * @param key a key associated with the value to be put into this region.
+ * The key object must implement the equals and hashCode methods.
+ * @param value the value to be put into the cache
+ * @return the previous value stored locally for the key.
+ * If the entry did not exist then <code>null</code> is returned.
+ * If the entry was "invalid" then <code>null</code> is returned.
+ * In some cases <code>null</code> may be returned even
+ * if a previous value exists.
+ * If the region is a client proxy then <code>null</code> is returned.
+ * If the region is partitioned and the put is done on a non-primary then <code>null</code> is returned.
+ * If the value is not currently stored in memory but is on disk
+ * and if the region does not have cqs
+ * then <code>null</code> is returned.
+ * @throws NullPointerException if key is null or if value
+ * is null (use invalidate instead), or if the key or value do not
+ * meet serializability requirements
+ * @throws ClassCastException if key does not satisfy the keyConstraint
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @throws PartitionedRegionStorageException if the operation could not be completed on a partitioned region.
+ * @throws LowMemoryException if a low memory condition is detected.
+ * @see #invalidate(Object)
+ * @see CacheLoader#load
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public V put(K key, V value)
+ throws TimeoutException, CacheWriterException;
+
+
+ /** Places a new value into an entry in this region with the specified key,
+ * providing a user-defined parameter
+ * object to any <code>CacheWriter</code> 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.
+ *
+ * <p>Updates the {@link CacheStatistics#getLastAccessedTime} and
+ * {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
+ *
+ * @param key a key associated with the value to be put into this region.
+ * The key object must implement the equals and hashCode methods.
+ * @param value the value to be put into the cache
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null. Should be serializable.
+ * @return the previous value stored locally for the key.
+ * If the entry did not exist then <code>null</code> is returned.
+ * If the entry was "invalid" then <code>null</code> is returned.
+ * In some cases <code>null</code> may be returned even
+ * if a previous value exists.
+ * If the region is a client proxy then <code>null</code> is returned.
+ * If the region is partitioned and the put is done on a non-primary then <code>null</code> is returned.
+ * If the value is not currently stored in memory but is on disk
+ * and if the region does not have cqs
+ * then <code>null</code> is returned.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if key, value, or
+ * aCallbackArgument do not meet serializability requirements
+ * @throws ClassCastException if key does not satisfy the keyConstraint
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @throws PartitionedRegionStorageException if the operation could not be completed on a partitioned region.
+ * @throws LowMemoryException if a low memory condition is detected.
+ * @see #invalidate(Object)
+ * @see CacheLoader#load
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public V put(K key, V value, Object aCallbackArgument)
+ throws TimeoutException, CacheWriterException;
+
+ /** Creates a new entry in this region with the specified key and value.
+ *
+ * <p>Updates the {@link CacheStatistics#getLastAccessedTime} and
+ * {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
+ *<p>
+ * 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 {@link InterestPolicy#ALL all events} configured.
+ *<p>
+ * This operation gets a distributed lock on the entry if the scope is
+ * <code>Scope.GLOBAL</code>.
+ *
+ * @param key the key for which to create the entry in this region
+ * @param value the value for the new entry, which may be null meaning
+ * the new entry starts as if it had been locally invalidated
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key or value
+ * is not serializable and this is a distributed region
+ * @throws ClassCastException if key does not satisfy the keyConstraint
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @throws EntryExistsException if an entry with this key already exists
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @throws PartitionedRegionStorageException if the operation could not be completed on a partitioned region.
+ * @throws LowMemoryException if a low memory condition is detected.
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public void create(K key, V value)
+ throws TimeoutException, EntryExistsException, CacheWriterException;
+
+ /** Creates a new entry in this region with the specified key and value,
+ * providing a user-defined parameter
+ * object to any <code>CacheWriter</code> invoked in the process.
+ * If this region has a distributed scope, then the value may be updated
+ * subsequently if other caches update the value.
+ *
+ * <p>Updates the {@link CacheStatistics#getLastAccessedTime} and
+ * {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
+ * <p>
+ * 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 {@link InterestPolicy#ALL all events} configured.
+ *
+ * @param key the key for which to create the entry in this region
+ * @param value the value for the new entry, which may be null meaning
+ * the new entry starts as if it had been locally invalidated.
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null. Should be serializable.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key, value, or
+ * aCallbackArgument do not meet serializability requirements
+ * @throws ClassCastException if key does not satisfy the keyConstraint
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @throws EntryExistsException if an entry with this key already exists
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @throws PartitionedRegionStorageException if the operation could not be completed on a partitioned region.
+ * @throws LowMemoryException if a low memory condition is detected.
+ * @see CacheListener#afterCreate
+ * @see CacheListener#afterUpdate
+ * @see CacheWriter#beforeCreate
+ * @see CacheWriter#beforeUpdate
+ */
+ public void create(K key, V value, Object aCallbackArgument)
+ throws TimeoutException, EntryExistsException, CacheWriterException;
+
+ /** 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.
+ *
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the value to be invalidated
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key does not
+ * meet serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @throws EntryNotFoundException if the entry does not exist in this region
+ * @see CacheListener#afterInvalidate
+ */
+ public void invalidate(Object key)
+ throws TimeoutException, EntryNotFoundException;
+
+ /** Invalidates the entry with the specified key,
+ * and provides a user-defined argument to the <code>CacheListener</code>.
+ * Invalidate only removes the value from the entry, the key is kept intact.
+ * To completely remove the entry, destroy should be used.
+ *
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the value to be invalidated
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null. Should be serializable.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key or the
+ * aCallbackArgument do not meet serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for <code>Scope.GLOBAL</code>
+ * @throws TimeoutException if timed out getting distributed lock for <code>Scope.GLOBAL</code>
+ * @throws EntryNotFoundException if this entry does not exist in this region
+ * @see CacheListener#afterInvalidate
+ */
+
+ public void invalidate(Object key, Object aCallbackArgument)
+ throws TimeoutException, EntryNotFoundException;
+
+ /** 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.
+ *
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the value to be invalidated
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key
+ * does not meet serializability requirements
+ * @throws IllegalStateException if this region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws EntryNotFoundException if the entry does not exist in this region locally
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @throws UnsupportedOperationInTransactionException If called in a transactional context
+ * @see CacheListener#afterInvalidate
+ */
+ public void localInvalidate(Object key) throws EntryNotFoundException;
+
+ /** Invalidates the value with the specified key in the local cache only,
+ * and provides a user-defined argument to the <code>CacheListener</code>.
+ * 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.
+ *
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the value to be invalidated
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null.
+ * @throws NullPointerException if key is null
+ * @throws IllegalStateException if this region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws EntryNotFoundException if this entry does not exist in this region locally
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @throws UnsupportedOperationInTransactionException If called in a transactional context
+ * @see CacheListener#afterInvalidate
+ */
+ public void localInvalidate(Object key, Object aCallbackArgument)
+ throws EntryNotFoundException;
+
+
+ /** Destroys the entry with the specified key. 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 <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the entry
+ * @return the previous value stored locally for the key.
+ * If the entry was "invalid" then <code>null</code> is returned.
+ * In some cases <code>null</code> may be returned even
+ * if a previous value exists.
+ * If the region is a client proxy then <code>null</code> is returned.
+ * If the region is partitioned and the destroy is done on a non-primary then <code>null</code> is returned.
+ * If the value is not currently stored in memory but is on disk
+ * and if the region does not have cqs
+ * then <code>null</code> is returned.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if key does not meet
+ * serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws EntryNotFoundException if the entry does not exist in this region
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @see CacheListener#afterDestroy
+ * @see CacheWriter#beforeDestroy
+ */
+ public V destroy(Object key)
+ throws TimeoutException, EntryNotFoundException, CacheWriterException;
+
+
+ /** Destroys the entry with the specified key, and provides a user-defined
+ * parameter object to any <code>CacheWriter</code> 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
+ * <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the entry to destroy
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null. Should be serializable.
+ * @return the previous value stored locally for the key.
+ * If the entry was "invalid" then <code>null</code> is returned.
+ * In some cases <code>null</code> may be returned even
+ * if a previous value exists.
+ * If the region is a client proxy then <code>null</code> is returned.
+ * If the region is partitioned and the destroy is done on a non-primary then <code>null</code> is returned.
+ * If the value is not currently stored in memory but is on disk
+ * and if the region does not have cqs
+ * then <code>null</code> is returned.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if the key or aCallbackArgument
+ * do not meet serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws EntryNotFoundException if the entry does not exist in this region
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @see CacheListener#afterDestroy
+ * @see CacheWriter#beforeDestroy
+ */
+ public V destroy(Object key, Object aCallbackArgument)
+ throws TimeoutException, EntryNotFoundException, CacheWriterException;
+
+ /** Destroys the value with the specified key in the local cache only,
+ * No <code>CacheWriter</code> is
+ * invoked. Destroy removes not only the value but also the key and entry
+ * from this region.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the entry to destroy
+ * @throws NullPointerException if key is null
+ * @throws IllegalStateException if this region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws EntryNotFoundException if the entry does not exist in this region locally
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @throws UnsupportedOperationInTransactionException If called in a transactional context
+ * @see CacheListener#afterDestroy
+ */
+ public void localDestroy(Object key) throws EntryNotFoundException;
+
+ /**
+ * Destroys the value with the specified key in the local cache
+ * only, and provides a user-defined
+ * parameter object to the <code>CacheListener</code>, if any. No <code>CacheWriter</code> is
+ * invoked. Destroy removes
+ * not only the value but also the key and entry from this region.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the entry to destroy
+ * @param aCallbackArgument a user-defined parameter to pass to callback events
+ * triggered by this method. Can be null.
+ * @throws NullPointerException if key is null
+ * @throws IllegalStateException if this region is distributed and
+ * {@link DataPolicy#withReplication replicated}
+ * @throws EntryNotFoundException if the entry does not exist in this region locally
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @throws UnsupportedOperationInTransactionException If called in a transactional context
+ * @see CacheListener#afterDestroy
+ */
+ public void localDestroy(Object key, Object aCallbackArgument) throws EntryNotFoundException;
+
+ /** Returns a set of keys in the region.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ *@deprecated Use <code>keySet</code> instead;
+ *
+ * @return a Set of all the keys
+ */
+ @Deprecated
+ public Set<K> keys();
+
+
+ /** Returns a set of keys in the region.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ *
+ * @return a Set of all the keys
+ */
+ public Set<K> keySet();
+
+ /** Returns a Collection of values in this region.
+ *
+ *<p>This <code>Collection</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this collection. No <code>ConcurrentModificationException</code>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.
+ *
+ * <p>Null values are not included in the result collection.
+ * @return a Collection of all the objects cached in this region
+ */
+ public Collection<V> values();
+
+ /** Returns the <code>Set</code> of <code>Region.Entry</code> 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.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ * @param 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
+ * @return a List of all the cached objects
+ *
+ * @deprecated Use <code>entrySet(boolean recursive)</code> instead.
+ * @see Region.Entry
+ */
+ @Deprecated
+ public Set<Region.Entry<?,?>> entries(boolean recursive);
+
+ /** Returns the <code>Set</code> of <code>Region.Entry</code> 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.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ * @param 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
+ * @return a Set of all the cached objects
+ * @see Region.Entry
+ */
+ public Set<Region.Entry<?,?>> entrySet(boolean recursive);
+
+ /** Returns the <code>Cache</code> associated with this region.
+ * <p>Does not throw a <code>CacheClosedException</code> if the Cache is closed.
+ * @return the Cache
+ * @deprecated as of 6.5 use {@link #getRegionService()} instead.
+ */
+ public Cache getCache();
+
+ /**
+ * Returns the <code>cache</code> associated with this region.
+ * <p>Does not throw a <code>CacheClosedException</code> if the cache is closed.
+ * @return the cache
+ * @since 6.5
+ */
+ public RegionService getRegionService();
+
+ /**
+ * Returns the application-defined object associated with this region.
+ * GemFire does not use this object for any purpose.
+ *
+ * @return the user attribute object or null if it has not been set
+ */
+ public Object getUserAttribute();
+
+ /** Sets the application-defined object associated with this region.
+ * GemFire does not use this object for any purpose.
+ * @param value the application-defined object
+ */
+ public void setUserAttribute(Object value);
+
+ /** Returns whether this region has been destroyed.
+ *
+ * <p>Does not throw a <code>RegionDestroyedException</code> if this region
+ * has been destroyed.
+ * @return true if this region has been destroyed
+ */
+ public boolean isDestroyed();
+
+ /** Returns whether there is a valid (non-null) value present for the specified
+ * key. This method is equivalent to:
+ * <pre>
+ * Entry e = getEntry(key);
+ * return e != null && e.getValue() != null;
+ * </pre>
+ *
+ * @param key the key to check for a valid value
+ * @return true if there is an entry in this region for the specified key
+ * and it has a valid value
+ */
+ public boolean containsValueForKey(Object key);
+
+ /** Returns whether the specified key currently exists in this region.
+ * This method is equivalent to <code>getEntry(key) != null</code>.
+ *
+ * @param key the key to check for an existing entry
+ * @return true if there is an entry in this region for the specified key
+ */
+ public boolean containsKey(Object key);
+
+
+ /** For {@link Scope#GLOBAL} regions, gets a <em>distributed</em>
+ * 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 {@link DataPolicy#withReplication replicated}
+ * regions when they acquire their initial data.
+ * <p>
+ * The operations invalidateRegion and destroyRegion do <em>not</em>
+ * 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.
+ * <p>
+ * See
+ * {@link #getDistributedLock} for the list of operations that automatically
+ * acquire distributed entry locks for regions with global scope.
+ * <p>
+ * Note that Region locks are potentially very expensive to acquire.
+ *
+ * @return a <code>Lock</code> used for acquiring a distributed lock on the entire region
+ * @throws IllegalStateException if the scope of this region is not global
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ */
+ public Lock getRegionDistributedLock() throws IllegalStateException;
+
+ /** For {@link Scope#GLOBAL} regions, gets a <em>distributed</em>
+ * lock on the entry with the specified key.
+ * Use of this <code>Lock</code> enables an application to synchronize
+ * operations on entries at a higher level than provided for by
+ * {@link 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:
+ * <pre>
+ * 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();
+ * }
+ * </pre>
+ *
+ * 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: <code>create</code>,
+ * <code>put</code>, <code>destroy</code>, <code>invalidate</code>,
+ * and <code>get</code> that causes a loader to be invoked.
+ * @return a <code>Lock</code> used for acquiring a distributed lock on an
+ * entry
+ * @throws IllegalStateException if the scope of this region is not global
+ * @throws NullPointerException if key is null
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ */
+ public Lock getDistributedLock(Object key) throws IllegalStateException;
+
+ /**
+ * Initiates a flush to asynchronously write unwritten region entries to disk.
+ *
+ * @throws IllegalStateException
+ * If this region is not configured to write to disk
+ * @throws DiskAccessException
+ * If problems are encounter while writing to disk
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see AttributesFactory#setPersistBackup
+ * @since 3.2
+ * @deprecated use {@link DiskStore#flush} instead.
+ */
+ @Deprecated
+ public void writeToDisk();
+
+ /**
+ * Determines whether there is a value in this <code>Region</code>
+ * that matches the given <code>queryPredicate</code>. Filters the
+ * values of this region using the predicate given as a string with
+ * the syntax of the <code>WHERE</code> clause of the query
+ * language. The predefined variable <code>this</code> may be used
+ * inside the predicate to denote the current value being filtered.
+ *
+ * @param queryPredicate
+ * A query language boolean query predicate.
+ *
+ * @return <code>true</code> if there is a value in region that
+ * matches the predicate, otherwise <code>false</code>.
+ *
+ * @throws QueryInvalidException
+ * If predicate does not correspond to valid query language
+ * syntax.
+ *
+ * @see QueryService
+ *
+ * @since 4.0
+ */
+ public boolean existsValue(String queryPredicate)
+ throws FunctionDomainException, TypeMismatchException, NameResolutionException,
+ QueryInvocationTargetException;
+ /**
+ * Filters the values of this region using the <code>queryPredicate</code>.
+ * 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.
+ *
+ * @see Pool#getQueryService
+ * @see Cache#getQueryService()
+ *
+ * @param queryPredicate
+ * A query language boolean query predicate.
+ *
+ * @return A <code>SelectResults</code> containing the values of this
+ * <code>Region</code> that match the
+ * <code>predicate</code>.
+ *
+ * @throws QueryInvalidException
+ * If exception occurs during query compilation or processing.
+ *
+ * @see QueryService
+ *
+ * @since 4.0
+ */
+ public <E> SelectResults<E> query(String queryPredicate)
+ throws FunctionDomainException, TypeMismatchException, NameResolutionException,
+ QueryInvocationTargetException;
+
+ /**
+ * Selects the single value in this <code>Region</code> that matches
+ * the given query <code>predicate</code>.
+ * 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 <code>this</code> may be used inside the predicate
+ * to denote the element currently being filtered.
+ *
+ * @param queryPredicate
+ * A query language boolean query predicate.
+ *
+ * @return The single element that evaluates to true for the
+ * predicate. If no value in this <code>Region</code>
+ * matches the predicate, <code>null</code> is returned.
+ *
+ * @throws QueryInvalidException
+ * If predicate does not correspond to valid query language
+ * syntax.
+ * @throws FunctionDomainException
+ * If more than one element evaluates to true.
+ *
+ * @see QueryService
+ * @since 4.0
+ */
+ public Object selectValue(String queryPredicate)
+ throws FunctionDomainException, TypeMismatchException, NameResolutionException,
+ QueryInvocationTargetException;
+
+ /**
+ * 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 <code>DiskAccessException</code> 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.
+ *
+ * @since 5.1
+ * @throws DiskAccessException
+ * @deprecated use {@link DiskStore#forceRoll} instead.
+ */
+ @Deprecated
+ public void forceRolling();
+
+ /**
+ * 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.
+ * <p>
+ * Calls to this method will block until grantor authority has been
+ * transferred to this member.
+ * <p>
+ * If another member later calls <code>becomeLockGrantor</code>, 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.
+ * <p>
+ * This region's scope must be <code>Scope.GLOBAL</code> to become a lock
+ * grantor.
+ * <p>
+ * 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.
+ *
+ * @throws IllegalStateException if scope is not GLOBAL
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ *
+ * @since 4.0
+ */
+ public void becomeLockGrantor();
+
+ /**
+ * Removes all local entries from this region. This is not a distributed operation.
+ * This operation is not allowed on replicated regions.
+ *
+ * @since 5.0
+ * @throws UnsupportedOperationException If the region is a replicated region
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ * @see CacheListener#afterRegionClear
+ *
+ */
+ public void localClear();
+
+////// Map API's ////
+ /**
+ * Removes all entries from this region. Clear will be distributed to other caches if the scope
+ * is not <code>Scope.LOCAL</code>.
+ * <p>
+ * @since 5.0
+ * @see java.util.Map#clear()
+ * @see CacheListener#afterRegionClear
+ * @see CacheWriter#beforeRegionClear
+ * @throws UnsupportedOperationException If the region is a partitioned region
+ */
+ public void clear();
+
+ /**
+ * 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.
+ *
+ * @since 5.0
+ * @see java.util.Map#containsValue(Object)
+ */
+ public boolean containsValue(Object value);
+
+ /**
+ * Returns the <code>Set</code> of <code>Region.Entry</code> objects in this region.
+ *
+ *<p>This <code>Set</code> is unmodifiable. It is
+ * backed by this region. Synchronization is not necessary to access or
+ * iterate over this set. No <code>ConcurrentModificationException</code>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.
+ *
+ * @return a Set of all the Region.Entry instances in this region locally
+ * @since 5.0
+ * @see java.util.Map#entrySet()
+ */
+ public Set<Map.Entry<K,V>> entrySet(); //@todo darrel: should be Region.Entry
+
+ /**
+ * Returns true if this region contains no entries.
+ *@since 5.0
+ * @see java.util.Map#isEmpty()
+ * @return true if this region contains no entries.
+ */
+ public boolean isEmpty();
+
+ /**
+ * Copies all of the entries from the specified map to this region.
+ * The effect of this call is equivalent to that of calling {@link #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 <code>Scope.LOCAL</code>.
+ * @param map the key/value pairs to put in this region.
+ * @since 5.0
+ * @see java.util.Map#putAll(Map map)
+ * @throws LowMemoryException if a low memory condition is detected.
+ */
+ public void putAll(Map<? extends K, ? extends V> map);
+
+ /**
+ * Copies all of the entries from the specified map to this region.
+ * The effect of this call is equivalent to that of calling {@link #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 <code>Scope.LOCAL</code>.
+ * @param map the key/value pairs to put in this region.
+ * @param 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.
+ * @since 8.1
+ * @see java.util.Map#putAll(Map map)
+ * @throws LowMemoryException if a low memory condition is detected.
+ */
+ public void putAll(Map<? extends K, ? extends V> map, Object aCallbackArgument);
+
+ /**
+ * Removes all of the entries for the specified keys from this region.
+ * The effect of this call is equivalent to that of calling {@link #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 <code>Scope.LOCAL</code>.
+ * @param keys the keys to remove from this region.
+ * @since 8.1
+ * @see Region#destroy(Object)
+ */
+ public void removeAll(Collection<? extends K> keys);
+ /**
+ * Removes all of the entries for the specified keys from this region.
+ * The effect of this call is equivalent to that of calling {@link #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 <code>Scope.LOCAL</code>.
+ * @param keys the keys to remove from this region.
+ * @param 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.
+ * @since 8.1
+ * @see Region#destroy(Object, Object)
+ */
+ public void removeAll(Collection<? extends K> keys, Object aCallbackArgument);
+
+ /**
+ * Gets values for all the keys in the input Collection.
+ * If a given key does not exist in the region then that key's value in the
+ * returned map will be <code>null</code>.
+ * <p>
+ * 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.
+ * @param keys A Collection of keys
+ * @return A Map of values for the input keys
+ *
+ * @since 5.7
+ */
+ public Map<K, V> getAll(Collection<?> keys);
+ /**
+ * Gets and returns values for all the keys in the input Collection.
+ * If a given key does not exist in the region then that key's value in the
+ * returned map will be <code>null</code>.
+ * @param <T> the type of the keys passed to getAll
+ * @param keys A Collection of keys
+ * @param aCallbackArgument 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.
+ * @return A Map of values for the input keys
+ *
+ * @since 8.1
+ */
+ public <T extends K> Map<T, V> getAll(Collection<T> keys, Object aCallbackArgument);
+
+
+ /**
+ * 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 <code>Scope.LOCAL</code>.
+ * <p>
+ * Does not update any <code>CacheStatistics</code>.
+ *
+ * @param key the key of the entry
+ * @return <code>null</code> 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 <code>null</code> is returned.
+ * In some cases <code>null</code> may be returned even
+ * if a previous value exists.
+ * If the region is a client proxy then <code>null</code> is returned.
+ * If the region is partitioned and the remove is done on a non-primary then <code>null</code> is returned.
+ * If the value is not currently stored in memory but is on disk
+ * and if the region does not have cqs
+ * then <code>null</code> is returned.
+ * @throws NullPointerException if key is null
+ * @throws IllegalArgumentException if key does not meet
+ * serializability requirements
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws CacheWriterException if a CacheWriter aborts the operation
+ * @see Region#destroy(Object)
+ * @see CacheListener#afterDestroy
+ * @see CacheWriter#beforeDestroy
+ * @see java.util.Map#remove(Object)
+ *
+ * @since 5.0
+ */
+ public V remove(Object key);
+
+ /**
+ * Returns the number of entries present in this region.
+ *
+ * For {@link 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.
+ *
+ * @since 5.0
+ * @see java.util.Map#size()
+ * @return int the number of entries present in this region
+ */
+ public int size();
+ /**
+ *
+ * Compares the specified object with this region for equality.
+ * Regions are only equal to themselves (identity based) so {@link Object#equals} is used.
+ * Note that some other class that implements <code>Map</code> 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.
+ *
+ * @param other Object object to be compared against the this
+ * @return <tt>true</tt> if the specified object is equal to this region.
+ * @see Object#equals
+ */
+ public boolean equals(Object other);
+ /**
+ * Returns the hash code value for this region. The hash code of a region is
+ * based on identity and uses {@link Object#hashCode}.
+ * @return the hash code value for this region.
+ * @see Object#hashCode()
+ */
+ public int hashCode();
+
+ /**
+ * 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.
+ *
+ * @param key The key on which to register interest. If the key is a
+ * <code>List</code>, then all the keys in the <code>List</code> 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.
+ *
+ * <p>This method uses the default <code>InterestResultPolicy</code>.</p>
+ *
+ * <p><i>Using 'ALL_KEYS' is the same as calling {@link #registerInterestRegex(String)}
+ * with ".*" as the argument. This means that all keys any type are
+ * pushed to the client and inserted into the local cache.</i></p>
+ *
+ * <p>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.</p>
+ *
+ * @see InterestResultPolicy
+ *
+ * @since 4.2
+ *
+ * @throws UnsupportedOperationException if the region is not configured with a pool name.
+ * @throws SubscriptionNotEnabledException if the region's pool does not have subscriptions enabled.
+ * @throws UnsupportedOperationException if the region is a replicate with distributed scope.
+ */
+ public void registerInterest(K key);
+
+ /**
+ * 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).
+ *
+ * <p>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.</p>
+ *
+ * @param key The key on which to register interest. If the key is a
+ * <code>List</code>, then all the keys in the <code>List</code> 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.
+ *
+ * <p><i>Using 'ALL_KEYS' is the same as calling {@link #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.</i></p>
+ *
+ * @param policy The interest result policy. This can be one of:
+ * <ul>
+ * <li>InterestResultPolicy.NONE - does not initialize the local cache</li>
+ * <li>InterestResultPolicy.KEYS - initializes the local cache with the
+ * keys satisfying the request</li>
+ * <li>InterestResultPolicy.KEYS_VALUES - initializes the local cache with
+ * the keys and current values satisfying the request</li>
+ * </ul>
+ * @throws UnsupportedOperationException if the region is not configured with a pool name.
+ * @throws SubscriptionNotEnabledException if the region's pool does not have subcriptions enabled.
+ * @throws UnsupportedOperationException if the region is a replicate with distributed scope.
+ *
+ * @see InterestResultPolicy
+ *
+ * @since 4.2.3
+ */
+ public void registerInterest(K key, InterestResultPolicy policy);
+
+ /**
+ * Sends a request to the CacheServer to register interest in a regular
+ * expression pattern for this client. Updates to any keys of type {@link 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 {@link String}
+ * that satisfy the regular expression are inserted into the local cache before this call returns.
+ *
+ * <p>Note that if the <code>regex</code> is <code>".*"</code> then all keys of any type will be pushed to the client.
+ * <p>This method uses the default <code>InterestResultPolicy</code>.</p>
+ *
+ * <p>The regular expression string is compiled using the {@link java.util.regex.Pattern} class.</p>
+ *
+ * <p>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.</p>
+ *
+ * @param regex The regular expression on which to register interest.
+ *
+ * @throws UnsupportedOperationException if the region is not configured with a pool name.
+ * @throws SubscriptionNotEnabledException if the region's pool does not have subscriptions enabled.
+ * @throws UnsupportedOperationException if the region is a replicate with distributed scope.
+ * @see InterestResultPolicy
+ * @see java.util.regex.Pattern
+ *
+ * @since 4.2.3
+ */
+ public void registerInterestRegex(String regex);
+
+ /**
+ * Sends a request to the CacheServer to register interest in a regular
+ * expression pattern for this client. Updates to any keys of type {@link 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 {@link String}
+ * that satisfy the regular expression are inserted into the local cache before this call returns.
+ *
+ * <p>The regular expression string is compiled using the {@link java.util.regex.Pattern} class.</p>
+ *
+ * <p>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.</p>
+ *
+ * @param regex The regular expression on which to register interest.
+ * @param policy The interest result policy. This can be one of:
+ * <ul>
+ * <li>InterestResultPolicy.NONE - does not initialize the local cache</li>
+ * <li>InterestResultPolicy.KEYS - initializes the local cache with the
+ * keys satisfying the request</li>
+ * <li>InterestResultPolicy.KEYS_VALUES - initializes the local cache with
+ * the keys and current values satisfying the request</li>
+ * </ul>
+ * @throws UnsupportedOperationException if the region is not configured with a pool name.
+ * @throws SubscriptionNotEnabledException if the region's pool does not have subscriptions enabled.
+ * @throws UnsupportedOperationException if the region is a replicate with distributed scope.
+ *
+ * @see InterestResultPolicy
+ * @see java.util.regex.Pattern
+ *
+ * @since 4.2.3
+ */
+ public void registerInterestRegex(String regex, InterestResultPolicy policy);
+
+ /**
+ * 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.
+ *
+ * @param key The key on which to register interest. If the key is a
+ * <code>List</code>, then all the keys in the <code>List</code> will
+ * be unregistered.
+ * @throws UnsupportedOperationException if the region is not configured with a pool name.
+ *
+ * @since 4.2
+ */
+ public void unregisterInterest(K key);
+
+ /**
+ * 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.
+ *
+ * @param regex The regular expression on which to unregister i
<TRUNCATED>