Pivotal GemFire Native Client Cache Reference  9.0.6
gemfire::Region Class Referenceabstract

This class manages subregions and cached data. More...

Inherits gemfire::SharedBase.

Public Member Functions

virtual void clear (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes all entries from this region and provides a user-defined parameter object to any CacheWriter or CacheListener invoked in the process. More...
 
virtual bool containsKey (const CacheableKeyPtr &keyPtr) const =0
 Only the client's cache is searched for the key. More...
 
template<class KEYTYPE >
bool containsKey (const KEYTYPE &key) const
 Convenience method allowing key to be a const char* This operations checks for the key in the local cache . More...
 
virtual bool containsKeyOnServer (const CacheableKeyPtr &keyPtr) const =0
 The cache of the server, to which it is connected with, is searched for the key to see if the key is present. More...
 
virtual bool containsValueForKey (const CacheableKeyPtr &keyPtr) const =0
 This operations checks for the value in the local cache . More...
 
template<class KEYTYPE >
bool containsValueForKey (const KEYTYPE &key) const
 Convenience method allowing key to be a const char* This operations checks for the value in the local cache . More...
 
virtual void create (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 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. More...
 
template<class KEYTYPE , class VALUETYPE >
void create (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
void create (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
void create (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
virtual RegionPtr createSubregion (const char *subregionName, const RegionAttributesPtr &aRegionAttributes)=0
 Creates a subregion with the specified attributes. More...
 
virtual void destroy (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Destroys the entry with the specified key, and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE >
void destroy (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual void destroyRegion (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Destroys the whole region and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
virtual bool existsValue (const char *predicate, uint32_t timeout=DEFAULT_QUERY_RESPONSE_TIMEOUT)=0
 Executes the query on the server based on the predicate and returns whether any result exists. More...
 
virtual CacheablePtr get (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Returns the value associated with the specified key, passing the callback argument to any cache loaders that are invoked in the operation. More...
 
template<class KEYTYPE >
CacheablePtr get (const KEYTYPE &key, const UserDataPtr &callbackArg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual void getAll (const VectorOfCacheableKey &keys, HashMapOfCacheablePtr values, HashMapOfExceptionPtr exceptions, bool addToLocalCache=false, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Gets values for an array of keys from the local cache or server. More...
 
virtual RegionAttributesPtr getAttributes () const =0
 Return the RegionAttributes for this region. More...
 
virtual AttributesMutatorPtr getAttributesMutator () const =0
 Return the a mutator object for changing a subset of the region attributes. More...
 
virtual CachePtr getCache () const =0
 Returns the cache associated with this region. More...
 
virtual RegionEntryPtr getEntry (const CacheableKeyPtr &key)=0
 Return the meta-object RegionEntry for key. More...
 
template<class KEYTYPE >
RegionEntryPtr getEntry (const KEYTYPE &key)
 Convenience method allowing key to be a const char*. More...
 
virtual const char * getFullPath () const =0
 return the full path of the region as can be used to lookup the region from Cache::getRegion. More...
 
virtual void getInterestList (VectorOfCacheableKey &vlist) const =0
 Returns the list of keys on which this client is interested and will be notified of changes. More...
 
virtual void getInterestListRegex (VectorOfCacheableString &vregex) const =0
 Returns the list of regular expresssions on which this client is interested and will be notified of changes. More...
 
virtual const char * getName () const =0
 Public Methods. More...
 
virtual RegionPtr getParentRegion () const =0
 Returns the parent region, or NULLPTR if a root region. More...
 
virtual RegionServicePtr getRegionService () const =0
 Returns the cache associated with this region. More...
 
virtual RegionPtr getSubregion (const char *path)=0
 Returns the subregion identified by the path, NULLPTR if no such subregion. More...
 
virtual void invalidate (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Invalidates the entry with the specified key, and provides a user-defined argument to the CacheListener. More...
 
template<class KEYTYPE >
void invalidate (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual void invalidateRegion (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Invalidates this region. More...
 
virtual void keys (VectorOfCacheableKey &v)=0
 Return all the keys in the local process for this region. More...
 
virtual void localClear (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes all entries from this region and provides a user-defined parameter object to any CacheWriter or CacheListener invoked in the process. More...
 
virtual void localCreate (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Creates a new entry in this region with the specified key and value in the local cache only, providing a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE , class VALUETYPE >
void localCreate (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
void localCreate (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
void localCreate (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
virtual void localDestroy (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Destroys the entry with the specified key in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE >
void localDestroy (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual void localDestroyRegion (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Destroys the whole region and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
virtual void localInvalidate (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Invalidates the entry with the specified key in the local cache only, and provides a user-defined argument to the CacheListener. More...
 
template<class KEYTYPE >
void localInvalidate (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual void localInvalidateRegion (const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Invalidates this region. More...
 
virtual void localPut (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Places a new value into an entry in this region with the specified key in the local cache only, providing a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE , class VALUETYPE >
void localPut (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
void localPut (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
void localPut (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
virtual bool localRemove (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes the entry with the specified key and value in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE , class VALUETYPE >
bool localRemove (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
bool localRemove (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
bool localRemove (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
virtual bool localRemoveEx (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes the entry with the specified key in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE >
bool localRemoveEx (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
void preserveSB () const
 Atomically increment reference count. More...
 
virtual void put (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 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. More...
 
template<class KEYTYPE , class VALUETYPE >
void put (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
void put (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
void put (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
virtual void putAll (const HashMapOfCacheable &map, uint32_t timeout=15, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Places a set of new values in this region with the specified keys given as a map of key/value pairs. More...
 
virtual SelectResultsPtr query (const char *predicate, uint32_t timeout=DEFAULT_QUERY_RESPONSE_TIMEOUT)=0
 Executes the query on the server based on the predicate. More...
 
int32_t refCount ()
 
virtual void registerAllKeys (bool isDurable=false, VectorOfCacheableKeyPtr resultKeys=gemfire::NullSharedBase::s_instancePtr, bool getInitialValues=false, bool receiveValues=true)=0
 Registers to get updates for all keys from the server. More...
 
virtual void registerKeys (const VectorOfCacheableKey &keys, bool isDurable=false, bool getInitialValues=false, bool receiveValues=true)=0
 Registers an array of keys for getting updates from the server. More...
 
virtual void registerRegex (const char *regex, bool isDurable=false, VectorOfCacheableKeyPtr resultKeys=gemfire::NullSharedBase::s_instancePtr, bool getInitialValues=false, bool receiveValues=true)=0
 Registers a regular expression to match with keys to get updates from the server. More...
 
void releaseSB () const
 Atomically decrement reference count, the SharedBase object is automatically deleted when its reference count goes to zero. More...
 
virtual bool remove (const CacheableKeyPtr &key, const CacheablePtr &value, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes the entry with the specified key, value and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE , class VALUETYPE >
bool remove (const KEYTYPE &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing both key and value to be a const char*. More...
 
template<class KEYTYPE >
bool remove (const KEYTYPE &key, const CacheablePtr &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
template<class VALUETYPE >
bool remove (const CacheableKeyPtr &key, const VALUETYPE &value, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing value to be a const char*. More...
 
template<class KEYTYPE >
bool remove (const KEYTYPE &key)
 Convenience method allowing both key and value to be a const char*. More...
 
virtual void removeAll (const VectorOfCacheableKey &keys, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes all of the entries for the specified keys from this region. More...
 
virtual bool removeEx (const CacheableKeyPtr &key, const UserDataPtr &aCallbackArgument=gemfire::NullSharedBase::s_instancePtr)=0
 Removes the entry with the specified key and provides a user-defined parameter object to any CacheWriter invoked in the process. More...
 
template<class KEYTYPE >
bool removeEx (const KEYTYPE &key, const UserDataPtr &arg=gemfire::NullSharedBase::s_instancePtr)
 Convenience method allowing key to be a const char*. More...
 
virtual SerializablePtr selectValue (const char *predicate, uint32_t timeout=DEFAULT_QUERY_RESPONSE_TIMEOUT)=0
 Executes the query on the server based on the predicate and returns a single result value. More...
 
virtual void serverKeys (VectorOfCacheableKey &v)=0
 Return the set of keys defined in the server process associated to this client and region. More...
 
virtual uint32_t size ()=0
 Get the size of region. More...
 
virtual void subregions (const bool recursive, VectorOfRegion &sr)=0
 Populates the passed in VectorOfRegion with subregions of the current region. More...
 
virtual void unregisterAllKeys ()=0
 Registers to get updates for all keys from the server. More...
 
virtual void unregisterKeys (const VectorOfCacheableKey &keys)=0
 Unregisters an array of keys to stop getting updates for them. More...
 
virtual void unregisterRegex (const char *regex)=0
 Unregisters a regular expression to stop getting updates for keys from the server. More...
 
virtual void values (VectorOfCacheable &vc)=0
 Return all values in the local process for this region. More...
 

Detailed Description

This class manages subregions and cached data.

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

Entries managed by the region are key-value pairs. A set of region attributes is associated with the region when it is created.

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

Each Cache defines regions called the root regions. User applications can use the root regions 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 Region::getSubregion. You can get the relative path from the root region with Region::getFullPath. The name separator is used to concatenate all the region names together from the root, starting with the root's subregions.

See also
RegionAttributes

Member Function Documentation

virtual void gemfire::Region::clear ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

Removes all entries from this region and provides a user-defined parameter object to any CacheWriter or CacheListener invoked in the process.

See also
CacheListener::afterRegionClear
CacheWriter::beforeRegionClear
virtual bool gemfire::Region::containsKey ( const CacheableKeyPtr keyPtr) const
pure virtual

Only the client's cache is searched for the key.

It does not go to the java server to which it is connected with.

template<class KEYTYPE >
bool gemfire::Region::containsKey ( const KEYTYPE &  key) const
inline

Convenience method allowing key to be a const char* This operations checks for the key in the local cache .

It is not propagated to the Gemfire cache server to which it is connected.

virtual bool gemfire::Region::containsKeyOnServer ( const CacheableKeyPtr keyPtr) const
pure virtual

The cache of the server, to which it is connected with, is searched for the key to see if the key is present.

Exceptions
UnsupportedOperationExceptionif the region's scope is ScopeType::LOCAL.
virtual bool gemfire::Region::containsValueForKey ( const CacheableKeyPtr keyPtr) const
pure virtual

This operations checks for the value in the local cache .

It is not propagated to the Gemfire cache server to which it is connected.

template<class KEYTYPE >
bool gemfire::Region::containsValueForKey ( const KEYTYPE &  key) const
inline

Convenience method allowing key to be a const char* This operations checks for the value in the local cache .

It is not propagated to the Gemfire cache server to which it is connected.

virtual void gemfire::Region::create ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

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.

The same parameter is also passed to the CacheListener, if one is defined for this Region, invoked in the process. The new entry is propogated to the java server also to which it is connected with.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

If remote server put fails throwing back a CacheServerException or security exception, then local put is tried to rollback. However, if the entry has overflowed/evicted/expired then the rollback is aborted since it may be due to a more recent notification or update by another thread.

Parameters
keythe key smart pointer for which to create the entry in this region.
valuethe value for the new entry, which may be NULLPTR meaning the new entry starts as if it had been locally invalidated.
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. Should be serializable if passed to remote callback events
Exceptions
IllegalArgumentExceptionif key is NULLPTR or if the key, value, or aCallbackArgument do not meet serializability requirements
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
RegionDestroyedExceptionif region is no longer valid
CacheServerExceptionIf an exception is received from the Java cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif the operation timed out
OutOfMemoryExceptionif no memory for new entry
EntryExistsExceptionif an entry with this key already exists
template<class KEYTYPE , class VALUETYPE >
void gemfire::Region::create ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
void gemfire::Region::create ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
void gemfire::Region::create ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

virtual RegionPtr gemfire::Region::createSubregion ( const char *  subregionName,
const RegionAttributesPtr aRegionAttributes 
)
pure virtual

Creates a subregion with the specified attributes.

virtual void gemfire::Region::destroy ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Destroys the entry with the specified key, and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener, if one is defined for this Region, invoked in the process. Destroy removes not only the value, but also the key and entry from this region.

The destroy is propogated to the Gemfire cache server to which it is connected with. If the destroy fails due to an exception on server throwing back CacheServerException or security exception, then the local entry is still destroyed.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to destroy
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
CacheServerExceptionIf an exception is received from the Gemfire cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif the operation timed out
RegionDestroyedExceptionif the region is destroyed.
EntryNotFoundExceptionif the entry does not exist in this region.
See also
invalidate
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE >
void gemfire::Region::destroy ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual void gemfire::Region::destroyRegion ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

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 cannot be used any more. Any attempt to use this region object will get a RegionDestroyedException exception.

The region destroy not only destroys the local region but also destroys the server region. However, if server region destroy fails throwing back CacheServerException or security exception, the local region is still destroyed.

Parameters
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this call. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
CacheWriterExceptionif CacheWriter aborts the operation; if this occurs some subregions may have already been successfully destroyed.
CacheListenerExceptionif CacheListener throws an exception; if this occurs some subregions may have already been successfully invalidated
CacheServerExceptionIf an exception is received from the Java cache server. Only for Native Client regions.
NotConnectedExceptionif not connected to the gemfire system because the client cannot establish usable connections to any of the servers given to it. For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
See also
invalidateRegion
virtual bool gemfire::Region::existsValue ( const char *  predicate,
uint32_t  timeout = DEFAULT_QUERY_RESPONSE_TIMEOUT 
)
pure virtual

Executes the query on the server based on the predicate and returns whether any result exists.

Valid only for a Native Client region.

Parameters
predicateThe query predicate (just the WHERE clause) or the entire query to execute.
timeoutThe time (in seconds) to wait for the response, optional. This should be less than or equal to 2^31/1000 i.e. 2147483.
Exceptions
IllegalArgumentExceptionIf predicate is empty or timeout parameter is greater than 2^31/1000.
QueryExceptionif some query error occurred at the server.
NotConnectedExceptionif a server connection error occurs. For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when the reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
CacheClosedExceptionif the cache has been closed
Returns
true if the result size is non-zero, false otherwise.
virtual CacheablePtr gemfire::Region::get ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Returns the value associated with the specified key, passing the callback argument to any cache loaders that are invoked in the operation.

If the value is not present locally then it is requested from the java server. If even that is unsuccessful then a local CacheLoader will be invoked if there is one. The value returned by get is not copied, so multi-threaded applications should not modify the value directly, but should use the update methods.

Updates the CacheStatistics::getLastAccessedTime, CacheStatistics::getHitCount, CacheStatistics::getMissCount, and CacheStatistics::getLastModifiedTime (if a new value is loaded) for this region and the entry.

Parameters
keywhose associated value is to be returned. The key Object must implement the equals and hashCode methods.
aCallbackArgumentan argument passed into the CacheLoader if loader is used. If it is sent on the wire, it has to be Serializable.
Exceptions
IllegalArgumentExceptionif key is NULLPTR or aCallbackArgument is not serializable and a remote CacheLoader needs to be invoked
CacheLoaderExceptionif CacheLoader throws an exception
CacheServerExceptionIf an exception is received from the Java cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it. For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
RegionDestroyedExceptionif the method is called on a destroyed region
template<class KEYTYPE >
CacheablePtr gemfire::Region::get ( const KEYTYPE &  key,
const UserDataPtr callbackArg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual void gemfire::Region::getAll ( const VectorOfCacheableKey keys,
HashMapOfCacheablePtr  values,
HashMapOfExceptionPtr  exceptions,
bool  addToLocalCache = false,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Gets values for an array of keys from the local cache or server.

If value for a key is not present locally then it is requested from the java server. The value returned is not copied, so multi-threaded applications should not modify the value directly, but should use the update methods.

Updates the CacheStatistics::getLastAccessedTime, CacheStatistics::getHitCount and CacheStatistics::getMissCount for this region and the entry.

Parameters
keysthe array of keys
valuesOutput parameter that provides the map of keys to respective values. It is ignored if NULLPTR, and when NULLPTR then at least the addToLocalCache parameter should be true and caching should be enabled for the region to get values into the region otherwise an IllegalArgumentException is thrown.
exceptionsOutput parameter that provides the map of keys to any exceptions while obtaining the key. It is ignored if NULLPTR.
addToLocalCachetrue if the obtained values have also to be added to the local cache
Since
8.1
Parameters
aCallbackArgumentan argument that is passed to the callback functions. It may be NULLPTR. Must be serializable if this operation is distributed.
Exceptions
IllegalArgumentExceptionIf the array of keys is empty. Other invalid case is when the values parameter is NULLPTR, and either addToLocalCache is false or caching is disabled for this region.
CacheServerExceptionIf an exception is received from the Java cache server while processing the request.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the given servers For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
TimeoutExceptionif operation timed out.
UnknownExceptionFor other exceptions.
See also
get
virtual RegionAttributesPtr gemfire::Region::getAttributes ( ) const
pure virtual

Return the RegionAttributes for this region.

virtual AttributesMutatorPtr gemfire::Region::getAttributesMutator ( ) const
pure virtual

Return the a mutator object for changing a subset of the region attributes.

Exceptions
RegionDestroyedException.
virtual CachePtr gemfire::Region::getCache ( ) const
pure virtual

Returns the cache associated with this region.

Returns
the cache
Deprecated:
as of NativeClient 3.5, use Region#getRegionService instead.
virtual RegionEntryPtr gemfire::Region::getEntry ( const CacheableKeyPtr key)
pure virtual

Return the meta-object RegionEntry for key.

Exceptions
IllegalArgumentException,RegionDestroyedException.
template<class KEYTYPE >
RegionEntryPtr gemfire::Region::getEntry ( const KEYTYPE &  key)
inline

Convenience method allowing key to be a const char*.

virtual const char* gemfire::Region::getFullPath ( ) const
pure virtual

return the full path of the region as can be used to lookup the region from Cache::getRegion.

The storage is backed by the region.

virtual void gemfire::Region::getInterestList ( VectorOfCacheableKey vlist) const
pure virtual

Returns the list of keys on which this client is interested and will be notified of changes.

Exceptions
UnsupportedOperationExceptionif the region's scope is ScopeType::LOCAL.
virtual void gemfire::Region::getInterestListRegex ( VectorOfCacheableString vregex) const
pure virtual

Returns the list of regular expresssions on which this client is interested and will be notified of changes.

Exceptions
UnsupportedOperationExceptionif the region's scope is ScopeType::LOCAL.
virtual const char* gemfire::Region::getName ( ) const
pure virtual

Public Methods.

return single name of region. The storage is backed by the region.

virtual RegionPtr gemfire::Region::getParentRegion ( ) const
pure virtual

Returns the parent region, or NULLPTR if a root region.

Exceptions
RegionDestroyedException
virtual RegionServicePtr gemfire::Region::getRegionService ( ) const
pure virtual

Returns the cache associated with this region.

Returns
the cache
virtual RegionPtr gemfire::Region::getSubregion ( const char *  path)
pure virtual

Returns the subregion identified by the path, NULLPTR if no such subregion.

virtual void gemfire::Region::invalidate ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

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. The invalidate is not propogated to the Gemfire cache server to which it is connected with.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the value to be invalidated
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. Should be serializable if passed to remote callback events
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheListenerExceptionif CacheListener throws an exception
EntryNotFoundExceptionif this entry does not exist in this region locally
RegionDestroyedExceptionif the region is destroyed
See also
destroy
CacheListener::afterInvalidate
template<class KEYTYPE >
void gemfire::Region::invalidate ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual void gemfire::Region::invalidateRegion ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

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.

Parameters
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
CacheListenerExceptionif CacheListener throws an exception; if this occurs some subregions may have already been successfully invalidated
RegionDestroyedExceptionif the region is no longer valid
See also
destroyRegion
CacheListener::afterRegionInvalidate This operation is not distributed.
virtual void gemfire::Region::keys ( VectorOfCacheableKey v)
pure virtual

Return all the keys in the local process for this region.

This includes keys for which the entry is invalid.

virtual void gemfire::Region::localClear ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

Removes all entries from this region and provides a user-defined parameter object to any CacheWriter or CacheListener invoked in the process.

Clear will not be distributed to other caches.

See also
CacheListener::afterRegionClear
CacheWriter::beforeRegionClear
virtual void gemfire::Region::localCreate ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Creates a new entry in this region with the specified key and value in the local cache only, providing a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener, if one is defined for this Region, invoked in the process.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key smart pointer for which to create the entry in this region.
valuethe value for the new entry, which may be NULLPTR meaning the new entry starts as if it had been locally invalidated.
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. Should be serializable if passed to remote callback events
Exceptions
IllegalArgumentExceptionif key or value is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
RegionDestroyedExceptionif region is no longer valid
OutOfMemoryExceptionif no memory for new entry
EntryExistsExceptionif an entry with this key already exists
template<class KEYTYPE , class VALUETYPE >
void gemfire::Region::localCreate ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
void gemfire::Region::localCreate ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
void gemfire::Region::localCreate ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

virtual void gemfire::Region::localDestroy ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Destroys the entry with the specified key in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener, if one is defined for this Region, invoked in the process. Destroy removes not only the value but also the key and entry from this region.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to destroy.
aCallbackArgumentthe callback for user to pass in, default is NULLPTR.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
EntryNotFoundExceptionif the entry does not exist in this region locally
See also
invalidate
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE >
void gemfire::Region::localDestroy ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual void gemfire::Region::localDestroyRegion ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

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 cannot be used any more. Any attempt to use this region object will get a RegionDestroyedException exception. The region destroy is not distributed to other caches.

Parameters
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this call. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
CacheWriterExceptionif CacheWriter aborts the operation; if this occurs some subregions may have already been successfully destroyed.
CacheListenerExceptionif CacheListener throws an exception; if this occurs some subregions may have already been successfully invalidated
See also
localInvalidateRegion
virtual void gemfire::Region::localInvalidate ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

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

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the value to be invalidated
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. Should be serializable if passed to remote callback events
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheListenerExceptionif CacheListener throws an exception
EntryNotFoundExceptionif this entry does not exist in this region locally
RegionDestroyedExceptionif the region is destroyed
See also
destroy
CacheListener::afterInvalidate
template<class KEYTYPE >
void gemfire::Region::localInvalidate ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual void gemfire::Region::localInvalidateRegion ( const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr)
pure virtual

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 not be distributed to other caches

Parameters
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
CacheListenerExceptionif CacheListener throws an exception; if this occurs some subregions may have already been successfully invalidated
RegionDestroyedExceptionif the region is no longer valid
See also
destroyRegion
CacheListener::afterRegionInvalidate
virtual void gemfire::Region::localPut ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Places a new value into an entry in this region with the specified key in the local cache only, providing a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener, if one is defined for this Region, invoked in the process. If there is already an entry associated with the specified key in this region, the entry's previous value is overwritten.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keya key smart pointer associated with the value to be put into this region.
valuethe value to be put into the cache
aCallbackArgumentan argument that is passed to the callback functions
Exceptions
IllegalArgumentExceptionif key or value is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
RegionDestroyedExceptionif region no longer valid
OutOfMemoryExceptionif not enoough memory for the value
template<class KEYTYPE , class VALUETYPE >
void gemfire::Region::localPut ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
void gemfire::Region::localPut ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
void gemfire::Region::localPut ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

virtual bool gemfire::Region::localRemove ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Removes the entry with the specified key and value in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener and CacheWriter, if one is defined for this Region, invoked in the process. Remove removes not only the value but also the key and entry from this region.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to remove.
valuethe value of the entry to remove.
aCallbackArgumentthe callback for user to pass in, default is NULLPTR.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
Returns
the boolean true if an entry(key, value)has been removed or false if an entry(key, value) has not been removed.
See also
destroy
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE , class VALUETYPE >
bool gemfire::Region::localRemove ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
bool gemfire::Region::localRemove ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
bool gemfire::Region::localRemove ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

virtual bool gemfire::Region::localRemoveEx ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Removes the entry with the specified key in the local cache only, and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener and CacheWriter, if one is defined for this Region, invoked in the process. Remove removes not only the value but also the key and entry from this region.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to remove.
aCallbackArgumentthe callback for user to pass in, default is NULLPTR.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
Returns
the boolean true if an entry(key, value)has been removed or false if an entry(key, value) has not been removed.
See also
destroy
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE >
bool gemfire::Region::localRemoveEx ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

void gemfire::SharedBase::preserveSB ( ) const
inherited

Atomically increment reference count.

virtual void gemfire::Region::put ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

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.

The same parameter is also passed to the CacheListener, if one is defined for this Region, 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. The new put value is propogated to the java server to which it is connected with.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

If remote server put fails throwing back a CacheServerException or security exception, then local put is tried to rollback. However, if the entry has overflowed/evicted/expired then the rollback is aborted since it may be due to a more recent notification or update by another thread.

Parameters
keya key smart pointer associated with the value to be put into this region.
valuethe value to be put into the cache
aCallbackArgumentan argument that is passed to the callback function
Exceptions
IllegalArgumentExceptionif key or value is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
RegionDestroyedExceptionif region no longer valid
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
OutOfMemoryExceptionif not enoough memory for the value
template<class KEYTYPE , class VALUETYPE >
void gemfire::Region::put ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
void gemfire::Region::put ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
void gemfire::Region::put ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

virtual void gemfire::Region::putAll ( const HashMapOfCacheable map,
uint32_t  timeout = 15,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Places a set of new values in this region with the specified keys given as a map of key/value pairs.

If there is already an entry associated with a specified key in this region, the entry's previous value is overwritten.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entries.

Parameters
mapA hashmap containing key-value pairs
timeoutThe time (in seconds) to wait for the response, optional. This should be less than or equal to 2^31/1000 i.e. 2147483. Default is 15 (seconds).
Since
8.1
Parameters
aCallbackArgumentan argument that is passed to the callback functions. It is ignored if NULLPTR. It must be serializable if this operation is distributed.
Exceptions
IllegalArgumentExceptionIf timeout parameter is greater than 2^31/1000, ie 2147483.
virtual SelectResultsPtr gemfire::Region::query ( const char *  predicate,
uint32_t  timeout = DEFAULT_QUERY_RESPONSE_TIMEOUT 
)
pure virtual

Executes the query on the server based on the predicate.

Valid only for a Native Client region.

Parameters
predicateThe query predicate (just the WHERE clause) or the entire query to execute.
timeoutThe time (in seconds) to wait for the query response, optional. This should be less than or equal to 2^31/1000 i.e. 2147483.
Exceptions
IllegalArgumentExceptionIf predicate is empty or timeout parameter is greater than 2^31/1000.
QueryExceptionif some query error occurred at the server.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif a server connection error occurs. For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
CacheClosedExceptionif the cache has been closed
Returns
A smart pointer to the SelectResults which can either be a ResultSet or a StructSet.
int32_t gemfire::SharedBase::refCount ( )
inlineinherited
Returns
the reference count
virtual void gemfire::Region::registerAllKeys ( bool  isDurable = false,
VectorOfCacheableKeyPtr  resultKeys = gemfire::NullSharedBase::s_instancePtr,
bool  getInitialValues = false,
bool  receiveValues = true 
)
pure virtual

Registers to get updates for all keys from the server.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Parameters
isDurableflag to indicate whether this is a durable registration
resultKeysIf non-NULLPTR then all the keys on the server that got registered are returned. The vector is cleared at the start to discard any existing keys in the vector.
getInitialValuestrue to populate the cache with values of all keys from the server
receiveValueswhether to act like notify-by-subscription is set
Exceptions
EntryNotFoundExceptionIf an exception occurs while obtaining values from server after register interest is complete. The actual cause of the exception can be obtained using Exception::getCause. If an application wants to undo the registration on server, or take some other steps for the incomplete cache population then this is the exception that should be caught.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
virtual void gemfire::Region::registerKeys ( const VectorOfCacheableKey keys,
bool  isDurable = false,
bool  getInitialValues = false,
bool  receiveValues = true 
)
pure virtual

Registers an array of keys for getting updates from the server.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Parameters
keysthe array of keys
isDurableflag to indicate whether this is a durable registration
getInitialValuestrue to populate the cache with values of the keys that were registered on the server
receiveValueswhether to act like notify-by-subscription is set
Exceptions
IllegalArgumentExceptionIf the array of keys is empty.
IllegalStateExceptionIf already registered interest for all keys.
EntryNotFoundExceptionIf an exception occurs while obtaining values from server after register interest is complete. The actual cause of the exception can be obtained using Exception::getCause. If an application wants to undo the registration on server, or take some other steps for the incomplete cache population then this is the exception that should be caught.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
virtual void gemfire::Region::registerRegex ( const char *  regex,
bool  isDurable = false,
VectorOfCacheableKeyPtr  resultKeys = gemfire::NullSharedBase::s_instancePtr,
bool  getInitialValues = false,
bool  receiveValues = true 
)
pure virtual

Registers a regular expression to match with keys to get updates from the server.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Parameters
regexThe regular expression string.
isDurableflag to indicate whether this is a durable registration
resultKeysIf non-NULLPTR then the keys that match the regular expression on the server are returned. The vector is cleared at the start to discard any existing keys in the vector.
getInitialValuestrue to populate the cache with values of the keys that were registered on the server
receiveValueswhether to act like notify-by-subscription is set
Exceptions
IllegalArgumentExceptionIf regex is empty.
IllegalStateExceptionIf already registered interest for all keys.
EntryNotFoundExceptionIf an exception occurs while obtaining values from server after register interest is complete. The actual cause of the exception can be obtained using Exception::getCause. If an application wants to undo the registration on server, or take some other steps for the incomplete cache population then this is the exception that should be caught.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
void gemfire::SharedBase::releaseSB ( ) const
inherited

Atomically decrement reference count, the SharedBase object is automatically deleted when its reference count goes to zero.

virtual bool gemfire::Region::remove ( const CacheableKeyPtr key,
const CacheablePtr value,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Removes the entry with the specified key, value and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener and CacheWriter, if one is defined for this Region, invoked in the process. remove removes not only the value, but also the key and entry from this region.

The remove is propogated to the Gemfire cache server to which it is connected with. If the destroy fails due to an exception on server throwing back CacheServerException or security exception, then the local entry is still removed.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to remove
valuethe value of the key to remove, it can be NULLPTR.
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
CacheServerExceptionIf an exception is received from the Gemfire cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif the operation timed out
RegionDestroyedExceptionif the region is destroyed.
Returns
the boolean true if an entry(key, value)has been removed or false if an entry(key, value) has not been removed.
See also
destroy
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE , class VALUETYPE >
bool gemfire::Region::remove ( const KEYTYPE &  key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing both key and value to be a const char*.

template<class KEYTYPE >
bool gemfire::Region::remove ( const KEYTYPE &  key,
const CacheablePtr value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

template<class VALUETYPE >
bool gemfire::Region::remove ( const CacheableKeyPtr key,
const VALUETYPE &  value,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing value to be a const char*.

template<class KEYTYPE >
bool gemfire::Region::remove ( const KEYTYPE &  key)
inline

Convenience method allowing both key and value to be a const char*.

virtual void gemfire::Region::removeAll ( const VectorOfCacheableKey keys,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Removes all of the entries for the specified keys from this region.

The effect of this call is equivalent to that of calling destroy on this region once for each key in the specified collection. If an entry does not exist that key is skipped; EntryNotFoundException is not thrown.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entries.

Since
8.1
Parameters
keysthe keys to remove from this region.
aCallbackArgumentan argument that is passed to the callback functions. It is ignored if NULLPTR. It must be serializable if this operation is distributed.
Exceptions
IllegalArgumentExceptionIf the array of keys is empty.
CacheServerExceptionIf an exception is received from the Java cache server while processing the request.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the given servers For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
TimeoutExceptionif operation timed out.
UnknownExceptionFor other exceptions.
See also
destroy
virtual bool gemfire::Region::removeEx ( const CacheableKeyPtr key,
const UserDataPtr aCallbackArgument = gemfire::NullSharedBase::s_instancePtr 
)
pure virtual

Removes the entry with the specified key and provides a user-defined parameter object to any CacheWriter invoked in the process.

The same parameter is also passed to the CacheListener and CacheWriter, if one is defined for this Region, invoked in the process. remove removes not only the value, but also the key and entry from this region.

The remove is propogated to the Gemfire cache server to which it is connected with. If the destroy fails due to an exception on server throwing back CacheServerException or security exception, then the local entry is still removed.

Updates the CacheStatistics::getLastAccessedTime and CacheStatistics::getLastModifiedTime for this region and the entry.

Parameters
keythe key of the entry to remove
aCallbackArgumenta user-defined parameter to pass to callback events triggered by this method. Can be NULLPTR. If it is sent on the wire, it has to be Serializable.
Exceptions
IllegalArgumentExceptionif key is NULLPTR
CacheWriterExceptionif CacheWriter aborts the operation
CacheListenerExceptionif CacheListener throws an exception
CacheServerExceptionIf an exception is received from the Gemfire cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif the operation timed out
RegionDestroyedExceptionif the region is destroyed.
Returns
the boolean true if an entry(key, value)has been removed or false if an entry(key, value) has not been removed.
See also
destroy
CacheListener::afterDestroy
CacheWriter::beforeDestroy
template<class KEYTYPE >
bool gemfire::Region::removeEx ( const KEYTYPE &  key,
const UserDataPtr arg = gemfire::NullSharedBase::s_instancePtr 
)
inline

Convenience method allowing key to be a const char*.

virtual SerializablePtr gemfire::Region::selectValue ( const char *  predicate,
uint32_t  timeout = DEFAULT_QUERY_RESPONSE_TIMEOUT 
)
pure virtual

Executes the query on the server based on the predicate and returns a single result value.

Valid only for a Native Client region.

Parameters
predicateThe query predicate (just the WHERE clause) or the entire query to execute.
timeoutThe time (in seconds) to wait for the response, optional. This should be less than or equal to 2^31/1000 i.e. 2147483.
Exceptions
IllegalArgumentExceptionIf predicate is empty or timeout parameter is greater than 2^31/1000.
QueryExceptionif some query error occurred at the server, or more than one result items are available.
NotConnectedExceptionif a server connection error occurs. For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif operation timed out
CacheClosedExceptionif the cache has been closed
Returns
A smart pointer to the single ResultSet or StructSet item, or NULLPTR of no results are available.
virtual void gemfire::Region::serverKeys ( VectorOfCacheableKey v)
pure virtual

Return the set of keys defined in the server process associated to this client and region.

If a server has the region defined as a mirror, then this will be the entire keyset for the region across all PEER in the distributed system. The vector v will contain only the server keys. Any prior contents in the vector will be removed.

Exceptions
CacheServerExceptionIf an exception is received from the Gemfire cache server. Only for Native Client regions.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
MessageExceptonIf the message received from server could not be handled. This will be the case when an unregistered typeId is received in the reply or reply is not well formed. More information can be found in the log.
TimeoutExceptionif there is a timeout getting the keys
UnsupportedOperationExceptionif the member type is not CLIENT or region is not a native client one.
virtual uint32_t gemfire::Region::size ( )
pure virtual

Get the size of region.

For native client regions, this will give the number of entries in the local cache and not on the servers.

virtual void gemfire::Region::subregions ( const bool  recursive,
VectorOfRegion sr 
)
pure virtual

Populates the passed in VectorOfRegion with subregions of the current region.

Parameters
recursivedetermines whether the method recursively fills in subregions
[out]srsubregions
Exceptions
RegionDestroyedException
virtual void gemfire::Region::unregisterAllKeys ( )
pure virtual

Registers to get updates for all keys from the server.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Exceptions
IllegalStateExceptionIf not previously registered all keys.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
virtual void gemfire::Region::unregisterKeys ( const VectorOfCacheableKey keys)
pure virtual

Unregisters an array of keys to stop getting updates for them.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Parameters
keysthe array of keys
Exceptions
IllegalArgumentExceptionIf the array of keys is empty.
IllegalStateExceptionIf no keys were previously registered.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
virtual void gemfire::Region::unregisterRegex ( const char *  regex)
pure virtual

Unregisters a regular expression to stop getting updates for keys from the server.

Valid only for a Native Client region when client notification ( AttributesFactory::setClientNotification ) is true.

Parameters
regexThe regular expression string.
Exceptions
IllegalArgumentExceptionIf regex is empty.
IllegalStateExceptionIf not previously registered this regular expression string.
UnsupportedOperationExceptionIf the region is not a Native Client region or AttributesFactory::setClientNotification is false.
CacheServerExceptionIf an exception is received from the Java cache server.
NotConnectedExceptionif it is not connected to the cache because the client cannot establish usable connections to any of the servers given to it For pools configured with locators, if no locators are available, the cause of NotConnectedException is set to NoAvailableLocatorsException.
RegionDestroyedExceptionIf region destroy is pending.
UnknownExceptionFor other exceptions.
TimeoutExceptionif operation timed out
virtual void gemfire::Region::values ( VectorOfCacheable vc)
pure virtual

Return all values in the local process for this region.

No value is included for entries that are invalidated.


GemFire C++ Cache API Documentation