Oracle Fusion Middleware C++ API Reference for Oracle Coherence: NearCache Class Reference

Detailed Description

CachingMap

cache

(A CachingMap is a map that has a "front" map and a "back" map; the front map is assumed to be low latency but incomplete, and the back map is assumed to be complete but high latency.)

Author:

tb 2008.07.02

Public Types

typedef spec::Handle

Handle

NearCache Handle definition.

typedef spec::View

View

NearCache View definition.

typedef spec::Holder

Holder

NearCache Holder definition.

Public Member Functions

virtual
NamedCache::Handle

getBackCache ()

Obtain the NamedCache object that sits behind this NearCache.

virtual NamedCache::View

getBackCache () const

Obtain the NamedCache object that sits behind this NearCache.

virtual String::View

getCacheName () const

Return the cache name.

Returns:: the cache name

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

isActive () const

Specifies whether or not the NamedCache is active.

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

virtual void

release ()

Release the CachingMap.

If the BackMap implements an ObservableMap calling this method is necessary to remove the BackMap listener. Any access to the CachingMap which has been released will cause IllegalStateException.

Exceptions:

IllegalStateException

if accessing the CachingMap which has been released

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 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 Map::View

getAll (Collection::View vColKeys) 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.

Note: this implementation does not differentiate between missing keys or NULL values stored in the back map; in both cases the returned map will not contain the corresponding entry.

Parameters:

vColKeys

a collection of keys that may be in the named cache

Returns:: a Map of keys to values for the specified keys passed in col

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

Protected Member Functions

NearCache (CacheMap::Handle hMapFront, CacheMap::Handle hMapBack, CachingMap::InvalidationStrategy strategy=listen_auto, ConcurrentMap::Handle hMapControl=NULL)

Construct a NearCache, using a mapBack NamedCache as the complete (back) storage and mapFront Map as a near (front) storage using the listen_auto invalidation strategy.

virtual void

onInit ()

Event called once the Object has finished being constructed.

Specifically when the first attachment is made. This provides a safe point at which Handles/Views to "this" can be created. It is not safe to create Handles/Views to an Object from within its constructor, thus any operations which rely upon this should be deferred until the onInit event is triggered.

As with all event methods any derived implementation should include a call to the super class's implementation. Specifically delegation to Object::onInit() must eventually occur or an IllegalStateException will result.

The default implementation calls the onInit() method of each of the Object's SmartMembers.

virtual
MemberListener::Handle

registerBackServiceListener ()

Instantiate and register a MemberListener with the back cache's service.

virtual void

unregisterBackServiceListener ()

Unregister back caches's service member listener.

Protected Attributes

FinalView< String >

f_vsName

Cache name.

FinalHandle
< CacheService >

f_hService

The back cache service.

FinalHandle
< MemberListener >

f_hListenerBackService

The back cache service MemberListener.

Constructor & Destructor Documentation

NearCache	(	CacheMap::Handle	hMapFront,
		CacheMap::Handle	hMapBack,
		CachingMap::InvalidationStrategy	strategy = `listen_auto`,
		ConcurrentMap::Handle	hMapControl = `NULL`
	)			`[protected]`

Construct a NearCache, using a mapBack NamedCache as the complete (back) storage and mapFront Map as a near (front) storage using the listen_auto invalidation strategy.

Parameters:

	hMapFront	map to put in front of the back cache
	hMapBack	NamedCache to put behind the front cache
	strategy	specifies the strategy used for the front map invalidation
	hMapControl	map to keep track of front map updates

Member Function Documentation

virtual NamedCache::Handle getBackCache ( ) [virtual]

Obtain the NamedCache object that sits behind this NearCache.

Returns:: the NamedCache object, which is the back map of this NearCache

Exceptions:

IllegalStateException

if this NamedCache has been released

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

Obtain the NamedCache object that sits behind this NearCache.

Returns:: the NamedCache object, which is the back map of this NearCache

Exceptions:

IllegalStateException

if this NamedCache has been released

virtual MemberListener::Handle registerBackServiceListener ( ) [protected, virtual]

Instantiate and register a MemberListener with the back cache's service.

The primary goal of that listener is invalidation of the front map in case of the service [automatic] restart.

Returns:: the instantiated and registered MemberListener object