Class NearCache

public class NearCache : CompositeCache, ICacheStatistics, INamedCache, IObservableCache, IConcurrentCache, IQueryCache, IInvocableCache, ICache, IDictionary, ICollection, IEnumerable, IDisposable

Remarks

A CompositeCache is a cache that has a "front" cache and a "back" cache; the front cache is assumed to be low latency but incomplete, and the back cache is assumed to be complete but high latency.

Constructors

NearCache(ICache, INamedCache)

Construct a NearCache, using a backINamedCache as the complete (back) storage and frontICache as a near (front) storage using the CompositeCacheStrategyType invalidation strategy.

Declaration

public NearCache(ICache front, INamedCache back)

Parameters

Type	Name	Description
ICache	front	ICache to put in front of the back cache.
INamedCache	back	INamedCache to put behind the front cache.

NearCache(ICache, INamedCache, CompositeCacheStrategyType)

Construct a NearCache, using a backINamedCache as the complete (back) storage and frontICache as a near (front) storage using the CompositeCacheStrategyType invalidation strategy.

Declaration

public NearCache(ICache front, INamedCache back, CompositeCacheStrategyType strategy)

Parameters

Type	Name	Description
ICache	front	ICache to put in front of the back cache.
INamedCache	back	INamedCache to put behind the front cache.
CompositeCacheStrategyType	strategy	Specifies the strategy used for the front cache invalidation; valid values are: ListenNone ListenPresent ListenAll ListenAuto

Properties

BackCache

Obtain the INamedCache object that sits behind this NearCache.

Declaration

public virtual INamedCache BackCache { get; }

Property Value

Type	Description
INamedCache	The INamedCache object, which is the back cache of this NearCache.

Exceptions

Type	Condition
InvalidOperationException	If this INamedCache has been released.

CacheName

Gets the cache name.

Declaration

public virtual string CacheName { get; }

Property Value

Type	Description
string	The cache name.

CacheService

Gets the ICacheService that this INamedCache is a part of.

Declaration

public virtual ICacheService CacheService { get; }

Property Value

Type	Description
ICacheService	The cache service this INamedCache is a part of.

IsActive

Specifies whether or not the INamedCache is active.

Declaration

public virtual bool IsActive { get; }

Property Value

Type	Description
bool	true if the INamedCache is active; false otherwise.

Methods

AddCacheListener(ICacheListener)

Add a standard cache listener that will receive all events (inserts, updates, deletes) that occur against the cache, with the key, old-value and new-value included.

Declaration

public virtual void AddCacheListener(ICacheListener listener)

Parameters

Type	Name	Description
ICacheListener	listener	The ICacheListener to add.

Remarks

Expensive: Listening always occurs on the back cache.

AddCacheListener(ICacheListener, object, bool)

Add a cache listener for a specific key.

Declaration

public virtual void AddCacheListener(ICacheListener listener, object key, bool isLite)

Parameters

Type	Name	Description
ICacheListener	listener	The ICacheListener to add.
object	key	The key that identifies the entry for which to raise events.
bool	isLite	true to indicate that the CacheEventArgs objects do not have to include the OldValue and NewValue property values in order to allow optimizations.

Remarks

The listeners will receive CacheEventArgs objects, but if isLite is passed as true, they might not contain the OldValue and NewValue properties.

To unregister the ICacheListener, use the RemoveCacheListener(ICacheListener, object) method.

Expensive: Listening always occurs on the back cache.

AddCacheListener(ICacheListener, IFilter, bool)

Add a cache listener that receives events based on a filter evaluation.

Declaration

public virtual void AddCacheListener(ICacheListener listener, IFilter filter, bool isLite)

Parameters

Type	Name	Description
ICacheListener	listener	The ICacheListener to add.
IFilter	filter	A filter that will be passed CacheEventArgs objects to select from; a CacheEventArgs will be delivered to the listener only if the filter evaluates to true for that CacheEventArgs; `null` is equivalent to a filter that alway returns true.
bool	isLite	true to indicate that the CacheEventArgs objects do not have to include the OldValue and NewValue property values in order to allow optimizations.

Remarks

The listeners will receive CacheEventArgs objects, but if isLite is passed as true, they might not contain the OldValue and NewValue properties.

To unregister the ICacheListener, use the RemoveCacheListener(ICacheListener, IFilter) method.

Expensive: Listening always occurs on the back cache.

AddIndex(IValueExtractor, bool, IComparer)

Add an index to this IQueryCache.

Declaration

public virtual void AddIndex(IValueExtractor extractor, bool isOrdered, IComparer comparer)

Parameters

Type	Name	Description
IValueExtractor	extractor	The IValueExtractor object that is used to extract an indexable object from a value stored in the indexed cache. Must not be `null`.
bool	isOrdered	true if the contents of the indexed information should be ordered; false otherwise.
IComparer	comparer	The IComparer object which imposes an ordering on entries in the indexed cache; or `null` if the entries' values natural ordering should be used.

Remarks

This allows to correlate values stored in this indexed cache (or attributes of those values) to the corresponding keys in the indexed cache and increase the performance of GetKeys and GetEntries methods.

The operation always executes against the back cache.

Aggregate(ICollection, IEntryAggregator)

Perform an aggregating operation against the entries specified by the passed keys.

Declaration

public virtual object Aggregate(ICollection keys, IEntryAggregator agent)

Parameters

Type	Name	Description
ICollection	keys	The collection of keys that specify the entries within this cache to aggregate across.
IEntryAggregator	agent	The IEntryAggregator that is used to aggregate across the specified entries of this cache.

Returns

Type	Description
object	The result of the aggregation.

Remarks

The operation always executes against the back cache.

Aggregate(IFilter, IEntryAggregator)

Perform an aggregating operation against the collection of entries that are selected by the given IFilter.

Declaration

public virtual object Aggregate(IFilter filter, IEntryAggregator agent)

Parameters

Type	Name	Description
IFilter	filter	an IFilter that is used to select entries within this cache to aggregate across.
IEntryAggregator	agent	The IEntryAggregator that is used to aggregate across the selected entries of this cache.

Returns

Type	Description
object	The result of the aggregation.

Remarks

The operation always executes against the back cache.

Destroy()

Release and destroy this instance of INamedCache.

Declaration

public virtual void Destroy()

Remarks

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.

GetEntries(IFilter)

Return a collection of the entries contained in this cache that satisfy the criteria expressed by the filter.

Declaration

public virtual ICacheEntry[] GetEntries(IFilter filter)

Parameters

Type	Name	Description
IFilter	filter	The IFilter object representing the criteria that the entries of this cache should satisfy.

Returns

Type	Description
ICacheEntry[]	A collection of entries that satisfy the specified criteria.

Remarks

The operation always executes against the back cache.

GetEntries(IFilter, IComparer)

Return a collection of the entries contained in this cache that satisfy the criteria expressed by the filter.

Declaration

public virtual ICacheEntry[] GetEntries(IFilter filter, IComparer comparer)

Parameters

Type	Name	Description
IFilter	filter	The IFilter object representing the criteria that the entries of this cache should satisfy.
IComparer	comparer	The IComparable object which imposes an ordering on entries in the resulting collection; or `null` if the entries' values natural ordering should be used.

Returns

Type	Description
ICacheEntry[]	A collection of entries that satisfy the specified criteria.

Remarks

It is guaranteed that enumerator will traverse the array in such a way that the entry values come up in ascending order, sorted by the specified comparer or according to the natural ordering.

The operation always executes against the back cache.

GetKeys(IFilter)

Return a collection of the keys contained in this cache for entries that satisfy the criteria expressed by the filter.

Declaration

public virtual object[] GetKeys(IFilter filter)

Parameters

Type	Name	Description
IFilter	filter	The IFilter object representing the criteria that the entries of this cache should satisfy.

Returns

Type	Description
object[]	A collection of keys for entries that satisfy the specified criteria.

Remarks

The operation always executes against the back cache.

GetValues(IFilter)

Return a collection of the values contained in this cache for entries that satisfy the criteria expressed by the filter.

Declaration

public virtual object[] GetValues(IFilter filter)

Parameters

Type	Name	Description
IFilter	filter	The IFilter object representing the criteria that the entries of this cache should satisfy.

Returns

Type	Description
object[]	A collection of the values for entries that satisfy the specified criteria.

Remarks

The operation always executes against the back cache.

GetValues(IFilter, IComparer)

Return a collection of the values contained in this cache for entries that satisfy the criteria expressed by the filter.

Declaration

public virtual object[] GetValues(IFilter filter, IComparer comparer)

Parameters

Type	Name	Description
IFilter	filter	The IFilter object representing the criteria that the entries of this cache should satisfy.
IComparer	comparer	The IComparable object which imposes an ordering on entries in the resulting collection; or `null` if the entries' values natural ordering should be used.

Returns

Type	Description
object[]	A collection of entries that satisfy the specified criteria.

Remarks

It is guaranteed that enumerator will traverse the array in such a way that the values come up in ascending order, sorted by the specified comparer or according to the natural ordering.

The operation always executes against the back cache.

Invoke(object, IEntryProcessor)

Invoke the passed IEntryProcessor against the entry specified by the passed key, returning the result of the invocation.

Declaration

public virtual object Invoke(object key, IEntryProcessor agent)

Parameters

Type	Name	Description
object	key	The key to process; it is not required to exist within the cache.
IEntryProcessor	agent	The IEntryProcessor to use to process the specified key.

Returns

Type	Description
object	The result of the invocation as returned from the IEntryProcessor.

Remarks

The operation always executes against the back cache.

InvokeAll(ICollection, IEntryProcessor)

Invoke the passed IEntryProcessor against the entries specified by the passed keys, returning the result of the invocation for each.

Declaration

public virtual IDictionary InvokeAll(ICollection keys, IEntryProcessor agent)

Parameters

Type	Name	Description
ICollection	keys	The keys to process; these keys are not required to exist within the cache.
IEntryProcessor	agent	The IEntryProcessor to use to process the specified keys.

Returns

Type	Description
IDictionary	A cache containing the results of invoking the IEntryProcessor against each of the specified keys.

Remarks

The operation always executes against the back cache.

InvokeAll(IFilter, IEntryProcessor)

Invoke the passed IEntryProcessor against the set of entries that are selected by the given IFilter, returning the result of the invocation for each.

Declaration

public virtual IDictionary InvokeAll(IFilter filter, IEntryProcessor agent)

Parameters

Type	Name	Description
IFilter	filter	An IFilter that results in the collection of keys to be processed.
IEntryProcessor	agent	The IEntryProcessor to use to process the specified keys.

Returns

Type	Description
IDictionary	A cache containing the results of invoking the IEntryProcessor against the keys that are selected by the given IFilter.

Remarks

Unless specified otherwise, IInvocableCache implementations will perform this operation in two steps: (1) use the filter to retrieve a matching entry collection; (2) apply the agent to every filtered entry. This algorithm assumes that the agent's processing does not affect the result of the specified filter evaluation, since the filtering and processing could be performed in parallel on different threads.

If this assumption does not hold, the processor logic has to be idempotent, or at least re-evaluate the filter. This could be easily accomplished by wrapping the processor with the ConditionalProcessor.

The operation always executes against the back cache.

Lock(object)

Attempt to lock the specified item and return immediately.

Declaration

public virtual bool Lock(object key)

Parameters

Type	Name	Description
object	key	Key being locked.

Returns

Type	Description
bool	true if the item was successfully locked; false otherwise.

Remarks

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

Expensive: Locking always occurs on the back cache.

Lock(object, long)

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

Declaration

public virtual bool Lock(object key, long waitTimeMillis)

Parameters

Type	Name	Description
object	key	Key being locked.
long	waitTimeMillis	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

Type	Description
bool	true if the item was successfully locked within the specified time; false otherwise.

Remarks

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 IConcurrentCache implementation. For example, holder could be a cluster member 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 cache to be locked. If the cache 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 LOCK_ALL as the key parameter to indicate the cache lock.

Expensive: Locking always occurs on the back cache.

OnMemberJoined(object, MemberEventArgs)

Invoked when an IMember has joined the service.

Declaration

public virtual void OnMemberJoined(object sender, MemberEventArgs evt)

Parameters

Type	Name	Description
object	sender	IService that raised an event.
MemberEventArgs	evt	An event which indicates that membership has changed.

Remarks

The most critical situation arises when a number of threads are waiting for a local service restart, being blocked by a IService object synchronization monitor. Since the Joined event should be fired only once, it is called on a client thread while holding a synchronization monitor. An attempt to use other clustered service functionality during this local event notification may result in a deadlock.

OnMemberLeaving(object, MemberEventArgs)

Invoked when an IMember is leaving the service.

Declaration

public virtual void OnMemberLeaving(object sender, MemberEventArgs evt)

Parameters

Type	Name	Description
object	sender	IService that raised an event.
MemberEventArgs	evt	An event which indicates that membership has changed.

OnMemberLeft(object, MemberEventArgs)

Invoked when an IMember has left the service.

Declaration

public virtual void OnMemberLeft(object sender, MemberEventArgs evt)

Parameters

Type	Name	Description
object	sender	IService that raised an event.
MemberEventArgs	evt	An event which indicates that membership has changed.

RegisterBackServiceMemberEventHandler()

Declaration

protected virtual void RegisterBackServiceMemberEventHandler()

Remarks

The primary goal of that event handler is invalidation of the front cache in case of the service [automatic] restart.

Release()

Release local resources associated with this instance of INamedCache.

Declaration

public override void Release()

Overrides

CompositeCache.Release()

Remarks

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 afterword will result in an exception.

Release(bool)

Release this cache, optionally destroying it.

Declaration

protected virtual void Release(bool fDestroy)

Parameters

Type	Name	Description
bool	fDestroy	If true, destroy the cache as well.

RemoveCacheListener(ICacheListener)

Remove a standard cache listener that previously signed up for all events.

Declaration

public virtual void RemoveCacheListener(ICacheListener listener)

Parameters

Type	Name	Description
ICacheListener	listener	The ICacheListener to remove.

RemoveCacheListener(ICacheListener, object)

Remove a cache listener that previously signed up for events about a specific key.

Declaration

public virtual void RemoveCacheListener(ICacheListener listener, object key)

Parameters

Type	Name	Description
ICacheListener	listener	The listener to remove.
object	key	The key that identifies the entry for which to raise events.

RemoveCacheListener(ICacheListener, IFilter)

Remove a cache listener that previously signed up for events based on a filter evaluation.

Declaration

public virtual void RemoveCacheListener(ICacheListener listener, IFilter filter)

Parameters

Type	Name	Description
ICacheListener	listener	The ICacheListener to remove.
IFilter	filter	A filter used to evaluate events; `null` is equivalent to a filter that alway returns true.

RemoveIndex(IValueExtractor)

Remove an index from this IQueryCache.

Declaration

public virtual void RemoveIndex(IValueExtractor extractor)

Parameters

Type	Name	Description
IValueExtractor	extractor	The IValueExtractor object that is used to extract an indexable object from a value stored in the cache.

Remarks

The operation always executes against the back cache.

Truncate()

Remove all mappings of this instance of INamedCache.

Declaration

public virtual void Truncate()

Unlock(object)

Unlock the specified item.

Declaration

public virtual bool Unlock(object key)

Parameters

Type	Name	Description
object	key	Key being unlocked.

Returns

Type	Description
bool	true if the item was successfully unlocked; false otherwise.

Remarks

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.

UnregisterBackServiceMemberEventHandler()

Unregister back caches's service member event handler.

Declaration

protected virtual void UnregisterBackServiceMemberEventHandler()

View()

Construct a view of this INamedCache.

Declaration

public virtual ViewBuilder View()

Returns

Type	Description
ViewBuilder	A local view for this INamedCache

Implements

ICacheStatistics

INamedCache

IObservableCache

IConcurrentCache

IQueryCache

IInvocableCache

ICache

IDictionary

ICollection

IEnumerable

IDisposable

Extension Methods

InvocableCacheEx.GetOrDefault(IInvocableCache, object, object)

InvocableCacheEx.InsertIfAbsent(IInvocableCache, object, object)

InvocableCacheEx.Remove(IInvocableCache, object, object)

InvocableCacheEx.Replace(IInvocableCache, object, object)

InvocableCacheEx.Replace(IInvocableCache, object, object, object)