Class ContinuousQueryCache

Create a materialized view of an INamedCache using the Coherence Continuous Query capability.

Inheritance
object
AbstractKeyBasedCache
AbstractKeySetBasedCache
ContinuousQueryCache
Implements
Inherited Members
Namespace: Tangosol.Net.Cache
Assembly: Coherence.dll
Syntax
public class ContinuousQueryCache : AbstractKeySetBasedCache, INamedCache, IObservableCache, IConcurrentCache, IQueryCache, IInvocableCache, ICache, IDictionary, ICollection, IEnumerable, IDisposable

Constructors

ContinuousQueryCache(Func<INamedCache>)

Create a locally materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(Func<INamedCache> supplierCache)
Parameters
Type Name Description
Func<INamedCache> supplierCache

The Func returning an INamedCache with which this ContinuousQueryCache will be created.

The Func must return a new instance each time it is invoked.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor will result in a ContinuousQueryCache that caches both its keys and values locally.

ContinuousQueryCache(Func<INamedCache>, IFilter)

Create a locally materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(Func<INamedCache> supplierCache, IFilter filter)
Parameters
Type Name Description
Func<INamedCache> supplierCache

The Func returning an INamedCache with which this ContinuousQueryCache will be created.

The Func must return a new instance each time it is invoked.
IFilter filter

The filter that defines the view.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor will result in a ContinuousQueryCache that caches both its keys and values locally.

ContinuousQueryCache(Func<INamedCache>, IFilter, bool, ICacheListener, IValueExtractor)

Initialize the ContinuousQueryCache.

Declaration
public ContinuousQueryCache(Func<INamedCache> supplierCache, IFilter filter, bool cacheValues, ICacheListener cacheListener, IValueExtractor transformer)
Parameters
Type Name Description
Func<INamedCache> supplierCache

The Func returning an INamedCache with which this ContinuousQueryCache will be created.

The Func must return a new instance each time it is invoked.
IFilter filter

The filter that defines the view.
bool cacheValues

Pass true to cache both the keys and values of the materialized view locally, or false to only cache the keys.
ICacheListener cacheListener

The optional ICacheListener that will receive all events starting from the initialization of the ContinuousQueryCache.
IValueExtractor transformer

The transformer that should be used to convert values from the underlying cache before storing them locally

ContinuousQueryCache(INamedCache)

Create a locally materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(INamedCache cache)
Parameters
Type Name Description
INamedCache cache

The INamedCache to create a view of.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor will result in a ContinuousQueryCache that caches both its keys and values locally.

ContinuousQueryCache(INamedCache, IFilter)

Create a locally materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(INamedCache cache, IFilter filter)
Parameters
Type Name Description
INamedCache cache

The INamedCache to create a view of.
IFilter filter

The filter that defines the view.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor will result in a ContinuousQueryCache that caches both its keys and values locally.

ContinuousQueryCache(INamedCache, IFilter, bool)

Create a materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(INamedCache cache, IFilter filter, bool isCacheValues)
Parameters
Type Name Description
INamedCache cache

The INamedCache to create a view of.
IFilter filter

The filter that defines the view.
bool isCacheValues

Pass true to cache both the keys and values of the materialized view locally, or false to only cache the keys.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API.

ContinuousQueryCache(INamedCache, IFilter, ICacheListener)

Create a materialized view of an INamedCache using an IFilter.

Declaration
public ContinuousQueryCache(INamedCache cache, IFilter filter, ICacheListener listener)
Parameters
Type Name Description
INamedCache cache

The INamedCache to create a view of.
IFilter filter

The IFilter that defines the view.
ICacheListener listener

An initial ICacheListener that will receive all the events from the ContinuousQueryCache, including those corresponding to its initial population.
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor allows a client to receive all events, including those that result from the initial population of the ContinuousQueryCache. In other words, all contents of the ContinuousQueryCache will be delivered to the listener as a sequence of events, including those items that already exist in the underlying (unfiltered) cache. Note that this constructor will always result in both the keys and values being cached locally if a listener is passed.

ContinuousQueryCache(INamedCache, IFilter, IValueExtractor)

Create a locally materialized view of an INamedCache using an IFilter and a transformer.

Declaration
public ContinuousQueryCache(INamedCache cache, IFilter filter, IValueExtractor transformer)
Parameters
Type Name Description
INamedCache cache

The INamedCache to create a view of.
IFilter filter

The filter that defines the view.
IValueExtractor transformer

The transformer that should be used to convert values from the underlying cache before storing them locally
Remarks

A materialized view is an implementation of Continuous Query exposed through the standard INamedCache API. This constructor will result in a ContinuousQueryCache that caches both its keys and values locally.

Fields

m_connectionTimestamp

The timestamp when the synchronization was last attempted.

Declaration
protected long m_connectionTimestamp
Field Value
Type Description
long

Properties

Cache

Obtain the INamedCache that this ContinuousQueryCache is based on.

Declaration
public virtual INamedCache Cache { get; }
Property Value
Type Description
INamedCache

The underlying INamedCache.

CacheListener

Obtain the configured CacheListener for this ContinuousQueryCache

Declaration
public virtual ICacheListener CacheListener { get; }
Property Value
Type Description
ICacheListener

The CacheListener for this ContinuousQueryCache

CacheName

Gets the cache name.

Declaration
public virtual string CacheName { get; }
Property Value
Type Description
string

The cache name.

CacheNameSupplier

Return the function providing the name of this ContinuousQueryCache.

Declaration
public virtual Func<string> CacheNameSupplier { get; set; }
Property Value
Type Description
Func<string>

A function used to provide the name of this ContinuousQueryCache's.

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.

CacheValues

Obtain or modify the local-caching option for this ContinuousQueryCache.

Declaration
public virtual bool CacheValues { get; set; }
Property Value
Type Description
bool

true if this object caches values locally, and false if it relies on the underlying INamedCache.
Remarks

By changing this value from false to true, the ContinuousQueryCache will fully realize its contents locally and maintain them coherently in a manner analogous to the Coherence Near Cache. By changing this value from true to false, the ContinuousQueryCache will discard its locally cached data and rely on the underlying INamedCache.

Dispatcher

Obtain this ContinuousQueryCache's event dispatcher.

Declaration
protected virtual ContinuousQueryCache.EventDispatcher Dispatcher { get; }
Property Value
Type Description
ContinuousQueryCache.EventDispatcher

The event dispatcher that this ContinuousQueryCache uses to dispatch its events to its non-synchronous listeners.

Filter

Obtain the IFilter that this ContinuousQueryCache is using to query the underlying INamedCache.

Declaration
public virtual IFilter Filter { get; }
Property Value
Type Description
IFilter

The IFilter that this cache uses to select its contents from the underlying INamedCache.

IndexMap

The index IDictionary used by this ContinuousQueryCache.

Declaration
protected virtual IDictionary IndexMap { get; }
Property Value
Type Description
IDictionary

The IDictionary used by this ContinuousQueryCache, or null if none.

InternalCache

Obtain a reference to the internal cache.

Declaration
protected virtual IObservableCache InternalCache { get; }
Property Value
Type Description
IObservableCache

The internal cache that represents the materialized view of the ContinuousQueryCache.
Remarks

The internal cache maintains all of the keys in the ContinuousQueryCache, and if CacheValues is true, it also maintains the up-to-date values corresponding to those keys.

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.

IsCacheValues

Obtain or modify the local-caching option for this ContinuousQueryCache.

Declaration
[Obsolete("As of Coherence 3.4 this property is replaced with CacheValues")]
public virtual bool IsCacheValues { get; set; }
Property Value
Type Description
bool

true if this object caches values locally, and false if it relies on the underlying INamedCache.
Remarks

By changing this value from false to true, the ContinuousQueryCache will fully realize its contents locally and maintain them coherently in a manner analogous to the Coherence Near Cache. By changing this value from true to false, the ContinuousQueryCache will discard its locally cached data and rely on the underlying INamedCache.

IsObserved

Determine or modify if the ContinuousQueryCache has any listeners that cannot be served by this cache listening to lite events.

Declaration
public virtual bool IsObserved { get; set; }
Property Value
Type Description
bool

true iff there is at least one listener.

IsReadOnly

Obtain or modify the read-only option for the ContinuousQueryCache.

Declaration
public virtual bool IsReadOnly { get; set; }
Property Value
Type Description
bool

true if this ContinuousQueryCache has been configured as read-only.
Remarks

Note that the cache can be made read-only, but the opposite (making it mutable) is explicitly disallowed.

IsSynchronized

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

Declaration
public override bool IsSynchronized { get; }
Property Value
Type Description
bool

Always true for this cache.
Overrides

ReconnectInterval

Return a reconnection interval (in milliseconds).

Declaration
public virtual long ReconnectInterval { get; set; }
Property Value
Type Description
long

A reconnection interval (in milliseconds). The value of zero means that the ContinuousQueryCache cannot be used when not connected.
Remarks

This value indicates the period in which re-synchronization with the underlying cache will be delayed in the case the connection is severed. During this time period, local content can be accessed without triggering re-synchronization of the local content.

State

The state of the ContinuousQueryCache.

Declaration
public virtual ContinuousQueryCache.CacheState State { get; set; }
Property Value
Type Description
ContinuousQueryCache.CacheState

One of the ContinuousQueryCache.CacheState values.

Transformer

Obtain the ValueExtractor that this ContinuousQueryCache is using to transform the results from the underlying cache prior to storing them locally.

Declaration
public virtual IValueExtractor Transformer { get; }
Property Value
Type Description
IValueExtractor

The ValueExtractor that this ContinuousQueryCache is using to transform the results from the underlying cache prior to storing them locally.

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

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 thisg indexed cache (or attributes of those values) to the corresponding keys in the indexed dictionary 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 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.

CheckEntry(object, object)

Check the passed value to verify that it does belong in this ContinuousQueryCache.

Declaration
protected void CheckEntry(object key, object value)
Parameters
Type Name Description
object key

The key for the entry.
object value

The value for the entry.
Exceptions
Type Condition
ArgumentException

if the entry does not belong in this ContinuousQueryCache (based on the cache's filter).

CheckEntry(ICacheEntry)

Check the passed value to verify that it does belong in this ContinuousQueryCache.

Declaration
protected void CheckEntry(ICacheEntry entry)
Parameters
Type Name Description
ICacheEntry entry

a key/value pair to check.
Exceptions
Type Condition
ArgumentException

if the entry does not belong in this ContinuousQueryCache (based on the cache's filter).

CheckReadOnly()

Check the read-only setting to verify that the cache is NOT read-only.

Declaration
protected void CheckReadOnly()
Exceptions
Type Condition
InvalidOperationException

if the ContinuousQueryCache is read-only.

Clear()

Removes all mappings from this cache.

Declaration
public override void Clear()
Overrides
Remarks

Some implementations will attempt to lock the entire cache (if necessary) before preceeding with the clear operation. For such implementations, the entire cache 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.

ConfigureSynchronization(bool)

Set up the listeners that keep the ContinuousQueryCache up-to-date.

Declaration
protected void ConfigureSynchronization(bool reload)
Parameters
Type Name Description
bool reload

Pass true to force a data reload.

Contains(object)

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

Declaration
public override bool Contains(object key)
Parameters
Type Name Description
object key

Key whose mapping is searched for.
Returns
Type Description
bool

true if this cache contains a mapping for the specified key, false otherwise.
Overrides

CreateTransformerFilter(CacheEventFilter)

Wrap specified CacheEventFilter with a CacheEventTransformerFilter that will either transform cache value using transformer defined for this ContinuousQueryCache, or remove the old value from the event using SemiLiteEventTransformer, if no transformer is defined for this CQC.

Declaration
protected IFilter CreateTransformerFilter(CacheEventFilter filterAdd)
Parameters
Type Name Description
CacheEventFilter filterAdd

Add filter to wrap.
Returns
Type Description
IFilter

CacheEventTransformerFilter that wraps specified add filter

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

EnsureEventDispatcher()

Obtain the existing event queue or create one if none exists.

Declaration
protected virtual ContinuousQueryCache.EventDispatcher EnsureEventDispatcher()
Returns
Type Description
ContinuousQueryCache.EventDispatcher

The event dispatcher that this ContinuousQueryCache uses to dispatch its events to its non-synchronous listeners.

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.

EnsureInternalCache()

Create and initialize this 

ContinuousQueryCache
's (if not already present) internal cache. This method is called by 
ConfigureSynchronization(boolean)
, as such, it shouldn't be called directly. Use 
GetInternalCache
.

Declaration
protected IObservableCache EnsureInternalCache()
Returns
Type Description
IObservableCache

The IObservableCache functioning as this 

ContinuousQueryCache
's internal cache.

EnsureSynchronized(bool)

Ensure that the ContinousQueryCache listeners have been registered and its content synchronized with the underlying INamedCache.

Declaration
protected void EnsureSynchronized(bool reload)
Parameters
Type Name Description
bool reload

The value to pass to the ConfigureSynchronization(bool) method if the ContinousQueryCache needs to be configured and synchronized.

Get(object)

Returns the value for the specified key.

Declaration
protected override object Get(object key)
Parameters
Type Name Description
object key

Key whose value is returned.
Returns
Type Description
object

Value from the cache for the specified key.
Overrides

GetAll(ICollection)

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

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

GetInternalKeysCollection()

Obtain a collection of keys that are represented by this cache.

Declaration
protected override ICollection GetInternalKeysCollection()
Returns
Type Description
ICollection

An internal collection of keys that are contained by this cache.
Overrides
Remarks

The AbstractKeySetBasedCache only utilizes the internal keys collection as a read-only resource.

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 override 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.
Overrides
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 override 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.
Overrides
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 override void InsertAll(IDictionary dictionary)
Parameters
Type Name Description
IDictionary dictionary

Mappings to be stored in this cache.
Overrides
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.

InstantiateAddListener()

Instantiate an ICacheListener for adding items to the query, and (if there are listeners on the ContinuousQueryCache) for dispatching inserts and updates.

Declaration
protected virtual ICacheListener InstantiateAddListener()
Returns
Type Description
ICacheListener

A new ICacheListener that will add items to and update items in the ContinuousQueryCache.

InstantiateEventDispatcher()

Create a self-processing event queue dispatcher.

Declaration
protected virtual ContinuousQueryCache.EventDispatcher InstantiateEventDispatcher()
Returns
Type Description
ContinuousQueryCache.EventDispatcher

A EventDispatcher onto which events can be placed in order to be dispatched asynchronously.

InstantiateEventRouter(ICacheListener, bool)

Instantiate a listener on the internal cache that will direct events to the passed listener, either synchronously or asynchronously as appropriate.

Declaration
protected virtual ContinuousQueryCache.EventRouter InstantiateEventRouter(ICacheListener listener, bool fLite)
Parameters
Type Name Description
ICacheListener listener

The listener to route to.
bool fLite

true to indicate the the event objects passed to the listener does not have to include old or new values in order to allow optimizations.
Returns
Type Description
ContinuousQueryCache.EventRouter

A new EventRouter specific to the passed listener.

InstantiateInternalCache()

Instantiate the internal cache used by the ContinuousQueryCache.

Declaration
protected virtual IObservableCache InstantiateInternalCache()
Returns
Type Description
IObservableCache

A new IObservableMap that will represent the materialized view of the ContinuousQueryCache.

InstantiateRemoveListener()

Instantiate an ICacheListener for evicting items from the query.

Declaration
protected virtual ICacheListener InstantiateRemoveListener()
Returns
Type Description
ICacheListener

A new ICacheListener that will listen to all events that will remove items from the ContinuousQueryCache.

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.

IsEventDeferred(object)

Called when an event has occurred.

Declaration
protected bool IsEventDeferred(object key)
Parameters
Type Name Description
object key

The key that the event is related to.
Returns
Type Description
bool

true if the event processing has been deferred.
Remarks

Allows the key to be logged as requiring deferred synchronization if the event occurs during the configuration or population of the ContinuousQueryCache.

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.

MergeFilter(IFilter)

Return a filter which merges the ContinousQueueCache's filter with the supplied filter.

Declaration
protected virtual IFilter MergeFilter(IFilter filter)
Parameters
Type Name Description
IFilter filter

The IFilter to merge with this cache's filter.
Returns
Type Description
IFilter

The merged filter.

OnMemberJoined(object, MemberEventArgs)

Invoked when an IMember has joined the service.

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

Note: this event could be called during the service restart on the local node in which case the listener's code should not attempt to use any clustered cache or service functionality.

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

Note: this event could be called during the service restart on the local node in which case the listener's code should not attempt to use any clustered cache or service functionality.

RegisterDeactivationListener()

Instantiate and register a INamedCacheDeactivationListener to allow this cache to listen for cache deactivation or truncation events.

Declaration
protected void RegisterDeactivationListener()

RegisterServiceMemberEventHandler()

Register a member event handler with the underlying caches's service.

Declaration
protected void RegisterServiceMemberEventHandler()
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 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.

ReleaseIndexMap()

Release the the entire index map.

Declaration
protected void ReleaseIndexMap()

ReleaseListeners()

Release all locally registered listeners.

Declaration
protected void ReleaseListeners()

Remove(object)

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

Declaration
public override void Remove(object key)
Parameters
Type Name Description
object key

The key of the element to remove.
Overrides

RemoveBlind(object)

Removes the mapping for this key from this cache if present.

Declaration
protected override bool RemoveBlind(object key)
Parameters
Type Name Description
object key

Key whose mapping is to be removed from the cache.
Returns
Type Description
bool

true if the cache changed as the result of this operation.
Overrides
Remarks

This method exists to allow sub-types to optimize remove functionalitly for situations in which the original value is not required.

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.

ShutdownEventQueue()

Shut down running event queue.

Declaration
protected virtual void ShutdownEventQueue()

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.

UnregisterDeactivationListener()

Unregister the previously registered INamedCacheDeactivationListener.

Declaration
protected void UnregisterDeactivationListener()

UnregisterServiceMemberEventHandler()

Unregister underlying caches's service member event handler.

Declaration
protected void UnregisterServiceMemberEventHandler()

View()

Construct a view of this INamedCache.

Declaration
public virtual ViewBuilder View()
Returns
Type Description
ViewBuilder

A local view for this INamedCache

createUnexpectedStateException(CacheState, CacheState)

Simple helper to create an exception for communicating invalid state transitions.

Declaration
protected SystemException createUnexpectedStateException(ContinuousQueryCache.CacheState expectedState, ContinuousQueryCache.CacheState actualState)
Parameters
Type Name Description
ContinuousQueryCache.CacheState expectedState

expected state
ContinuousQueryCache.CacheState actualState

actual state
Returns
Type Description
SystemException

a new SystemException with a description of the invalid state transition

Implements

Extension Methods