com.gemstone.gemfire.cache.Region Maven / Gradle / Ivy
Show all versions of gemfire-core Show documentation
/*
* Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you
* may not use this file except in compliance with the License. You
* may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License. See accompanying
* LICENSE file.
*/
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.
*
*
* 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}.
*
*
* 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.
*
*
* A region's name can be any String except that it should not contain
* the region name separator, a forward slash (/).
*
* Regions can be referenced by a relative path name from any region
* higher in the hierarchy in {@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.
*
* Relative region names can provide a convenient
* method to locate a subregion directly from some higher region. For example,
* a region structure is as follows:
* a region named 3rd_level_region has parent region 2nd_level_region; region
* 2nd_level_region in turn has parent region 1st_level_region; and region
* 1st_level_region is a child of the root region. Then,the user can get the region
* 3rd_level_region from the root region by issuing:
*
*
* region3 = root.getSubregion("1st_level_region/2nd_level_region/3rd_level_region");
*
*
* or the user can get the region 3rd_level_region from region 1st_level_region
* by issuing
*
*
* region3 = region1.getSubregion("2nd_level_region/3rd_level_region");
*
*
*
* Region entries are identified by their key. Any Object can be used as a key
* as long as the key Object
* is region-wide unique and implements both the equals and
* hashCode methods. For regions with distributed scope, the key must also be Serializable.
*
* Regions and their entries can be locked. The Lock
* obtained from {@link #getRegionDistributedLock} is a distributed lock on the
* entire Region, and the Lock obtained from
* {@link Region#getDistributedLock} is a distributed lock on the individual
* entry.
*
*
If the scope is Scope.GLOBAL, the methods
* that modify, destroy, or invalidate the entries in this region will also get a
* distributed lock. See the documentations for {@link #getDistributedLock} and
* {@link #getRegionDistributedLock} for details on the implicit locking that
* occurs for regions with Scope.GLOBAL.
*
* Unless otherwise specified, all of these methods throw a
* CacheClosedException if the Cache is closed at the time of
* invocation, or a RegionDestroyedException if this region has been
* destroyed.
* Serializability Requirements for arguments: Several methods in the region API
* take parameters such as key, value and callback parameters.All of these parameters
* are typed as objects.
* For distributed regions, keys, values and callback parameters have to be serializable
* Failure to meet these serialization requirements
* causes API methods to throw IllegalArgumentException.
*
* Implementation of the java.util.concurrent.ConcurrentMap interface was added
* in version 6.5. These methods give various levels
* of concurrency guarantees based on the scope and data policy of the region.
* They are implemented in the peer cache and client/server cache but are
* disallowed in peer Regions having NORMAL or EMPTY data policies.
*
* The semantics of the ConcurrentMap methods on a Partitioned Region are
* consistent with those expected on a ConcurrentMap. In particular
* multiple writers in different JVMs of the same key in the same
* Partitioned Region will be done atomically.
*
* The same is true for a region with GLOBAL scope. All operations will be
* done atomically since a distributed lock will be held while the
* operation is done.
*
* The same is true for a region with LOCAL scope. All ops will be done
* atomically since the underlying map is a concurrent hash map and no
* distribution is involved.
*
* For peer REPLICATE and PRELOADED regions atomicity is limited to
* threads in the JVM the operation starts in. There is no coordination with
* other members of the system unless the operation is performed in a
* transaction.
*
* For client server regions the atomicity is determined by the scope and
* data policy of the server region as described above. The operation is
* actually performed on the server as described above. Clients will
* always send the ConcurrentMap operation to the server and the result
* returned by the ConcurrentMap method in client will reflect what was
* done on the server. Same goes for any CacheListener called on the
* client. Any local state on the client will be updated to be consistent
* with the state change made on the server.
*
* @see RegionAttributes
* @see AttributesFactory
* @see AttributesMutator
* @see Region.Entry
* @since 2.0
*/
public interface Region extends Map, ConcurrentMap{
/** 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".
*
* Does not throw a CacheClosedException or a
* RegionDestroyedException.
*
* @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.
*
* Does not throw a CacheClosedException or a
* RegionDestroyedException.
*
* @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.
*
* Does not throw a CacheClosedException or a
* RegionDestroyedException.
*
* @return the parent region which contains this region;
* null, if this region is the root region
* @see Region#createSubregion(String, RegionAttributes) createSubregion
*/
public Region getParentRegion();
/** Returns the RegionAttributes for this region.
* This object is backed by this region, so if attributes
* are modified using this region's AttributesMutator,
* this RegionAttributes object will immediately reflect the change.
*
* Does not throw a CacheClosedException or a
* RegionDestroyedException.
*
* @return the RegionAttributes of this region
* @see Region#createSubregion(String, RegionAttributes)
* @see AttributesMutator
* @see AttributesFactory
* @see #getAttributesMutator
*/
public RegionAttributes 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 AttributesMutator object
* @see #getAttributes
*/
public AttributesMutator getAttributesMutator();
/** Returns the CacheStatistics for this region.
*
* @return the CacheStatistics 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 invalidateRegion, this region and the entries in it still
* exist. To remove all the entries and this region,
* destroyRegion should be used. The region invalidate will be distributed
* to other caches if the scope is not Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @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#afterRegionInvalidate
*/
public void invalidateRegion() throws TimeoutException;
/** Invalidates this region. The invalidation will cascade to
* all the subregions and cached entries. After
* the invalidateRegion, the region and the entries in it still
* exist. In order to remove all the entries and the region,
* destroyRegion should be used. The region invalidate will be distributed
* to other caches if the scope is not Scope.LOCAL.
*
* Does not update any CacheStatistics.
* @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 Scope.GLOBAL
* @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
* @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 invalidateRegion, this region and the entries in it still
* exist. To remove all the entries and this region,
* destroyRegion should be used.
*
* Does not update any CacheStatistics.
*
* @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 CacheListener.
* The invalidation will cascade to
* all the subregions and cached entries. After
* the invalidateRegion, the region and the entries in it still
* exist. In order to remove all the entries and the region,
* destroyRegion should be used.
*
* Does not update any CacheStatistics.
* @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 RegionDestroyedException.
* The region destroy will be distributed to other caches if the scope is
* not Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @throws CacheWriterException if a CacheWriter aborts the operation; if this
* occurs some subregions may have already been successfully destroyed.
* @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 CacheWriter invoked in the process.
* Destroy cascades to all entries
* and subregions. After the destroy, this region object can not be used
* any more. Any attempt to use this region object will get a
* RegionDestroyedException exception. The region destroy is
* distributed to other caches if the scope is not Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @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 CacheWriter
* is invoked.
* Destroy cascades to all entries and subregions.
* After the destroy, this region object can not be used
* any more and any attempt to use this region object will get
* {@link RegionDestroyedException} exception.
* This operation is not distributed to any other cache.
*
* Does not update any CacheStatistics.
*
* @see CacheListener#afterRegionDestroy
*/
public void localDestroyRegion();
/** Destroys the whole region in the local cache only, and provides a
* user-defined argument to a CacheListener if any.
*
* No CacheWriter is invoked.
* Destroy will cascade to all the entries
* and subregions. After the destroy, this region object can not be used
* any more. Any attempt to use this region object will get
* {@link RegionDestroyedException} exception.
*
* Does not update any CacheStatistics.
* @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).
*
* Does not update any CacheStatistics.
*
* @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 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).
*
* In order to continue working with this region, a new reference needs to be
* acquired using Cache#getRegion or Region#getSubregion (which will block until
* reinitialization is complete).
*
* NOTE: SUBREGIONS ARE DESTROYED.
* Since loading a snapshot effectively destroys the region and recreates
* it, all subregions of this region in this cache as well as other remote
* caches in the same distributed system are destroyed.
*
* If any error occurs while loading the snapshot, this region is destroyed
* and threads in remote caches that are attempting to get a reference to this
* region will get null instead of a region reference.
*
* The only callbacks that are invoked are called for the destroyRegion
* operation, i.e. the CacheWriter and the close methods on callbacks.
* CacheListeners and other callback objects have their close() methods called
* when the region is destroyed, and then those same callback objects will
* be reinstalled on the new region. Therefore, the callback objects should
* be able to handle a close() followed by events associated with the newly
* created region.
*
* @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 regionName 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 Region getSubregion(String path);
/** Creates a subregion with the specified name and RegionAttributes.
* 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.
*
* 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
* region creation constraints
* 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 Region createSubregion(String subregionName, RegionAttributes 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.
*
*This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but subregions may be added or removed while a thread is
* iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the set is required, then call
* one of the toArray methods on the set and iterate over the array.
*
* @param recursive if false, collects direct subregions only; if true,
* collects all subregions recursively
* @return a Set of subregions
*/
public Set> subregions(boolean recursive);
/** Returns the Region.Entry 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 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.
*
* For local scope, a local CacheLoader will be invoked if there is one.
* For global scope, the order is netSearch, localLoad, netLoad.
* For any other distributed scope, the order is localLoad, netSearch, netLoad.
*
* netSearch and netLoad are never performed more than once, so if a loader
* attempts to do a netSearch and one was already done, then another one will
* not be done.
*
* The value returned by get is not copied, so multi-threaded applications
* should not modify the value directly, but should use the update methods.
*
* Updates the {@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 CacheWriter throws a
* CacheWriterException when a new value is retrieved
* from a loader, the value will not be put into the cache (a new
* entry will not be created) but the get will return the value and
* not propagate the exception.
*
* @param key whose associated value is to be returned. The key Object must
* implement the equals and hashCode methods.
* @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.
*
* For local scope, a local CacheLoader will be invoked if there is one.
* For global scope, the order is netSearch, localLoad, netLoad.
* For any other distributed scope, the order is localLoad, netSearch, netLoad.
*
* netSearch and netLoad are never performed more than once, so if a loader
* attempts to do a netSearch and one was already done, then another one will
* not be done.
*
* The value returned by get is not copied, so multi-threaded applications
* should not modify the value directly, but should use the update methods.
*
* Updates the {@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 CacheWriter
* throws a CacheWriterException when
* a new value is retrieved from a loader, then the value will not be put
* into the cache (a new entry will not be created) but the get will return
* the value and not propagate the exception.
*
* @param key whose associated value is to be returned. The key Object must
* implement the equals and hashCode methods.
* @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.
* Can 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.
*
*
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 null is returned.
* If the entry was "invalid" then null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the put is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @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 CacheWriter invoked in the process.
* If there is already an entry associated with the specified key in this region,
* the entry's previous value is overwritten.
*
*
Updates the {@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 null is returned.
* If the entry was "invalid" then null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the put is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @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.
*
*
Updates the {@link CacheStatistics#getLastAccessedTime} and
* {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
*
* If this region has a distributed scope, this operation
* may cause update events in caches that already have
* this region with this entry, and it will cause create events in other caches
* that have {@link InterestPolicy#ALL all events} configured.
*
* This operation gets a distributed lock on the entry if the scope is
* Scope.GLOBAL.
*
* @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 Scope.GLOBAL
* @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 CacheWriter invoked in the process.
* If this region has a distributed scope, then the value may be updated
* subsequently if other caches update the value.
*
*
Updates the {@link CacheStatistics#getLastAccessedTime} and
* {@link CacheStatistics#getLastModifiedTime} for this region and the entry.
*
* If this region has a distributed scope, this operation
* may cause update events in caches that already have
* this region with this entry, and it will cause create events in other caches
* that have {@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 Scope.GLOBAL
* @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.
*
*
* Does not update any CacheStatistics.
*
* @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 Scope.GLOBAL
* @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 CacheListener.
* Invalidate only removes the value from the entry, the key is kept intact.
* To completely remove the entry, destroy should be used.
*
*
* Does not update any CacheStatistics.
*
* @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 Scope.GLOBAL
* @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
* @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.
*
*
* Does not update any CacheStatistics.
*
* @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 CacheListener.
* Invalidate will only remove the value from the entry, the key will be kept intact.
* In order to completely remove the key, entry and value, destroy should
* be called.
*
*
* Does not update any CacheStatistics.
*
* @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 Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @param key the key of the entry
* @return the previous value stored locally for the key.
* If the entry was "invalid" then null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the destroy is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @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 CacheWriter invoked in the process.
* Destroy removes
* not only the value but also the key and entry from this region.
* Destroy will be distributed to other caches if the scope is not
* Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @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 null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the destroy is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @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 CacheWriter is
* invoked. Destroy removes not only the value but also the key and entry
* from this region.
*
* Does not update any CacheStatistics.
*
* @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 CacheListener, if any. No CacheWriter is
* invoked. Destroy removes
* not only the value but also the key and entry from this region.
*
* Does not update any CacheStatistics.
*
* @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.
*
*
This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but keys may be added or removed to this set while a thread
* is iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the set is required, then call
* one of the toArray methods on the set and iterate over the array.
* If you need to lock down the region so this set is not modified while
* it is being accessed, use global scope with a distributed lock.
*
*@deprecated Use keySet instead;
*
* @return a Set of all the keys
*/
@Deprecated
public Set keys();
/** Returns a set of keys in the region.
*
*This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but 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 keySet();
/** Returns a Collection of values in this region.
*
*This Collection is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this collection. No ConcurrentModificationExceptions
* will be thrown, but values may be added or removed to this collection while a thread
* is iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the collection is required, then call
* one of the toArray methods on the collection and iterate over the array.
* If you need to lock down the region so this set is not modified while
* it is being accessed, use global scope with a distributed lock on the
* region.
*
*
Null values are not included in the result collection.
* @return a Collection of all the objects cached in this region
*/
public Collection values();
/** Returns the Set of Region.Entry objects in this region.
* If the recursive parameter is set to true, this call will
* recursively collect all the entries
* in this region and its subregions and return them in the Set; if false,
* it only returns entries directly contained in this region.
*
*This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but entries may be added or removed to this set while a thread
* is iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the set is required, then call
* one of the toArray methods on the set and iterate over the array.
* If you need to lock down the region so this set is not modified while
* it is being accessed, use global scope with a distributed lock.
*
* @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 entrySet(boolean recursive) instead.
* @see Region.Entry
*/
@Deprecated
public Set> entries(boolean recursive);
/** Returns the Set of Region.Entry objects in this region.
* If the recursive parameter is set to true, this call will
* recursively collect all the entries
* in this region and its subregions and return them in the Set; if false,
* it only returns entries directly contained in this region.
*
*This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but entries may be added or removed to this set while a thread
* is iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the set is required, then call
* one of the toArray methods on the set and iterate over the array.
* If you need to lock down the region so this set is not modified while
* it is being accessed, use global scope with a distributed lock.
*
* @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> entrySet(boolean recursive);
/** Returns the Cache associated with this region.
* Does not throw a CacheClosedException if the Cache is closed.
* @return the Cache
* @deprecated as of 6.5 use {@link #getRegionService()} instead.
*/
public Cache getCache();
/**
* Returns the cache associated with this region.
*
Does not throw a CacheClosedException 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.
*
*
Does not throw a RegionDestroyedException 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:
*
* Entry e = getEntry(key);
* return e != null && e.getValue() != null;
*
*
* @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 getEntry(key) != null.
*
* @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 distributed
* lock on this whole region. This region lock
* cannot be acquired until all other caches release both region locks and any
* entry locks they hold in this region. Likewise, new entry locks cannot be
* acquired until outstanding region locks are released.
* The only place that a region distributed lock is acquired automatically
* is during region creation for distributed {@link DataPolicy#withReplication replicated}
* regions when they acquire their initial data.
*
* The operations invalidateRegion and destroyRegion do not
* automatically acquire a distributed lock at all, so it is possible for these
* operations to cause an entry to be invalidated or the region to be destroyed
* even if a distributed lock is held on an entry. If an application requires
* all entry level locks to be released when a region is destroyed or
* invalidated as a whole, then it can call this method explicitly to get
* a ock on the entire region before calling invalidateRegion or destroyRegion.
*
* See
* {@link #getDistributedLock} for the list of operations that automatically
* acquire distributed entry locks for regions with global scope.
*
* Note that Region locks are potentially very expensive to acquire.
*
* @return a Lock 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 distributed
* lock on the entry with the specified key.
* Use of this Lock enables an application to synchronize
* operations on entries at a higher level than provided for by
* {@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:
*
* Lock entry1Lock = myRegion.getDistributedLock(key1);
* Lock entry2Lock = myRegion.getDistributedLock(key2);
* entry1Lock.lock();
* entry2Lock.lock();
* try {
* Object val1 = myRegion.get(key1);
* Object val2 = myRegion.get(key2);
* // do something with val1 and val2
* }
* finally {
* entry2Lock.unlock();
* entry1Lock.unlock();
* }
*
*
* You can also get a lock on an entry that does not exist in the local
* cache. Doing so guarantees that no other cache with the same
* region using global scope or using the same lock will create or update
* that entry while you have the lock.
*
* When a region has global scope, the following operations automatically
* acquire a distributed lock on an entry: create,
* put, destroy, invalidate,
* and get that causes a loader to be invoked.
* @return a Lock 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 Region
* that matches the given queryPredicate. Filters the
* values of this region using the predicate given as a string with
* the syntax of the WHERE clause of the query
* language. The predefined variable this may be used
* inside the predicate to denote the current value being filtered.
*
* @param queryPredicate
* A query language boolean query predicate.
*
* @return true if there is a value in region that
* matches the predicate, otherwise false.
*
* @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 queryPredicate.
* The queryPredicate should follow the syntax of query WHERE clause.
*
* When executed from a client, this method always runs on the server.
* However application should use QueryService to execute queries.
*
* When executed from a client, this method always runs on the server.
* However application should use QueryService to execute queries.
*
* @see Pool#getQueryService
* @see Cache#getQueryService()
*
* @param queryPredicate
* A query language boolean query predicate.
*
* @return A SelectResults containing the values of this
* Region that match the
* predicate.
*
* @throws QueryInvalidException
* If exception occurs during query compilation or processing.
*
* @see QueryService
*
* @since 4.0
*/
public SelectResults query(String queryPredicate)
throws FunctionDomainException, TypeMismatchException, NameResolutionException,
QueryInvocationTargetException;
/**
* Selects the single value in this Region that matches
* the given query predicate.
* Filters the values of this region using the predicate given as a string
* with the syntax of the where clause of the query language.
* The predefined variable this may be used inside the predicate
* to denote the element currently being filtered.
*
* @param queryPredicate
* A query language boolean query predicate.
*
* @return The single element that evaluates to true for the
* predicate. If no value in this Region
* matches the predicate, null 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 DiskAccessException saying that the disk is full will be
* thrown. If compaction is true, the application will wait for the other oplogs to be compressed and more
* space to be created.
*
* @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.
*
* Calls to this method will block until grantor authority has been
* transferred to this member.
*
* If another member later calls becomeLockGrantor, that
* member will transfer grantor authority from this member to itself.
* Multiple calls to this operation will have no effect unless another
* member has transferred grantor authority, in which case, this member will
* transfer grantor authority back to itself.
*
* This region's scope must be Scope.GLOBAL to become a lock
* grantor.
*
* This operation should not be invoked repeatedly in an application. It is
* possible to create a lock service and have two or more members endlessly
* calling becomeLockGrantor to transfer grantorship back and forth.
*
* @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 Scope.LOCAL.
*
* @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 Set of Region.Entry objects in this region.
*
*
This Set is unmodifiable. It is
* backed by this region. Synchronization is not necessary to access or
* iterate over this set. No ConcurrentModificationExceptions
* will be thrown, but entries may be added or removed to this set while a thread
* is iterating. Iterators are intended to be used by one thread at a time.
* If a stable "snapshot" view of the set is required, then call
* one of the toArray methods on the set and iterate over the array.
* If you need to lock down the region so this set is not modified while
* it is being accessed, use global scope with a distributed lock.
*
* A remove called on an entry via the iterator will result in an UnsupportedOperationException
*
* The Region.Entry obtained via the iterator is backed by the region. If a setValue on
* that entry is called, it will be similar in effect as calling a put on that key.
*
* @return a Set of all the Region.Entry instances in this region locally
* @since 5.0
* @see java.util.Map#entrySet()
*/
public Set> 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.
*
* putAll will be distributed to other caches if the scope
* is not Scope.LOCAL.
*
* @param map the entries 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 map);
/**
* Gets values for all the keys in the input Collection.
* @param keys A Collection of keys
* @return A Map of values for the input keys
*
* @since 5.7
*/
public Map getAll(Collection keys);
/**
* Removes the entry with the specified key. The operation removes
* not only the value but also the key and entry from this region.
* Remove will be distributed to other caches if the scope
* is not Scope.LOCAL.
*
* Does not update any CacheStatistics.
*
* @param key the key of the entry
* @return null is returned if an entry for key does not exist
* otherwise the value that was stored locally for the removed entry is returned.
* If the entry was "invalid" then null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the remove is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @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 Map may say that
* it is equal to an instance of Region (since Region implements Map)
* even though Region will never say that it is equal to that instance.
*
* @param other Object object to be compared against the this
* @return true 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 uses
* its full path.
* @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
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
*
This method uses the default InterestResultPolicy.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* 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.
*
* @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).
*
* 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.
*
* @param key The key on which to register interest. If the key is a
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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.
*
* Note that if the regex is ".*" then all keys of any type will be pushed to the client.
*
This method uses the default InterestResultPolicy.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* @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.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* @param regex The regular expression on which to register interest.
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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
* List, then all the keys in the List 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 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
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
* This method uses the default InterestResultPolicy.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* 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.
*
* @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.
*
* 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.
*
* @param key The key on which to register interest. If the key is a
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
* This method uses the default InterestResultPolicy.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* @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).
*
* 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.
*
* @param key The key on which to register interest. If the key is a
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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
* List, then all the keys in the List will
* be registered. The key can also be the special token 'ALL_KEYS', which
* will register interest in all keys in the region. In effect, this will
* cause an update to any key in this region in the CacheServer to be pushed
* to the client.
*
* Using 'ALL_KEYS' is the same as calling {@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.
*
* 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.
*
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* Note that if the regex is ".*" then all keys of any type will be pushed to the client.
*
This method uses the default InterestResultPolicy.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* @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.
*
* Note that if the regex is ".*" then all keys of any type will be pushed to the client.
*
This method uses the default InterestResultPolicy.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* @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.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* @param regex The regular expression on which to register interest.
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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.
*
* The regular expression string is compiled using the {@link java.util.regex.Pattern} class.
*
* If you locally-destroy a key and your region has concurrency-checks-enabled
* turned off you will not receive invalidation events from your interest subscription
* for that key. When concurrency-checks-enabled is turned on GemFire will accept
* invalidation and deliver these events to your client cache.
*
* @param regex The regular expression on which to register interest.
* @param policy The interest result policy. This can be one of:
*
* - InterestResultPolicy.NONE - does not initialize the local cache
* - InterestResultPolicy.KEYS - initializes the local cache with the
* keys satisfying the request
* - InterestResultPolicy.KEYS_VALUES - initializes the local cache with
* the keys and current values satisfying the request
*
* @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 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 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
*
* if (!map.containsKey(key))
* return map.put(key, value);
* else
* return map.get(key);
* except that the action is performed atomically.
*
*ConcurrentMap operations are supported on partitioned and replicated regions
*and in client caches. They are also supported on non-empty local regions.
*Please read the notes on ConcurrentMap operations in the javadoc for Region.
*Region allows the value parameter to be null, which will create an invalid entry.
* @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
* null if there was no mapping for the key.
* (A null return can also indicate that the map
* previously associated null with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the put 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
*
* if (map.containsKey(key) && map.get(key).equals(value)) {
* map.remove(key);
* return true;
* } else return false;
* except that the action is performed atomically.
*ConcurrentMap operations are supported on partitioned and replicated regions
*and in client caches. They are also supported on non-empty local regions.
*
Please read the notes on ConcurrentMap operations in the javadoc for Region.
*Region allows the value parameter to be null, which will match an invalid entry.
* @param key key with which the specified value is associated
* @param value value expected to be associated with the specified key
* @return true if the value was removed
* @throws UnsupportedOperationException if the remove 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
*
* if (map.containsKey(key) && map.get(key).equals(oldValue)) {
* map.put(key, newValue);
* return true;
* } else return false;
* except that the action is performed atomically.
*ConcurrentMap operations are supported on partitioned and replicated regions
*and in client caches. They are also supported on non-empty local regions.
*Please read the notes on ConcurrentMap operations in the javadoc for Region.
*Region allows the oldValue parameter to be null, which will match an invalid entry.
* @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 true if the value was replaced
* @throws UnsupportedOperationException if the replace 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
*
* if (map.containsKey(key)) {
* return map.put(key, value);
* } else return null;
* except that the action is performed atomically.
*ConcurrentMap operations are supported on partitioned and replicated regions
*and in client caches. They are also supported on non-empty local regions.
*Please read the notes on ConcurrentMap operations in the javadoc for Region.
*
* @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
* null if there was no mapping for the key.
* (A null return can also indicate that the map
* previously associated null with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the put 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
* CacheStatistics.
*
* Unless otherwise noted, all of these methods throw a
* CacheClosedException if the Cache is closed at the time of
* invocation, or an EntryDestroyedException if the entry has been
* destroyed.
*/
public interface Entry extends Map.Entry{
/** 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 CacheLoader, does not do a netSearch, netLoad, etc.
*
* @return the value or null if this entry is invalid
*/
public V getValue();
/** Returns the region that contains this entry.
*
* @return the Region that contains this entry
*/
public Region 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.
* Does not throw a EntryDestroyedException 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 null is returned.
* If the entry was "invalid" then null is returned.
* In some cases null may be returned even
* if a previous value exists.
* If the region is a client proxy then null is returned.
* If the region is partitioned and the setValue is done on a non-primary then null is returned.
* If the value is not currently stored in memory but is on disk
* and if the region does not have cqs
* then null is returned.
* @since 5.0
* @see Region#put(Object, Object)
*/
public V setValue(V value);
}
}