Class WrapperNamedCache

Wrapper for a given NamedCache.

Inheritance

object

WrapperNamedCache

Implements

INamedCache

IObservableCache

IConcurrentCache

IQueryCache

IInvocableCache

ICache

IDictionary

ICollection

IEnumerable

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Tangosol.Net.Cache

Assembly: Coherence.dll

Syntax

public class WrapperNamedCache : INamedCache, IObservableCache, IConcurrentCache, IQueryCache, IInvocableCache, ICache, IDictionary, ICollection, IEnumerable, IDisposable

Constructors

WrapperNamedCache(INamedCache)

Default constructor.

Declaration

public WrapperNamedCache(INamedCache cache)

Parameters

Type	Name	Description
INamedCache	cache	The cache to be wrapped.

Properties

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.

Count

Returns the number of key-value mappings in this cache.

Declaration

public virtual int Count { get; }

Property Value

Type	Description
int	The number of key-value mappings in this cache.

Entries

Gets a collection of ICacheEntry instances within the cache.

Declaration

public virtual ICollection Entries { get; }

Property Value

Type	Description
ICollection	A collection of ICacheEntry objects.

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.

IsFixedSize

Gets a value indicating whether the IDictionary object has a fixed size.

Declaration

public virtual bool IsFixedSize { get; }

Property Value

Type	Description
bool	Always false for this INamedCache.

IsReadOnly

Gets a value indicating whether the IDictionary object is read-only.

Declaration

public virtual bool IsReadOnly { get; }

Property Value

Type	Description
bool	Always true for this INamedCache.

IsSynchronized

Gets a value indicating whether access to the ICollection is synchronized (thread safe).

Declaration

public virtual bool IsSynchronized { get; }

Property Value

Type	Description
bool	true if access to the ICollection is synchronized (thread safe); otherwise, false.

this[object]

Returns the value to which this cache maps the specified key.

Declaration

public virtual object this[object key] { get; set; }

Parameters

Type	Name	Description
object	key	Key whose associated value is to be returned.

Property Value

Type	Description
object	The value to which this cache maps the specified key, or null if the cache contains no mapping for this key.

Remarks

Returns null if the cache contains no mapping for this key. A return value of null does not necessarily indicate that the cache contains no mapping for the key; it's also possible that the cache explicitly maps the key to null.

The Contains(object) operation may be used to distinguish these two cases.

Exceptions

Type	Condition
InvalidCastException	If the key is of an inappropriate type for this cache.
NullReferenceException	If the key is null and this cache does not permit null keys.

See Also

Contains(object)

Keys

Gets an ICollection containing the keys of the IDictionary.

Declaration

public virtual ICollection Keys { get; }

Property Value

Type	Description
ICollection	An ICollection object containing the keys of the IDictionary object.

NamedCache

Actual (wrapped) INamedCache.

Declaration

public virtual INamedCache NamedCache { get; }

Property Value

Type	Description
INamedCache	Wrapped INamedCache.

SyncRoot

Gets an object that can be used to synchronize access to this object.

Declaration

public virtual object SyncRoot { get; }

Property Value

Type	Description
object	An object that can be used to synchronize access to this object.

Values

Gets an ICollection containing the values of the IDictionary.

Declaration

public virtual ICollection Values { get; }

Property Value

Type	Description
ICollection	An ICollection object containing the values of the IDictionary object.

Methods

Add(object, object)

Adds an element with the provided key and value to the IDictionary object.

Declaration

public virtual void Add(object key, object value)

Parameters

Type	Name	Description
object	key	The object to use as the key of the element to add.
object	value	The object to use as the value of the element to add.

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

This has the same result as the following call:

AddCacheListener(listener, (IFilter) null, false);

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.

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 CacheEvent objects to select from; a CacheEvent will be delivered to the listener only if the filter evaluates to true for that CacheEvent; 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.

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.

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.

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.

Clear()

Removes all mappings from this dictionary.

Declaration

public virtual void Clear()

Remarks

Some implementations will attempt to lock the entire dictionary (if necessary) before preceeding with the clear operation. For such implementations, the entire dictionary has to be either already locked or able to be locked for this operation to succeed.

Exceptions

Type	Condition
InvalidOperationException	If the lock could not be succesfully obtained for some key.

Contains(object)

Determines whether the IDictionary contains an element with the specified key.

Declaration

public virtual bool Contains(object key)

Parameters

Type	Name	Description
object	key	The key to locate in the IDictionary.

Returns

Type	Description
bool	true if the IDictionary contains an element with the key; otherwise, false.

CopyTo(Array, int)

Copies the elements of the ICollection to an array, starting at a particular array index.

Declaration

public virtual void CopyTo(Array array, int index)

Parameters

Type	Name	Description
Array	array	The one-dimensional array that is the destination of the elements copied from ICollection.
int	index	The zero-based index in array at which copying begins.

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.

Dispose()

Calls Release() to release the resources associated with this cache.

Declaration

public void Dispose()

GetAll(ICollection)

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

Declaration

public virtual IDictionary GetAll(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	A collection of keys that may be in the named cache.

Returns

Type	Description
IDictionary	A dictionary of keys to values for the specified keys passed in keys.

Remarks

For each key that is in the cache, that key and its corresponding value will be placed in the dictionary that is returned by this method. The absence of a key in the returned dictionary 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:

IDictionary dict = new AnyDictionary();
// could be a Hashtable (but does not have to)
foreach (object key in colKeys)
{
    object value = this[key];
    if (value != null || Contains(key))
    {
        dict[key] = value;
    }
}
return dict;

GetEntries(IFilter)

Return a collectioin 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.

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.

GetEnumerator()

Returns an enumerator that iterates through cache items.

Declaration

public virtual ICacheEnumerator GetEnumerator()

Returns

Type	Description
ICacheEnumerator	An IEnumerator object that can be used to iterate through cache items.

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.

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.

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.

Insert(object, object)

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

Declaration

public virtual object Insert(object key, object value)

Parameters

Type	Name	Description
object	key	Key with which the specified value is to be associated.
object	value	Value to be associated with the specified key.

Returns

Type	Description
object	Previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the cache previously associated null with the specified key, if the implementation supports null values.

Remarks

If the cache previously contained a mapping for this key, the old value is replaced.

Invoking this method is equivalent to the following call:

Insert(key, value, CacheExpiration.Default);

Insert(object, object, long)

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

Declaration

public virtual object Insert(object key, object value, long millis)

Parameters

Type	Name	Description
object	key	Key with which the specified value is to be associated.
object	value	Value to be associated with the specified key.
long	millis	The number of milliseconds until the cache entry will expire, also referred to as the entry's "time to live"; pass DEFAULT to use the cache's default time-to-live setting; pass NEVER to indicate that the cache entry should never expire; this milliseconds value is not a date/time value, but the amount of time object will be kept in the cache.

Returns

Type	Description
object	Previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the cache previously associated null with the specified key, if the implementation supports null values.

Remarks

If the cache previously contained a mapping for this key, the old value is replaced.

This variation of the Insert(object, object) method allows the caller to specify an expiry (or "time to live") for the cache entry.

Exceptions

Type	Condition
NotSupportedException	If the requested expiry is a positive value and the implementation does not support expiry of cache entries.

InsertAll(IDictionary)

Copies all of the mappings from the specified dictionary to this cache (optional operation).

Declaration

public virtual void InsertAll(IDictionary dictionary)

Parameters

Type	Name	Description
IDictionary	dictionary	Mappings to be stored in this cache.

Remarks

These mappings will replace any mappings that this cache had for any of the keys currently in the specified dictionary.

Exceptions

Type	Condition
InvalidCastException	If the class of a key or value in the specified dictionary prevents it from being stored in this cache.
InvalidOperationException	If the lock could not be succesfully obtained for some key.
NullReferenceException	This cache does not permit null keys or values, and the specified key or value is null.

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.

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 dictionary containing the results of invoking the IEntryProcessor against each of the specified keys.

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

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

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

Passing the special constant LOCK_ALL as the key parameter to indicate the cache lock is not allowed for WrapperNamedCache and will cause an exception to be thrown.

Release()

Release local resources associated with this instance of INamedCache.

Declaration

public virtual void 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.

Remove(object)

Removes the element with the specified key from the IDictionary object.

Declaration

public virtual void Remove(object key)

Parameters

Type	Name	Description
object	key	The key of the element to remove.

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.

Remarks

This has the same result as the following call:

RemoveCacheListener(listener, (IFilter) null);

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.

ToString()

Provide a human-readable representation of this WrapperNamedCache.

Declaration

public override string ToString()

Returns

Type	Description
string	A human-readable representation of this WrapperNamedCache.

Overrides

object.ToString()

Truncate()

Removes all mappings from this instance of INamedCache.

Declaration

public virtual void Truncate()

Remarks

Note: the removal of entries caused by this truncate operation will not be observable.

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.

View()

Construct a view of this INamedCache.

Declaration

public virtual ViewBuilder View()

Returns

Type	Description
ViewBuilder	A local view for this INamedCache

Implements

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)