| /*========================================================================= |
| * 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 off-heap and the old value was stored in off-heap memory 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 off-heap and the old value was stored in off-heap memory 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 off-heap and the old value was stored in off-heap memory 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 off-heap and the old value was stored in off-heap memory 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 interest. |
| * @throws UnsupportedOperationException if the region is not configured with a pool name. |
| * |
| * @since 4.2.3 |
| */ |
| public void unregisterInterestRegex(String regex); |
| /** |
| * Returns the list of keys on which this client is interested and will be |
| * notified of changes. This method is currently supported only on clients |
| * in a client server topology. |
| * |
| * @return The list of keys on which this client is interested |
| * @throws UnsupportedOperationException if the region is not configured with a pool name. |
| * |
| * @since 4.2 |
| */ |
| public List<K> getInterestList(); |
| |
| |
| /** |
| * 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. |
| * |
| * @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> |
| * |
| * @param isDurable |
| * true if the register interest is durable |
| * |
| * @see InterestResultPolicy |
| * |
| * @since 5.5 |
| * |
| * @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, boolean isDurable); |
| |
| /** |
| * 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. |
| * |
| * <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>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> |
| * |
| * @param isDurable |
| * true if the register interest is durable |
| * |
| * @param receiveValues defaults to true. set to false to receive create or update events |
| * as invalidates similar to notify-by-subscription false. |
| * |
| * @see InterestResultPolicy |
| * |
| * @since 6.0.3 |
| * |
| * @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, boolean isDurable, boolean receiveValues); |
| |
| /** |
| * 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). |
| * |
| * <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> |
| * @param isDurable |
| * true if the register interest is durable |
| * @param receiveValues defaults to true. set to false to receive create or update events |
| * as invalidates similar to notify-by-subscription false. |
| * @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 |
| * |
| * @since 6.0.3 |
| */ |
| public void registerInterest(K key, InterestResultPolicy policy, |
| boolean isDurable, boolean receiveValues); |
| |
| /** |
| * Sends a request to the CacheServer to register interest in a key for |
| * this client. 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). |
| * |
| * @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> |
| * |
| * <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 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> |
| * @param isDurable |
| * true if the register interest is durable |
| * @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 |
| * |
| * @since 5.5 |
| */ |
| public void registerInterest(K key, InterestResultPolicy policy, boolean isDurable); |
| |
| /** |
| * 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>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> |
| * |
| * <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> |
| * |
| * @param regex The regular expression on which to register interest. |
| * |
| * @param isDurable |
| * true if the register interest is durable |
| * @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 5.5 |
| */ |
| public void registerInterestRegex(String regex, boolean isDurable); |
| |
| /** |
| * 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. |
| * |
| * @param isDurable |
| * true if the register interest is durable |
| * @param receiveValues defaults to true. set to false to receive create or update events |
| * as invalidates similar to notify-by-subscription false. |
| * @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 6.0.3 |
| */ |
| public void registerInterestRegex(String regex, boolean isDurable, |
| boolean receiveValues); |
| |
| /** |
| * Sends a request to the CacheServer to register interest in a regular |
| * expression pattern for this client. 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> |
| * @param isDurable |
| * true if the register interest is durable |
| * @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 5.5 |
| */ |
| public void registerInterestRegex(String regex, InterestResultPolicy policy, boolean isDurable); |
| |
| /** |
| * Sends a request to the CacheServer to register interest in a regular |
| * expression pattern for this client. 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> |
| * @param isDurable |
| * true if the register interest is durable |
| * @param receiveValues defaults to true. set to false to receive create or update events |
| * as invalidates similar to notify-by-subscription false. |
| * @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 6.0.3 |
| */ |
| public void registerInterestRegex(String regex, InterestResultPolicy policy, |
| boolean isDurable, boolean receiveValues); |
| |
| /** |
| * Returns the list of regular expresssions on which this client is interested |
| * and will be notified of changes. This method is currently supported only on |
| * clients in a client server topology. |
| * |
| * @return The list of regular expresssions on which this client is interested |
| * @throws UnsupportedOperationException if the region is not configured with a pool name. |
| * |
| * @since 4.2.3 |
| */ |
| public List<String> getInterestListRegex(); |
| |
| /** Returns a set of keys in the region on the server. |
| * |
| * @return a Set of all the keys in the region on the server |
| * @throws UnsupportedOperationException if the region is not configured with a pool name. |
| * |
| * @since 5.0.2 |
| */ |
| public Set<K> keySetOnServer(); |
| |
| /** Returns whether the specified key currently exists in this region on the |
| * server. |
| * |
| * @param key the key to check for an existing entry |
| * @return true if there is an entry in this region for the specified key on |
| * the server |
| * @throws UnsupportedOperationException if the region is not configured with a pool name. |
| * |
| * @since 5.0.2 |
| */ |
| public boolean containsKeyOnServer(Object key); |
| |
| /** |
| * If the specified key is not already associated |
| * with a value, associate it with the given value. |
| * This is equivalent to |
| * <pre> |
| * if (!map.containsKey(key)) |
| * return map.put(key, value); |
| * else |
| * return map.get(key);</pre> |
| * except that the action is performed atomically. |
| * |
| *<p>ConcurrentMap operations are supported on partitioned and replicated regions |
| *and in client caches. They are also supported on non-empty local regions.</p> |
| *<p>Please read the notes on ConcurrentMap operations in the javadoc for Region.</p> |
| *<p>Region allows the value parameter to be null, which will create an invalid entry.</p> |
| * @param key key with which the specified value is to be associated |
| * @param value value to be associated with the specified key |
| * @return the previous value associated with the specified key, or |
| * <tt>null</tt> if there was no mapping for the key. |
| * (A <tt>null</tt> return can also indicate that the map |
| * previously associated <tt>null</tt> with the key, |
| * if the implementation supports null values.) |
| * @throws UnsupportedOperationException if the <tt>put</tt> operation |
| * is not supported by this map |
| * @throws ClassCastException if the class of the specified key or value |
| * prevents it from being stored in this map |
| * @throws NullPointerException if the specified key or value is null, |
| * and this map does not permit null keys or values |
| * @throws IllegalArgumentException if some property of the specified key |
| * or value prevents it from being stored in this map |
| * @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. |
| * @since 6.5 |
| * |
| */ |
| V putIfAbsent(K key, V value); |
| |
| /** |
| * Removes the entry for a key only if currently mapped to a given value. |
| * This is equivalent to |
| * <pre> |
| * if (map.containsKey(key) && map.get(key).equals(value)) { |
| * map.remove(key); |
| * return true; |
| * } else return false;</pre> |
| * except that the action is performed atomically. |
| *<p>As of 8.5, if value is an Array then Arrays.equals or Arrays.deepEquals is used |
| *instead of Object.equals. |
| *<p>ConcurrentMap operations are supported on partitioned and replicated regions |
| *and in client caches. They are also supported on non-empty local regions.<p> |
| *<p>Please read the notes on ConcurrentMap operations in the javadoc for Region.</p> |
| *<p>Region allows the value parameter to be null, which will match an invalid entry.</p> |
| * @param key key with which the specified value is associated |
| * @param value value expected to be associated with the specified key |
| * @return <tt>true</tt> if the value was removed |
| * @throws UnsupportedOperationException if the <tt>remove</tt> operation |
| * is not supported by this map |
| * @throws ClassCastException if the key or value is of an inappropriate |
| * type for this map (optional) |
| * @throws NullPointerException if the specified key or value is null, |
| * and this map does not permit null keys or values (optional) |
| * @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. |
| * @since 6.5 |
| */ |
| boolean remove(Object key, Object value); |
| |
| /** |
| * Replaces the entry for a key only if currently mapped to a given value. |
| * This is equivalent to |
| * <pre> |
| * if (map.containsKey(key) && map.get(key).equals(oldValue)) { |
| * map.put(key, newValue); |
| * return true; |
| * } else return false;</pre> |
| * except that the action is performed atomically. |
| *<p>As of 8.5, if value is an Array then Arrays.equals or Arrays.deepEquals is used |
| *instead of Object.equals. |
| *<p>ConcurrentMap operations are supported on partitioned and replicated regions |
| *and in client caches. They are also supported on non-empty local regions.</p> |
| *<p>Please read the notes on ConcurrentMap operations in the javadoc for Region.</p> |
| *<p>Region allows the oldValue parameter to be null, which will match an invalid entry.</p> |
| * @param key key with which the specified value is associated |
| * @param oldValue value expected to be associated with the specified key |
| * @param newValue value to be associated with the specified key |
| * @return <tt>true</tt> if the value was replaced |
| * @throws UnsupportedOperationException if the <tt>replace</tt> operation |
| * is not supported by this map |
| * @throws ClassCastException if the class of a specified key or value |
| * prevents it from being stored in this map |
| * @throws NullPointerException if a specified key is null, |
| * and this map does not permit null keys |
| * @throws IllegalArgumentException if some property of a specified key |
| * or value prevents it from being stored in this map |
| * @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. |
| * @since 6.5 |
| */ |
| boolean replace(K key, V oldValue, V newValue); |
| |
| /** |
| * Replaces the entry for a key only if currently mapped to some value. |
| * This is equivalent to |
| * <pre> |
| * if (map.containsKey(key)) { |
| * return map.put(key, value); |
| * } else return null;</pre> |
| * except that the action is performed atomically. |
| *<p>ConcurrentMap operations are supported on partitioned and replicated regions |
| *and in client caches. They are also supported on non-empty local regions.</p> |
| *<p>Please read the notes on ConcurrentMap operations in the javadoc for Region.</p> |
| * |
| * @param key key with which the specified value is associated |
| * @param value value to be associated with the specified key |
| * @return the previous value associated with the specified key, or |
| * <tt>null</tt> if there was no mapping for the key. |
| * (A <tt>null</tt> return can also indicate that the map |
| * previously associated <tt>null</tt> with the key, |
| * if the implementation supports null values.) |
| * @throws UnsupportedOperationException if the <tt>put</tt> operation |
| * is not supported by this map |
| * @throws ClassCastException if the class of the specified key or value |
| * prevents it from being stored in this map |
| * @throws NullPointerException if the specified key or value is null, |
| * and this map does not permit null keys or values |
| * @throws IllegalArgumentException if some property of the specified key |
| * or value prevents it from being stored in this map |
| * @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. |
| * @since 6.5 |
| */ |
| V replace(K key, V value); |
| |
| /** A key-value pair containing the cached data in a region. This object's |
| * operations (except for{Entry#setValue()}), are not distributed, do not acquire any locks, and do not affect |
| * <code>CacheStatistics</code>. |
| *<p> |
| * Unless otherwise noted, all of these methods throw a |
| * <code>CacheClosedException</code> if the Cache is closed at the time of |
| * invocation, or an <code>EntryDestroyedException</code> if the entry has been |
| * destroyed. |
| */ |
| public interface Entry<K, V> extends Map.Entry<K,V>{ |
| |
| /** Returns the key for this entry. |
| * |
| * @return the key for this entry |
| */ |
| public K getKey(); |
| |
| /** Returns the value of this entry in the local cache. Does not invoke |
| * a <code>CacheLoader</code>, does not do a netSearch, netLoad, etc. |
| * |
| * @return the value or <code>null</code> if this entry is invalid |
| */ |
| public V getValue(); |
| |
| /** Returns the region that contains this entry. |
| * |
| * @return the Region that contains this entry |
| */ |
| public Region<K,V> getRegion(); |
| |
| /** This method checks to see if the entry is in the in-process cache, or |
| * is in another process. Only Regions with {@link DataPolicy#PARTITION} may return |
| * false in response to this query. A non-local Entry will not reflect |
| * dynamic changes being made to the cache. For instance, the result of |
| * getValue() will not change, even though the cache may have been updated |
| * for the corresponding key. To see an updated snapshot of a non-local |
| * Entry, you must fetch the entry from the Region again. |
| */ |
| public boolean isLocal(); |
| |
| /** Returns the statistics for this entry. |
| * |
| * @return the CacheStatistics for this entry |
| * @throws StatisticsDisabledException if statistics have been disabled for |
| * this region |
| */ |
| public CacheStatistics getStatistics(); |
| |
| /** Returns the user attribute for this entry in the local cache. |
| * |
| * @return the user attribute for this entry |
| */ |
| public Object getUserAttribute(); |
| |
| /** Sets the user attribute for this entry. Does not distribute the user |
| * attribute to other caches. |
| * |
| * @param userAttribute the user attribute for this entry |
| * @return the previous user attribute or null no user attributes has been |
| * set for this entry |
| */ |
| public Object setUserAttribute(Object userAttribute); |
| |
| /** |
| * Returns whether this entry has been destroyed. |
| * <p>Does not throw a <code>EntryDestroyedException</code> if this entry |
| * has been destroyed. |
| * |
| * @return true if this entry has been destroyed |
| */ |
| public boolean isDestroyed(); |
| |
| /** |
| * Sets the value of this entry. It has similar to calling a put on the |
| * key of this Entry |
| * @param value Object the value to be set |
| * @return the previous value object stored locally for this entry. |
| * 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 off-heap and the old value was stored in off-heap memory then <code>null</code> is returned. |
| * If the region is partitioned and the setValue 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. |
| * @since 5.0 |
| * @see Region#put(Object, Object) |
| */ |
| public V setValue(V value); |
| } |
| } |
