Oracle Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.1.2)
E26041-01

coherence::net::cache::WrapperNamedCache

WrapperNamedCache Class Reference

#include <coherence/net/cache/WrapperNamedCache.hpp>

Inherits Object, and NamedCache.

Inherited by BundlingNamedCache.

List of all members.

Detailed Description

A wrapper for the given NamedCache.

Author:: lh 2012.06.18

Since:: Coherence 12.1.2

Public Types

typedef spec::Handle Handle

WrapperNamedCache Handle definition.

typedef spec::View View

WrapperNamedCache View definition.

typedef spec::Holder Holder

WrapperNamedCache Holder definition.

Public Member Functions

virtual size32_t size () const

Return the number of key-value mappings in this map.

Returns:: the number of key-value mappings in this map.

virtual bool isEmpty () const

Return true if this map contains no key-value mappings.

Returns:: true if this map contains no key-value mappings.

virtual bool containsKey (Object::View vKey) const

Return true if this map contains a mapping for the specified key.

Parameters:

vKey

key whose presence in this map is to be tested.

Returns:: true if this map contains a mapping for the specified key.

virtual bool containsValue (Object::View vValue) const

Return true if this map maps one or more keys to the specified value.

This operation will probably require time linear in the map size for most implementations of the Map interface.

Parameters:

vValue

value whose presence in this map is to be tested.

Returns:: true if this map maps one or more keys to the specified value.

virtual Object::Holder get (Object::View vKey) const

Return the value to which this map maps the specified key.

Return NULL if the map contains no mapping for this key. A return value of NULL does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to NULL. The containsKey operation may be used to distinguish these two cases.

Parameters:

vKey

key whose associated value is to be returned.

Returns:: the value to which this map maps the specified key, or NULL if the map contains no mapping for this key.

See also:: containsKey()

virtual Object::Holder get (Object::View vKey)

Return the value to which this map maps the specified key.

Parameters:

vKey

key whose associated value is to be returned.

Returns:: the value to which this map maps the specified key, or NULL if the map contains no mapping for this key.

See also:: containsKey()

virtual Object::Holder put (Object::View vKey, Object::Holder ohValue)

Associate the specified value with the specified key in this map.

If the map previously contained a mapping for this key, the old value is replaced by the specified value.

Parameters:

	vKey	key with which the specified value is to be associated.
	ohValue	value to be associated with the specified key.

Returns:: previous value associated with specified key, or NULL if there was no mapping for key. A NULL return can also indicate that the map previously associated NULL with the specified key.

Exceptions:

coherence::lang::UnsupportedOperationException

if the put() operation is not supported by this map.

virtual Object::Holder remove (Object::View vKey)

Remove the mapping for this key from this map if it is present.

Return the value to which the map previously associated the key, or NULL if the map contained no mapping for this key. (A NULL return can also indicate that the map previously associated NULL with the specified key.) The map will not contain a mapping for the specified key once the call returns.

Parameters:

vKey

key whose mapping is to be removed from the map.

Returns:: previous value associated with specified key, or NULL if there was no mapping for key.

Exceptions:

coherence::lang::UnsupportedOperationException

if the remove() operation is not supported by this map.

virtual void putAll (Map::View vMap)

virtual void clear ()

Remove all mappings from this map.

Exceptions:

coherence::lang::UnsupportedOperationException

if the clear()operation is not supported by this map.

virtual Set::View keySet () const

Return a set of the keys contained in this map.

The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:: a set of the keys contained in this map.

virtual Set::Handle keySet ()

Return a set of the keys contained in this map.

The set is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:: a set of the keys contained in this map.

virtual Collection::View values () const

Return a collection of the values contained in this map.

The collection is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined.

Returns:: a collection of the values contained in this map.

virtual
Collection::Handle values ()

Return a collection of the values contained in this map.

The collection is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined.

Returns:: a collection of the values contained in this map.

virtual Set::View entrySet () const

Return a set of the mappings contained in this map.

Each element in the returned set is a Map::Entry::View. The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:: a set of the mappings contained in this map.

virtual Set::Handle entrySet ()

Return a set of the mappings contained in this map.

Each element in the returned set is a Map::Entry::Handle. The set is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:: a set of the mappings contained in this map.

virtual Map::View getAll (Collection::View vKeys) const

Get all the specified keys, if they are in the cache.

For each key that is in the cache, that key and its corresponding value will be placed in the map that is returned by this method. The absence of a key in the returned map indicates that it was not in the cache, which may imply (for caches that can load behind the scenes) that the requested data could not be loaded.

The result of this method is defined to be semantically the same as the following implementation, without regards to threading issues:

 // could be a HashMap (but does not have to)
 Map::Handle hMap = SomeMap::create();

 for (Iterator::Handle iter = colKeys->iterator(); iter->hasNext();)
     {
     Object::View hKey = iter->next();
     Object::View hVal = get(hKey);
     if (hVal || containsKey(hKey))
         {
         hMap->put(hKey, hVal);
         }
     }
 return hMap;

Parameters:

vKeys

a collection of keys that may be in the named cache

Returns:: a coherence::util::Map of keys to values for the specified keys passed in vKeys

virtual Object::Holder put (Object::View vKey, Object::Holder ohValue, int64_t cMillis)

Associates the specified value with the specified key in this cache.

If the cache previously contained a mapping for this key, the old value is replaced. This variation of the put(Object::View, Object::View) method allows the caller to specify an expiry (or "time to live") for the cache entry.

Parameters:

	vKey	key with which the specified value is to be associated
	ohValue	value to be associated with the specified key
	cMillis	the number of milliseconds until the cache entry will expire, also referred to as the entry's "time to live"; pass expiry_default to use the cache's default time-to-live setting; pass expiry_never to indicate that the cache entry should never expire; this milliseconds value is not a date/time value

Returns:: previous value associated with specified key, or empty handle if there was no mapping for key. An empty handle return can also indicate that the map previously associated NULL with the specified key, if the implementation supports NULL values

Exceptions:

coherence::lang::UnsupportedOperationException

if the requested expiry is a positive value and the implementation does not support expiry of cache entries

virtual void release ()

Release local resources associated with this instance of NamedCache.

Releasing a cache makes it no longer usable, but does not affect the cache itself. In other words, all other references to the cache will still be valid, and the cache data is not affected by releasing the reference. Any attempt to use this reference afterward will result in an exception.

Caches should be released by the same mechanism in which they were obtained. For example:

Cache::create() - cache->release()
CacheFactory::getCache() - CacheFactory::releaseCache()
ConfigurableCacheFactory::ensureCache() - ConfigurableCacheFactory::releaseCache()

Except for the case where the application code explicitly allocated the cache, this method should not be called by application code.

See also:: CacheFactory::releaseCache
ConfigurableCacheFactory::releaseCache

virtual void destroy ()

Release and destroy this instance of NamedCache.

Warning: This method is used to completely destroy the specified cache across the cluster. All references in the entire cluster to this cache will be invalidated, the cached data will be cleared, and all resources will be released.

Caches should be destroyed by the same mechanism in which they were obtained. For example:

Cache::create() - cache->destroy()
CacheFactory::getCache() - CacheFactory::destroyCache()
ConfigurableCacheFactory::ensureCache() - ConfigurableCacheFactory::destroyCache()

Except for the case where the application code explicitly allocated the cache, this method should not be called by application code.

See also:: CacheService::destroyCache

virtual String::View getCacheName () const

Return the cache name.

Returns:: the cache name

virtual bool isActive () const

Specifies whether or not the NamedCache is active.

Returns:: true if the NamedCache is active; false otherwise

virtual
NamedCache::CacheServiceHandle getCacheService ()

Return the CacheService that this NamedCache is a part of.

Returns:: the CacheService

virtual
NamedCache::CacheServiceView getCacheService () const

Return the CacheService that this NamedCache is a part of.

Returns:: the CacheService

virtual bool lock (Object::View vKey, int64_t cWait) const

Attempt to lock the specified item within the specified period of time.

The item doesn't have to exist to be locked. While the item is locked there is known to be a lock holder which has an exclusive right to modify (calling put and remove methods) that item.

Lock holder is an abstract concept that depends on the ConcurrentMap implementation. For example, holder could be a process or a thread (or both).

Locking strategy may vary for concrete implementations as well. Lock could have an expiration time (this lock is sometimes called a "lease") or be held indefinitely (until the lock holder terminates).

Some implementations may allow the entire map to be locked. If the map is locked in such a way, then only a lock holder is allowed to perform any of the "put" or "remove" operations. Pass the special constant getLockAll() as the vKey parameter to indicate the map lock.

Parameters:

	vKey	key being locked
	cWait	the number of milliseconds to continue trying to obtain a lock; pass zero to return immediately; pass -1 to block the calling thread until the lock could be obtained

Returns:: true if the item was successfully locked within the specified time; false otherwise

virtual bool lock (Object::View vKey) const

Attempt to lock the specified item and return immediately.

This method behaves exactly as if it simply performs the call lock(vKey, 0).

Parameters:

vKey

key being locked

Returns:: true if the item was successfully locked; false otherwise

virtual bool unlock (Object::View vKey) const

Unlock the specified item.

The item doesn't have to exist to be unlocked. If the item is currently locked, only the holder of the lock could successfully unlock it.

Parameters:

vKey

key being unlocked

Returns:: true if the item was successfully unlocked; false otherwise

virtual Object::Holder invoke (Object::View vKey, EntryProcessor::Handle hAgent)

virtual Map::View invokeAll (Collection::View vCollKeys, EntryProcessor::Handle hAgent)

virtual Map::View invokeAll (Filter::View vFilter, EntryProcessor::Handle hAgent)

virtual Object::Holder aggregate (Collection::View vCollKeys, EntryAggregator::Handle hAgent) const

virtual Object::Holder aggregate (Filter::View vFilter, EntryAggregator::Handle hAgent) const

virtual Set::View keySet (Filter::View vFilter) const

virtual Set::View entrySet (Filter::View vFilter) const

virtual Set::View entrySet (Filter::View vFilter, Comparator::View vComparator) const

virtual void addIndex (ValueExtractor::View vExtractor, bool fOrdered, Comparator::View vComparator)

virtual void removeIndex (ValueExtractor::View vExtractor)

virtual void addKeyListener (MapListener::Handle hListener, Object::View vKey, bool fLite)

virtual void removeKeyListener (MapListener::Handle hListener, Object::View vKey)

virtual void addFilterListener (MapListener::Handle hListener, Filter::View vFilter=NULL, bool fLite=false)

virtual void removeFilterListener (MapListener::Handle hListener, Filter::View vFilter=NULL)

virtual void toStream (std::ostream &out) const

Output a human-readable description of this Object to the given stream.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.

 Object::View vKey   = ...
 Object::View vValue = ...
 std::cout << vKey << " = " << vValue << std::endl;

 String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);

Parameters:

out

the stream used to output the description

virtual
NamedCache::Handle getNamedCache ()

Get the actual (wrapped) named cache.

virtual NamedCache::View getNamedCache () const

Get the actual (wrapped) named cache.

Protected Member Functions

WrapperNamedCache (NamedCache::Handle hCache)

Create a new WrapperNamedCache.

Protected Attributes

FinalHandle< NamedCache > f_hNamedCache

Actual (wrapped) NamedCache.

Constructor & Destructor Documentation

WrapperNamedCache ( NamedCache::Handle hCache ) [protected]

Create a new WrapperNamedCache.

Parameters:

hCache

the NamedCache that will be wrapped by this WrapperNamedCache

Member Function Documentation

virtual NamedCache::Handle getNamedCache ( ) [virtual]

Get the actual (wrapped) named cache.

Returns:: the wrapped cache

virtual NamedCache::View getNamedCache ( ) const [virtual]

Get the actual (wrapped) named cache.

Returns:: the wrapped cache

The documentation for this class was generated from the following file:

coherence/net/cache/WrapperNamedCache.hpp