Class LocalCache

public class LocalCache : SynchronizedDictionary, ISerializable, IConfigurableCache, IObservableCache, IConcurrentCache, IQueryCache, IInvocableCache, ICache, IDictionary, ICollection, IEnumerable

Remarks

The implementation is thread safe and uses a combination of Most Recently Used (MRU) and Most Frequently Used (MFU) caching strategies.

The cache is size-limited, which means that once it reaches its maximum size ("high-water mark") it prunes itself (to its "low-water mark"). The cache high- and low-water-marks are measured in terms of "units", and each cached item by default uses one unit. All of the cache constructors, except for the default constructor, require the maximum number of units to be passed in. To change the number of units that each cache entry uses, either set the Units property of the cache entry, or extend the ICache implementation so that the inner LocalCache.Entry class calculates its own unit size. To determine the current, high-water and low-water sizes of the cache, use the cache object's Units, HighUnits and LowUnits properties. The HighUnits and LowUnits properties can be changed, even after the cache is in use. To specify the LowUnits value as a percentage when constructing the cache, use the extended constructor taking the percentage-prune-level.

Each cached entry never expires by default. To alter this behavior, use a constructor that takes the expiry-millis; for example, an expiry-millis value of 10000 will expire entries after 10 seconds. The ExpiryDelay property can also be set once the cache is in use, but it will not affect the expiry of previously cached items.

The cache can optionally be flushed on a periodic basis by setting the FlushDelay property or scheduling a specific flush time by setting the FlushTime property.

Cache hit statistics can be obtained from the CacheHits, CacheMisses and HitProbability read-only properties. The statistics can be reset by invoking ResetHitStatistics(). The statistics are automatically reset when the cache is cleared (the Clear() method).

The LocalCache implements the IObservableCache interface, meaning it provides event notifications to any interested listener for each insert, update and delete, including those that occur when the cache is pruned or entries are automatically expired.

This implementation is designed to support extension through inheritence. To override the one-unit-per-entry default behavior, extend the inner Entry class and override the CalculateUnits(object) method.

Constructors

LocalCache()

Construct the cache manager.

Declaration

public LocalCache()

LocalCache(int)

Construct the cache manager.

Declaration

public LocalCache(int units)

Parameters

Type	Name	Description
int	units	The number of units that the cache manager will cache before pruning the cache.

LocalCache(int, int)

Construct the cache manager.

Declaration

public LocalCache(int units, int expiryMillis)

Parameters

Type	Name	Description
int	units	The number of units that the cache manager will cache before pruning the cache.
int	expiryMillis	The number of milliseconds that each cache entry lives before being automatically expired.

LocalCache(int, int, double)

Construct the cache manager.

Declaration

public LocalCache(int units, int expiryMillis, double pruneLevel)

Parameters

Type	Name	Description
int	units	The number of units that the cache manager will cache before pruning the cache.
int	expiryMillis	The number of milliseconds that each cache entry lives before being automatically expired.
double	pruneLevel	The percentage of the total number of units that will remain after the cache manager prunes the cache (i.e. this is the "low water mark" value); this value is in the range 0.0 to 1.0.

LocalCache(int, int, ICacheLoader)

Construct the cache manager.

Declaration

public LocalCache(int units, int expiryMillis, ICacheLoader loader)

Parameters

Type	Name	Description
int	units	The number of units that the cache manager will cache before pruning the cache.
int	expiryMillis	The number of milliseconds that each cache entry lives before being automatically expired.
ICacheLoader	loader	The ICacheLoader or ICacheStore to use.

Fields

DEFAULT_EXPIRE

By default, the cache entries never expire.

Declaration

public const int DEFAULT_EXPIRE = 0

Field Value

Type	Description
int

DEFAULT_FLUSH

By default, expired cache entries are flushed on a minute interval.

Declaration

public const int DEFAULT_FLUSH = 60000

Field Value

Type	Description
int

DEFAULT_KEY_MASK

The default key mask that ignores nothing.

Declaration

protected readonly LocalCache.KeyMask DEFAULT_KEY_MASK

Field Value

Type	Description
LocalCache.KeyMask

DEFAULT_PRUNE

By default, when the cache prunes, it reduces its entries by 25%, meaning it retains 75% (.75) of its entries.

Declaration

public const double DEFAULT_PRUNE = 0.75

Field Value

Type	Description
double

DEFAULT_UNITS

By default, the cache size (in units) is infinite.

Declaration

public const int DEFAULT_UNITS = 2147483647

Field Value

Type	Description
int

m_avgTouch

For a prune cycle, this value is the average number of touches that an entry should have. This value is used by the hybrid eviction policy.

Declaration

protected int m_avgTouch

Field Value

Type	Description
int

m_lastPrune

The last time that a prune was run. This value is used by the hybrid eviction policy.

Declaration

protected long m_lastPrune

Field Value

Type	Description
long

Properties

CacheHits

Gets the rough number of cache hits since the cache statistics were last reset.

Declaration

public virtual long CacheHits { get; }

Property Value

Type	Description
long	The number of this[object] calls that have been served by existing cache entries.

CacheLoader

Gets or sets the loader used by this LocalCache.

Declaration

public virtual ICacheLoader CacheLoader { get; set; }

Property Value

Type	Description
ICacheLoader	An ICacheLoader instance.

CacheMisses

Gets the rough number of cache misses since the cache statistics were last reset.

Declaration

public virtual long CacheMisses { get; }

Property Value

Type	Description
long	The number of this[object] calls that failed to find an existing cache entry because the requested key was not in the cache.

CacheStatistics

Gets the ICacheStatistics for this cache.

Declaration

public virtual ICacheStatistics CacheStatistics { get; }

Property Value

Type	Description
ICacheStatistics	An ICacheStatistics object.

CacheStore

Determine the store used by this LocalCache, if any.

Declaration

protected virtual ICacheStore CacheStore { get; }

Property Value

Type	Description
ICacheStore	The ICacheStore used by this LocalCache, or `null` if none.

CalculatorType

Gets or sets the current unit calculator type for the cache.

Declaration

public virtual LocalCache.UnitCalculatorType CalculatorType { get; set; }

Property Value

Type	Description
LocalCache.UnitCalculatorType	One of the LocalCache.UnitCalculatorType enum values.

Remarks

The type can only be set to an external unit calculator if a UnitCalculator object has been provided.

Count

Gets the number of elements contained in the ICache.

Declaration

public override int Count { get; }

Property Value

Type	Description
int	The number of elements contained in the ICache.

Overrides

SynchronizedDictionary.Count

CurrentKeyMask

Gets or sets the current key mask for the current thread.

Declaration

protected virtual LocalCache.KeyMask CurrentKeyMask { get; set; }

Property Value

Type	Description
LocalCache.KeyMask	The current key mask.

Entries

Get a collection of ICacheEntry instances within the cache.

Declaration

public virtual ICollection Entries { get; }

Property Value

Type	Description
ICollection

EvictionPolicy

Determine the current external eviction policy, if any.

Declaration

public virtual IEvictionPolicy EvictionPolicy { get; set; }

Property Value

Type	Description
IEvictionPolicy	The external eviction policy, if one has been provided.

Remarks

If null is passed, clear the external eviction policy, and use the default internal policy.

EvictionType

Gets or sets the current eviction type.

Declaration

public virtual LocalCache.EvictionPolicyType EvictionType { get; set; }

Property Value

Type	Description
LocalCache.EvictionPolicyType	One of the EvictionPolicyType enum values.

Remarks

The type can only be set to an external policy if an IEvictionPolicy object has been provided.

ExpiryDelay

Gets or sets the "time to live" for each individual cache entry.

Declaration

public virtual int ExpiryDelay { get; set; }

Property Value

Type	Description
int	The number of milliseconds that a cache entry value will live, or zero if cache entries are never automatically expired.

Remarks

This does not affect the already-scheduled expiry of existing entries.

FlushDelay

Gets or sets the delay between cache flushes.

Declaration

public virtual int FlushDelay { get; set; }

Property Value

Type	Description
int	The number of milliseconds between cache flushes, or zero which signifies that the cache never flushes

FlushTime

Gets or sets the date/time offset in milliseconds at which the next cache flush is scheduled.

Declaration

public virtual long FlushTime { get; set; }

Property Value

Type	Description
long	The date/time offset in milliseconds at which the next cache flush is scheduled.

Remarks

Note that the date/time may be long.MaxValue, which implies that a flush will never occur. Also note that the cache may internally adjust the flush time to prevent a flush from occurring during certain processing as a means to raise concurrency.

HighUnits

Gets or sets the limit of the cache size in units.

Declaration

public virtual long HighUnits { get; set; }

Property Value

Type	Description
long	The limit of the cache size in units.

Remarks

The cache will prune itself automatically once it reaches its maximum unit level. This is often referred to as the "high water mark" of the cache.

HitProbability

Gets the rough probability (0 <= p <= 1) that any particular "get" invocation will be satisfied by an existing entry in the cache, based on the statistics collected since the last reset of the cache statistics.

Declaration

public virtual double HitProbability { get; }

Property Value

Type	Description
double	The cache hit probability (0 <= p <= 1).

IndexMap

The index IDictionary used by this LocalCache.

Declaration

protected virtual IDictionary IndexMap { get; }

Property Value

Type	Description
IDictionary	The IDictionary used by this LocalCache, or `null` if none.

this[object]

Gets or sets the element with the specified key.

Declaration

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

Parameters

Type	Name	Description
object	key	The key of the element to get or set.

Property Value

Type	Description
object	The element with the specified key.

Overrides

SynchronizedDictionary.this[object]

Keys

Get the keys collection.

Declaration

public override ICollection Keys { get; }

Property Value

Type	Description
ICollection	The keys collection.

Overrides

SynchronizedDictionary.Keys

LowUnits

Gets or sets the point to which the cache will shrink when it prunes.

Declaration

public virtual long LowUnits { get; set; }

Property Value

Type	Description
long	The number of units that the cache prunes to.

Remarks

This is often referred to as a "low water mark" of the cache.

PruneLevel

The percentage of the total number of units that will remain after the cache manager prunes the cache.

Declaration

public virtual double PruneLevel { get; set; }

Property Value

Type	Description
double	The value in the range 0.0 to 1.0.

Storage

Get underlying cache storage.

Declaration

protected virtual HashDictionary Storage { get; }

Property Value

Type	Description
HashDictionary

Remarks

This property should only be used while holding a read or write lock, depending on the operation that needs to be performed against the underlying storage.

UnitCalculator

Gets or sets the current external unit calculator, if any.

Declaration

public virtual IUnitCalculator UnitCalculator { get; set; }

Property Value

Type	Description
IUnitCalculator	The external unit calculator, if one has been provided.

Remarks

If null is passed, clear the external unit calculator, and use the default unit calculator.

Units

Gets the number of units that the cache currently stores.

Declaration

public virtual long Units { get; }

Property Value

Type	Description
long	The number of units that the cache currently stores.

Values

Get the values collection.

Declaration

public override ICollection Values { get; }

Property Value

Type	Description
ICollection	The values collection.

Overrides

SynchronizedDictionary.Values

Methods

Add(object, object)

Adds an element with the provided key and value to the cache.

Declaration

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

Overrides

SynchronizedDictionary.Add(object, object)

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

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 dictionary and increase the performance of GetKeys and GetEntries methods.

AddInternal(object, object)

Add new cache entry and raise Inserted event if necessary.

Declaration

protected virtual LocalCache.Entry AddInternal(object key, object value)

Parameters

Type	Name	Description
object	key	Key to add.
object	value	Value to add.

Returns

Type	Description
LocalCache.Entry	Added entry.

Remarks

This method should only be called while holding the write lock.

AdjustUnits(int)

Adjust current size.

Declaration

protected virtual void AdjustUnits(int delta)

Parameters

Type	Name	Description
int	delta	Value that current size should be adjusted by.

Remarks

This method should only be called while holding the write lock.

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

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

Returns

Type	Description
object	The result of the aggregation.

CheckFlush()

Flush the cache if it needs to be flushed.

Declaration

protected virtual void CheckFlush()

Remarks

This method should only be called while holding the write lock.

CheckSize()

Check if the cache is too big, and if it is prune it by discarding the lowest priority cache entries.

Declaration

protected virtual void CheckSize()

Remarks

This method should only be called while holding the write lock.

Clear()

Removes all elements from the ICache object.

Declaration

public override void Clear()

Overrides

SynchronizedDictionary.Clear()

ClearInternal(bool)

Utility method to support clear and truncation operations.

Declaration

protected virtual void ClearInternal(bool fNotifyObservers)

Parameters

Type	Name	Description
bool	fNotifyObservers	true if observers should be notified, otherwise false.

ConfigureEviction(EvictionPolicyType, IEvictionPolicy)

Configure the eviction type and policy.

Declaration

protected virtual void ConfigureEviction(LocalCache.EvictionPolicyType type, IEvictionPolicy policy)

Parameters

Type	Name	Description
LocalCache.EvictionPolicyType	type	One of the LocalCache.EvictionPolicyType enum values.
IEvictionPolicy	policy	An external eviction policy, or `null`.

Remarks

This method should only be called while holding the write lock.

ConfigureUnitCalculator(UnitCalculatorType, IUnitCalculator)

Configure the unit calculator type and implementation.

Declaration

protected virtual void ConfigureUnitCalculator(LocalCache.UnitCalculatorType type, IUnitCalculator calculator)

Parameters

Type	Name	Description
LocalCache.UnitCalculatorType	type	One of the LocalCache.UnitCalculatorType enum values.
IUnitCalculator	calculator	An external unit calculator, or `null`.

Remarks

This method should only be called while holding the write lock.

Contains(object)

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

Declaration

public override bool Contains(object key)

Parameters

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

Returns

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

Overrides

SynchronizedDictionary.Contains(object)

ContainsKey(object)

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

Declaration

public virtual bool ContainsKey(object key)

Parameters

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

Returns

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

ContainsValue(object)

Determines whether the IDictionary object contains an element with the specified value.

Declaration

public virtual bool ContainsValue(object value)

Parameters

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

Returns

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

CopyTo(Array, int)

Copies the elements of the IDictionary to an Array, starting at a particular index.

Declaration

public override void CopyTo(Array array, int arrayIndex)

Parameters

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

Overrides

SynchronizedDictionary.CopyTo(Array, int)

CreateEntry(object, object)

Creates an ICacheEntry.

Declaration

protected virtual ICacheEntry CreateEntry(object key, object value)

Parameters

Type	Name	Description
object	key	Entry key.
object	value	Entry value.

Returns

Type	Description
ICacheEntry	ICacheEntry instance.

DispatchEvent(CacheEventArgs)

Dispatch the passed event.

Declaration

protected virtual void DispatchEvent(CacheEventArgs evt)

Parameters

Type	Name	Description
CacheEventArgs	evt	A CacheEventArgs object.

Remarks

This method should only be called while holding the read lock.

EnsureEntry(object)

Create a LocalCache.Entry object for the specified key.

Declaration

protected virtual IInvocableCacheEntry EnsureEntry(object key)

Parameters

Type	Name	Description
object	key	The key to create an entry for; the key is not required to exist within the cache.

Returns

Type	Description
IInvocableCacheEntry	A Entry object.

EnsureEntryCollection(ICollection)

Create an array of LocalCache.Entry objects for the specified ICache and the keys collection.

Declaration

protected virtual IInvocableCacheEntry[] EnsureEntryCollection(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	Collection of keys to create entries for; these keys are not required to exist within the cache.

Returns

Type	Description
IInvocableCacheEntry[]	An array of Entry objects.

EnsureIndexMap()

Obtain the IDictionary of indexes maintained by this cache.

Declaration

protected virtual IDictionary EnsureIndexMap()

Returns

Type	Description
IDictionary	The IDictionary of indexes maintained by this cache.

Evict()

Evict all entries from the cache that are no longer valid, and potentially prune the cache size if the cache is size-limited and its size is above the caching low water mark.

Declaration

public virtual void Evict()

Evict(object)

Evict a specified key from the cache, as if it had expired from the cache.

Declaration

public virtual void Evict(object key)

Parameters

Type	Name	Description
object	key	The key to evict from the cache.

Remarks

If the key is not in the cache, then the method has no effect.

EvictAll(ICollection)

Evict the specified keys from the cache, as if they had each expired from the cache.

Declaration

public virtual void EvictAll(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	A collection of keys to evict from the cache.

Remarks

The result of this method is defined to be semantically the same as the following implementation:

foreach (object key in keys)
{
    Evict(key);
}

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

GetCacheEntry(object)

Locate a cache entry in the cache based on its key.

Declaration

public IConfigurableCacheEntry GetCacheEntry(object key)

Parameters

Type	Name	Description
object	key	The key object to search for.

Returns

Type	Description
IConfigurableCacheEntry	The entry or null.

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.

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.

GetEntry(object)

Locate an LocalCache.Entry in the cache based on its key.

Declaration

public virtual LocalCache.Entry GetEntry(object key)

Parameters

Type	Name	Description
object	key	The key object to search for.

Returns

Type	Description
LocalCache.Entry	The Entry or `null`.

GetEntryInternal(object)

Locate an LocalCache.Entry in the cache based on its key.

Declaration

protected virtual LocalCache.Entry GetEntryInternal(object key)

Parameters

Type	Name	Description
object	key	The key object to search for.

Returns

Type	Description
LocalCache.Entry	The Entry or `null` if the entry is not found in the cache or has expired.

Remarks

If the Entry has expired, it is removed from the cache.

Unlike the GetEntry(object) method, this method does not flush the cache (if necessary) or update cache statistics.

This method should only be called while holding the write lock.

GetEnumerator()

Returns an ICacheEnumerator object for the ICache instance.

Declaration

public virtual ICacheEnumerator GetEnumerator()

Returns

Type	Description
ICacheEnumerator	An ICacheEnumerator object for the ICache instance.

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.

HasListeners()

Determine if the LocalCache has any listeners at all.

Declaration

protected virtual bool HasListeners()

Returns

Type	Description
bool	true if this LocalCache has at least one ICacheListener.

Remarks

This method should only be called while holding the read or write lock.

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 dictionary 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.
NullReferenceException	This cache does not permit `null` keys or values, and the specified key or value is `null`.

InstantiateCacheEnumerator(LocalCache, EnumeratorMode)

Factory method for cache enumerator.

Declaration

protected virtual ICacheEnumerator InstantiateCacheEnumerator(LocalCache cache, LocalCache.EnumeratorMode mode)

Parameters

Type	Name	Description
LocalCache	cache	Cache to enumerate.
LocalCache.EnumeratorMode	mode	Enumerator mode.

Returns

Type	Description
ICacheEnumerator	Cache enumerator.

InstantiateCacheEvent(CacheEventType, object, object, object)

Factory pattern: instantiate a new CacheEventArgs corresponding to the specified parameters.

Declaration

protected virtual CacheEventArgs InstantiateCacheEvent(CacheEventType type, object key, object valueOld, object valueNew)

Parameters

Type	Name	Description
CacheEventType	type	This event's type, one of CacheEventType values.
object	key	The key into the cache.
object	valueOld	The old value (for update and delete events).
object	valueNew	The new value (for insert and update events).

Returns

Type	Description
CacheEventArgs	A new instance of the CacheEventArgs class (or a subclass thereof).

InstantiateEntriesCollection(LocalCache)

Factory method that creates virtual collection of cache entries.

Declaration

protected virtual ICollection InstantiateEntriesCollection(LocalCache cache)

Parameters

Type	Name	Description
LocalCache	cache	Cache to create entries collection for.

Returns

Type	Description
ICollection	Virtual collection of cache entries.

InstantiateInternalListener()

Factory pattern: Instantiate an internal ICacheListener to listen to this cache and report changes to the ICacheStore.

Declaration

protected virtual ICacheListener InstantiateInternalListener()

Returns

Type	Description
ICacheListener	A new ICacheListener instance.

InstantiateKeysCollection(LocalCache)

Factory method that creates virtual collection of cache keys.

Declaration

protected virtual ICollection InstantiateKeysCollection(LocalCache cache)

Parameters

Type	Name	Description
LocalCache	cache	Cache to create keys collection for.

Returns

Type	Description
ICollection	Virtual collection of cache keys.

InstantiateValuesCollection(LocalCache)

Factory method that creates virtual collection of cache values.

Declaration

protected virtual ICollection InstantiateValuesCollection(LocalCache cache)

Parameters

Type	Name	Description
LocalCache	cache	Cache to create values collection for.

Returns

Type	Description
ICollection	Virtual collection of cache values.

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

IsFlushRequired()

Check if the cache needs to be flushed.

Declaration

protected virtual bool IsFlushRequired()

Returns

Type	Description
bool	true if it is time to flush the cache.

Remarks

This method should only be called while holding a read or write lock.

Load(object)

Indicates to the cache that the specified key should be loaded into the cache, if it is not already in the cache.

Declaration

public virtual void Load(object key)

Parameters

Type	Name	Description
object	key	The key to request to be loaded.

Remarks

This provides a means to "pre-load" a single entry into the cache using the cache's loader.

If a valid entry with the specified key already exists in the cache, or if the cache does not have a loader, then this method has no effect.

An implementation may perform the load operation asynchronously.

LoadAll()

Indicates to the cache that it should load data from its loader to fill the cache; this is sometimes referred to as "pre-loading" or "warming" a cache.

Declaration

public virtual void LoadAll()

Remarks

The specific set of data that will be loaded is unspecified. The implementation may choose to load all data, some specific subset of the data, or no data. An implementation may require that the loader implement the IIterableCacheLoader interface in order for this method to load any data.

An implementation may perform the load operation asynchronously.

LoadAll(ICollection)

Indicates to the cache that the specified keys should be loaded into the cache, if they are not already in the cache.

Declaration

public virtual void LoadAll(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	A collection of keys to request to be loaded.

Remarks

This provides a means to "pre-load" entries into the cache using the cache's loader.

The result of this method is defined to be semantically the same as the following implementation:

ICacheLoader loader = CacheLoader;
if (loader != null && keys.Count != 0)
{
    ArrayList requestList = new ArrayList(keys);
    CollectionUtils.RemoveAll(requestList, PeekAll(keys).Keys);
    if (requestList.Count != 0)
    {
        IDictionary dictionary = loader.LoadAll(requestList);
        if (dictionary.Count != 0)
        {
            CollectionUtils.AddAll(dictionary);
        }
    }
}

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

Peek(object)

Checks for a valid entry corresponding to the specified key in the cache, and returns the corresponding value if it is.

Declaration

public virtual object Peek(object key)

Parameters

Type	Name	Description
object	key	The key to "peek" into the cache for.

Returns

Type	Description
object	The value corresponding to the specified key.

Remarks

If it is not in the cache, returns null, and does not attempt to load the value using its cache loader.

PeekAll(ICollection)

Checks for a valid entry corresponding to each specified key in the cache, and places the corresponding value in the returned dictionary if it is.

Declaration

public virtual IDictionary PeekAll(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	A collection of keys to "peek" into the cache for.

Returns

Type	Description
IDictionary	An IDictionary of keys that were found in the cache and their values.

Remarks

For each key that is not in the cache, no entry is placed into the returned dictionary. The cache does not attempt to load any values using its cache loader.

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

IDictionary dict = new Hashtable();
foreach (object key in keys)
{
Object value = Peek(key);
if (value != null || Contains(key))
{
dict.Add(key, value);
}
}
return dict;

PeekEntryInternal(object)

Locate an LocalCache.Entry in the cache based on its key.

Declaration

protected virtual LocalCache.Entry PeekEntryInternal(object key)

Parameters

Type	Name	Description
object	key	The key object to search for.

Returns

Type	Description
LocalCache.Entry	The Entry or `null` if the entry is not found in the cache.

Remarks

Unlike the GetEntryInternal(object) method, this method does not remove expired entries from the cache.

This method should only be called while holding a read or write lock.

Prune()

Prune the cache by discarding the lowest priority cache entries.

Declaration

protected virtual void Prune()

Remarks

This method should only be called while holding the write lock.

Remove(object)

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

Declaration

public override void Remove(object key)

Parameters

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

Overrides

SynchronizedDictionary.Remove(object)

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.

RemoveExpired(Entry, bool)

Remove an entry because it has expired.

Declaration

protected virtual void RemoveExpired(LocalCache.Entry entry, bool removeInternal)

Parameters

Type	Name	Description
LocalCache.Entry	entry	The expired cache entry.
bool	removeInternal	true if the cache entry still needs to be removed from the cache.

Remarks

This method should only be called while holding the write lock.

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.

RemoveInternal(Entry, bool)

Remove an entry.

Declaration

protected virtual void RemoveInternal(LocalCache.Entry entry, bool removeInternal)

Parameters

Type	Name	Description
LocalCache.Entry	entry	The expired cache entry.
bool	removeInternal	true if the cache entry still needs to be removed from the cache.

Remarks

This method should only be called while holding the write lock.

ResetHitStatistics()

Reset the cache statistics.

Declaration

public virtual void ResetHitStatistics()

ScheduleFlush()

Schedule the next flush.

Declaration

protected virtual void ScheduleFlush()

Remarks

This method should only be called while holding the write lock.

ToString()

Returns a string representation of this LocalCache object.

Declaration

public override string ToString()

Returns

Type	Description
string	A string representation of this LocalCache object.

Overrides

object.ToString()

Truncate()

Removes all mappings from this map.

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.

Implements

ISerializable

IConfigurableCache

IObservableCache

IConcurrentCache

IQueryCache

IInvocableCache

ICache

IDictionary

ICollection

IEnumerable

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)