Class ClientCache

This class cannot be inherited.

Inheritance
System.Object
Cache
ClientCache
Inherited Members
Namespace:
Assembly: Alachisoft.NCache.Web.dll
Syntax
public sealed class ClientCache : Cache, IEnumerable, IDisposable
Remarks

One instance of this class is created per application domain, and it remains valid as long as the application domain remains active. This object is accessible through the Alachisoft.NCache.Web.Caching.NCache.Cache property of the NCache object.

ClientInfo

Declaration
public override ClientInfo ClientInfo { get; }
Property Value
Type Description
ClientInfo
Overrides

Count

Gets the number of items stored in the cache.

Declaration
public override long Count { get; }
Property Value
Type Description
System.Int64

The number of items stored in the cache.
Overrides
Remarks

This property can be useful when monitoring your application's performance or when using ASP.NET tracing functionality.

Note: In a partitioned cluster this operation is an expensive one as it might result in network calls. It is therefore advised to use this property only when required.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

ExceptionsEnabled

Flag that indicates whether exceptions are enabled or not.

Declaration
public override bool ExceptionsEnabled { get; set; }
Property Value
Type Description
System.Boolean

true if exceptions are enabled, otherwise false.
Overrides
Remarks

If this property is set the Cache object throws exceptions from public operations. If not set no exception is thrown and the operation fails silently. Setting this flag is especially helpful during development phase of application since exceptions provide more information about the specific causes of failure.

Examples

This sample shows how to set the ExceptionsEnabled property.

NCache.Cache.ExceptionsEnabled = true;

Item[String]

Gets or sets the cache item at the specified key.

Declaration
public override object this[string key] { get; set; }
Parameters
Type Name Description
System.String key

A string object that represents the key for the cache item.
Property Value
Type Description
System.Object

The specified cache item.
Overrides
Remarks

You can use this property to retrieve the value of a specified cache item, or to add an item and a key for it to the cache.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following examples demonstrates using this property to retrieve and insert the values of cached item.

void cmdReset_Click(object objSender, EventArgs objArgs)
{
    txtValue.Text = NCache.Cache[txtName.Text].ToString();
}

void cmdAdd_Click(object objSender, EventArgs objArgs)
{
    if (txtName.Text != "")
    {
        // Add this item to the cache.
        NCache.Cache[txtName.Text] = txtValue.Text;
    }
}

Or simply in a class deriving from or .

void cmdReset_Click(object objSender, EventArgs objArgs)
{
    txtValue.Text = Cache[txtName.Text].ToString();
}

void cmdAdd_Click(object objSender, EventArgs objArgs)
{
    if (txtName.Text != "")
    {
        // Add this item to the cache.
        Cache[txtName.Text] = txtValue.Text;
    }
}
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

AddAsyncOperation(String, Object, CacheDependency, CacheSyncDependency, DateTime, TimeSpan, CacheItemPriority, DSWriteOption, CacheItemRemovedCallback, CacheItemUpdatedCallback, AsyncItemAddedCallback, DataSourceItemsAddedCallback, Boolean, String, String, Tag[], String, String, NamedTagsDictionary, CacheDataNotificationCallback, CacheDataNotificationCallback, EventDataFilter, EventDataFilter, String, Int16, Int16, Int16)

This function tries to do an Add asynchronously in remote cache, if successful the operation is then done to client cache

Declaration
protected override void AddAsyncOperation(string key, object value, CacheDependency dependency, CacheSyncDependency syncDependency, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority, DSWriteOption dsWriteOption, CacheItemRemovedCallback onRemoveCallback, CacheItemUpdatedCallback onUpdateCallback, AsyncItemAddedCallback onAsyncItemAddCallback, DataSourceItemsAddedCallback onDataSourceItemAdded, bool isResyncExpiredItems, string group, string subGroup, Tag[] tags, string providerName, string resyncProviderName, NamedTagsDictionary namedTags, CacheDataNotificationCallback cacheItemUdpatedCallback, CacheDataNotificationCallback cacheItemRemovedCallaback, EventDataFilter itemUpdateDataFilter, EventDataFilter itemRemovedDataFilter, string clientId, short updateCallbackId, short removeCallbackId, short dsItemAddedCallbackId)
Parameters
Type Name Description
System.String key
System.Object value
CacheDependency dependency
CacheSyncDependency syncDependency
System.DateTime absoluteExpiration
System.TimeSpan slidingExpiration
CacheItemPriority priority
DSWriteOption dsWriteOption
CacheItemRemovedCallback onRemoveCallback
CacheItemUpdatedCallback onUpdateCallback
AsyncItemAddedCallback onAsyncItemAddCallback
DataSourceItemsAddedCallback onDataSourceItemAdded
System.Boolean isResyncExpiredItems
System.String group
System.String subGroup
Tag[] tags
System.String providerName
System.String resyncProviderName
NamedTagsDictionary namedTags
CacheDataNotificationCallback cacheItemUdpatedCallback
CacheDataNotificationCallback cacheItemRemovedCallaback
Alachisoft.NCache.Runtime.Events.EventDataFilter itemUpdateDataFilter
Alachisoft.NCache.Runtime.Events.EventDataFilter itemRemovedDataFilter
System.String clientId
System.Int16 updateCallbackId
System.Int16 removeCallbackId
System.Int16 dsItemAddedCallbackId
Overrides

AddBulk(String[], CacheItem[], DSWriteOption, DataSourceItemsAddedCallback)

Add array of CacheItem to the cache.

Declaration
public override IDictionary AddBulk(string[] keys, CacheItem[] items, DSWriteOption dsWriteOptions, DataSourceItemsAddedCallback onDataSourceItemsAdded)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the items.
CacheItem[] items

The items that are to be stored
DSWriteOption dsWriteOptions

Options regarding updating data source
DataSourceItemsAddedCallback onDataSourceItemsAdded
Returns
Type Description
System.Collections.IDictionary

keys that are added or that alredy exists in the cache and their status.
Overrides
Remarks

If CacheItem contains invalid values the related exception is thrown. See CacheItem for invalid property values and related exceptions

Examples

The following example demonstrates how to add items to the cache with an absolute expiration defined by a variable d, a sliding expiration defined by a variable t, a priority of high, and that notifies the application when the item is removed from the cache.

First create a CacheItems.

string keys = {"ORD_23", "ORD_67"};
CacheItem items = new CacheItem[2]
items[0] = new CacheItem(new Order());
items[0].AbsoluteExpiration = d;
items[0].SlidingExpiration = t;
items[0].Priority = CacheItemPriority.High;
items[0].ItemRemoveCallback = onRemove;

items[1] = new CacheItem(new Order());
items[1].AbsoluteExpiration = d;
items[1].SlidingExpiration = t;
items[1].Priority = CacheItemPriority.Low;
items[1].ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

NCache.Cache.Add(keys, items, "Customer", "Orders");

Cache.Add(keys, items, "Customer", "Orders");

AddBulk(String[], CacheItem[], DSWriteOption, String, DataSourceItemsAddedCallback)

Declaration
public override IDictionary AddBulk(string[] keys, CacheItem[] items, DSWriteOption dsWriteOptions, string providerName, DataSourceItemsAddedCallback onDataSourceItemsAdded)
Parameters
Type Name Description
System.String[] keys
CacheItem[] items
DSWriteOption dsWriteOptions
System.String providerName
DataSourceItemsAddedCallback onDataSourceItemsAdded
Returns
Type Description
System.Collections.IDictionary
Overrides

AddDependency(String, CacheDependency, Boolean)

Add dependency to the cache item.

Declaration
public override bool AddDependency(string key, CacheDependency dependency, bool isResyncRequired)
Parameters
Type Name Description
System.String key

key used to reference the required object
CacheDependency dependency

CacheDependency to be added
System.Boolean isResyncRequired

If set, then at the time of expiration, a fresh copy of the item is fetched from the master datasource provided that the read-thru is enabled. Otherwise it is expired as normal.
Returns
Type Description
System.Boolean

True if the operation successeded otherwise false
Overrides

AddDependency(String, CacheSyncDependency)

Add CacheSyncDependency to the cache item.

Declaration
public override bool AddDependency(string key, CacheSyncDependency syncDependency)
Parameters
Type Name Description
System.String key

key used to reference the required object
CacheSyncDependency syncDependency

CacheSyncDependency to be added
Returns
Type Description
System.Boolean

True if the operation successeded otherwise false
Overrides

Aggregate(IValueExtractor, IAggregator)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
Returns
Type Description
System.Object
Overrides

Aggregate(IValueExtractor, IAggregator, IKeyFilter)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator, IKeyFilter keyFilter)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
IKeyFilter keyFilter
Returns
Type Description
System.Object
Overrides

Aggregate(IValueExtractor, IAggregator, IKeyFilter, Int32)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator, IKeyFilter keyFilter, int timeout)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
IKeyFilter keyFilter
System.Int32 timeout
Returns
Type Description
System.Object
Overrides

Aggregate(IValueExtractor, IAggregator, Int32)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator, int timeout)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
System.Int32 timeout
Returns
Type Description
System.Object
Overrides

Aggregate(IValueExtractor, IAggregator, String, Hashtable)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator, string query, Hashtable parameters)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
System.String query
System.Collections.Hashtable parameters
Returns
Type Description
System.Object
Overrides

Aggregate(IValueExtractor, IAggregator, String, Hashtable, Int32)

Declaration
public override object Aggregate(IValueExtractor extractor, IAggregator aggregator, string query, Hashtable parameters, int timeout)
Parameters
Type Name Description
IValueExtractor extractor
IAggregator aggregator
System.String query
System.Collections.Hashtable parameters
System.Int32 timeout
Returns
Type Description
System.Object
Overrides

Clear(DSWriteOption, DataSourceClearedCallback)

Removes all elements from the Cache.

Declaration
public override void Clear(DSWriteOption updateOpt, DataSourceClearedCallback dataSourceClearedCallback)
Parameters
Type Name Description
DSWriteOption updateOpt

Options regarding updating data source
DataSourceClearedCallback dataSourceClearedCallback
Overrides
Remarks

In most of the cases this method's implementation is close to O(1).

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to clear the Cache.

NCache.Cache.Clear();

Or simply in a class deriving from or .

Cache.Clear();

ClearAsync(AsyncCacheClearedCallback)

Removes all elements from the Cache asynchronously.

Declaration
public override void ClearAsync(AsyncCacheClearedCallback onAsyncCacheClearCallback)
Parameters
Type Name Description
AsyncCacheClearedCallback onAsyncCacheClearCallback
Overrides
Remarks

This is similar to Clear(DSWriteOption, DataSourceClearedCallback) except that the operation is performed asynchronously. A CacheCleared event is fired upon successful completion of this method.It is not possible to determine if the actual operation has failed, therefore use this operation for the cases when it does not matter much.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

A delegate that, that can be used to get the result of the Asynchronous Clear operation. Options regarding updating data source

Examples

The following example demonstrates how to clear the Cache.

void OnAsyncCacheCleared(object result)
{
...
}

NCache.Cache.ClearAsync(new AsyncCacheClearedCallback(OnAsyncCacheCleared));

Or simply in a class deriving from or .

Cache.ClearAsync(new AsyncCacheClearedCallback(OnAsyncCacheCleared));

ClearAsync(DSWriteOption, AsyncCacheClearedCallback, DataSourceClearedCallback)

Declaration
public override void ClearAsync(DSWriteOption updateOpt, AsyncCacheClearedCallback onAsyncCacheClearCallback, DataSourceClearedCallback dataSourceClearedCallback)
Parameters
Type Name Description
DSWriteOption updateOpt
AsyncCacheClearedCallback onAsyncCacheClearCallback
DataSourceClearedCallback dataSourceClearedCallback
Overrides

ClearClientCache()

Declaration
public override void ClearClientCache()
Overrides

ClearClientCacheAsync(AsyncCacheClearedCallback)

Removes all elements from the client cache asynchronously.

Declaration
public override void ClearClientCacheAsync(AsyncCacheClearedCallback onAsyncCacheClearCallback)
Parameters
Type Name Description
AsyncCacheClearedCallback onAsyncCacheClearCallback
Overrides
Remarks

This is similar to ClearClientCache except that the operation is performed asynchronously. A CacheCleared event is fired upon successful completion of this method.It is not possible to determine if the actual operation has failed, therefore use this operation for the cases when it does not matter much. A delegate that, that can be used to get the result of the Asynchronous Clear operation.

Examples

The following example demonstrates how to clear the client cache.

void OnAsyncCacheCleared(object result)
{
...
}

NCache.Cache.ClearClientCacheAsync(new AsyncCacheClearedCallback(OnAsyncCacheCleared));

Or simply in a class deriving from or .

Cache.ClearClientCacheAsync(new AsyncCacheClearedCallback(OnAsyncCacheCleared));

Contains(String)

Determines whether the cache contains a specific key.

Declaration
public override bool Contains(string key)
Parameters
Type Name Description
System.String key

The key to locate in the Cache.
Returns
Type Description
System.Boolean

true if the Cache contains an element with the specified key; otherwise, false.
Overrides
Remarks

In most of the cases this method's implementation is close to O(1).

Note: In a partitioned cluster this operation is an expensive one as it might result in network calls. It is therefore advised to use this property only when required.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to check for containment of an item in the Cache.

if(NCache.Cache.Contains("MyTextBox.Value"))
{
    Response.Write("Item found!");
}

Or simply in a class deriving from or .

if(Cache.Contains("MyTextBox.Value"))
{
    Response.Write("Item found!");
}
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

Delete(String, CacheItemVersion)

Declaration
public override void Delete(string key, CacheItemVersion version)
Parameters
Type Name Description
System.String key
CacheItemVersion version
Overrides

Delete(String, DSWriteOption, DataSourceItemsRemovedCallback)

Removes the object from the Cache.

Declaration
public override void Delete(string key, DSWriteOption dsWriteOption, DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
DSWriteOption dsWriteOption

Options regarding updating the data source.
DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback

A delegate that, if provided, is called when item is removed from data source.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

Cache cache = NCache.InitializeCache("myCache");
cache.Remove("timestamp", DSWriteOption.None, new DataSourceItemsRemovedCallback(OnDataSourceItemsRemoved));
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

Delete(String, DSWriteOption, String, DataSourceItemsRemovedCallback)

Declaration
public override void Delete(string key, DSWriteOption dsWriteOption, string providerName, DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback)
Parameters
Type Name Description
System.String key
DSWriteOption dsWriteOption
System.String providerName
DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback
Overrides

Delete(String, LockHandle)

Declaration
public override void Delete(string key, LockHandle lockHandle)
Parameters
Type Name Description
System.String key
LockHandle lockHandle
Overrides

DeleteBulk(String[], DSWriteOption, DataSourceItemsRemovedCallback)

Removes the objects from the Cache.

Declaration
public override void DeleteBulk(string[] keys, DSWriteOption dsWriteOption, DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the item.
DSWriteOption dsWriteOption

Options regarding updating data source
DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback

A delegate that, if provided, is called when item is removed from data source.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

OnDataSourceItemsRemoved(IDictionary result)
{
...
}
Cache cache = NCache.InitializeCache("myCache");
string[] keys = new string[]{"myItem1", "myItem2"};
cache.DeleteBulk(keys, DSWriteOption.WriteBehind, new DataSourceItemsRemovedCallback(OnDataSourceItemsRemoved));
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

DeleteBulk(String[], DSWriteOption, String, DataSourceItemsRemovedCallback)

Removes the objects from the Cache.

Declaration
public override void DeleteBulk(string[] keys, DSWriteOption dsWriteOption, string providerName, DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the item.
DSWriteOption dsWriteOption

Options regarding updating data source
System.String providerName
DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback

A delegate that, if provided, is called when item is removed from data source.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

OnDataSourceItemsRemoved(IDictionary result)
{
...
}
Cache cache = NCache.InitializeCache("myCache");
string[] keys = new string[]{"myItem1", "myItem2"};
cache.DeleteBulk(keys, DSWriteOption.WriteBehind, "writeThruProvider", new DataSourceItemsRemovedCallback(OnDataSourceItemsRemoved));
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

Dispose()

Decerements the reference count of the cache and performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public override void Dispose()
Overrides
Remarks

The behavior of this method depends upon the cache's sharing mode (inproc/outproc) specified in the configuration.

If the application uses the cache in inproc mode, calling Dispose closes the cache and releases the resources used by it. If in a cluster the calling node leaves the cluster as well.

If the application uses the cache in outproc mode, calling Dispose releases the reference to the cache object. The cache itself remains operational and cluster remains intact.

ExecuteNonQuery(String, IDictionary)

Executes delete statements on Cache.

Declaration
public override int ExecuteNonQuery(string query, IDictionary values)
Parameters
Type Name Description
System.String query

simple SQL like query syntax
System.Collections.IDictionary values

The IDictionary of atribute names and values.
Returns
Type Description
System.Int32

returns the number of rows affected.
Overrides
Examples

Only Delete Query is supported yet.

These operators are supported by NCache Queries.

  1. Comparison Operators = , == , != , <> , < , > , <=, >=, IN
  2. Logical Operators AND , OR , NOT
  3. Miscellaneous () , DateTime.Now , DateTime("any date time compatible string")
Cache _cache = NCache.InitializeCache("myCache");

Hashtable values = new Hashtable();
values.Add("Name", "Paul Jones");
string query="delete Test.Application.Employee where this.Name = ?";
ICacheReader reader=_cache.ExecuteNonQuery(query,values);

values.Clear();
values.Add("Salary", 2000);
query="delete Test.Application.Employee where this.Salary > ?";
reader=_cache.ExecuteNonQuery(query,values);

values.Clear();
values.Add("Name", "Paul jones");
values.Add("Salary", 2000);
query="delete Test.Application.Employee where this.Name = ? and this.Salary > ?";
reader=_cache.ExecuteNonQuery(query,values);

values.Clear();
values.Add("Name", "Paul Jones");
values.Add("Salary", 2000);
query="delete Test.Application.Employee where Not(this.Name = 'Paul Jones' and this.Salary > 2000)";
reader=_cache.ExecuteNonQuery(query,values);

ExecuteReader(String, IDictionary)

Performs search on the Cache based on the query specified where query contains 'group by' clause.

Declaration
public override ICacheReader ExecuteReader(string query, IDictionary values)
Parameters
Type Name Description
System.String query

simple SQL like query syntax to query objects from cache
System.Collections.IDictionary values

The IDictionary of atribute names and values.
Returns
Type Description
ICacheReader

Returns a cache data reader ICacheReader
Overrides
Examples

These operators are supported by NCache Queries.

  1. Comparison Operators = , == , != , <> , < , > , <=, >=, IN
  2. Logical Operators AND , OR , NOT
  3. Miscellaneous () , DateTime.Now , DateTime("any date time compatible string")
Cache _cache = NCache.InitializeCache("myCache");

Hashtable values = new Hashtable();
values.Add("Name", "Paul Jones");
string query="select Test.Application.Employee where this.Name = ?";
ICacheReader result=_cache.ExecuteReader(query,values);

values.Clear();
values.Add("Salary", 2000);
query="select Test.Application.Employee where this.Salary > ?";
result=_cache.ExecuteReader(query,values);

values.Clear();
values.Add("Name", "Paul jones");
values.Add("Salary", 2000);
query="select Test.Application.Employee where this.Name = ? and this.Salary > ?";
result=_cache.ExecuteReader(query,values);

values.Clear();
values.Add("Name", "Paul Jones");
values.Add("Salary", 2000);
query="select Test.Application.Employee where Not(this.Name = 'Paul Jones' and this.Salary > 2000)";
result=_cache.ExecuteReader(query,values);

ExecuteReader(String, IDictionary, Boolean)

Declaration
public override ICacheReader ExecuteReader(string query, IDictionary values, bool getData)
Parameters
Type Name Description
System.String query
System.Collections.IDictionary values
System.Boolean getData
Returns
Type Description
ICacheReader
Overrides

ExecuteReader(String, IDictionary, Boolean, Int32)

Declaration
public override ICacheReader ExecuteReader(string query, IDictionary values, bool getData, int chunkSize)
Parameters
Type Name Description
System.String query
System.Collections.IDictionary values
System.Boolean getData
System.Int32 chunkSize
Returns
Type Description
ICacheReader
Overrides

ExecuteReaderCQ(ContinuousQuery)

Declaration
public override ICacheReader ExecuteReaderCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query
Returns
Type Description
ICacheReader
Overrides

ExecuteReaderCQ(ContinuousQuery, Boolean)

Declaration
public override ICacheReader ExecuteReaderCQ(ContinuousQuery cquery, bool getData)
Parameters
Type Name Description
ContinuousQuery cquery
System.Boolean getData
Returns
Type Description
ICacheReader
Overrides

ExecuteReaderCQ(ContinuousQuery, Boolean, Int32)

Declaration
public override ICacheReader ExecuteReaderCQ(ContinuousQuery query, bool getData, int chunkSize)
Parameters
Type Name Description
ContinuousQuery query
System.Boolean getData
System.Int32 chunkSize
Returns
Type Description
ICacheReader
Overrides

ExecuteTask(MapReduceTask)

Declaration
public override ITrackableTask ExecuteTask(MapReduceTask task)
Parameters
Type Name Description
MapReduceTask task
Returns
Type Description
ITrackableTask
Overrides

ExecuteTask(MapReduceTask, IKeyFilter)

Declaration
public override ITrackableTask ExecuteTask(MapReduceTask task, IKeyFilter keyFilter)
Parameters
Type Name Description
MapReduceTask task
IKeyFilter keyFilter
Returns
Type Description
ITrackableTask
Overrides

ExecuteTask(MapReduceTask, String, Hashtable)

Declaration
public override ITrackableTask ExecuteTask(MapReduceTask task, string query, Hashtable parameters)
Parameters
Type Name Description
MapReduceTask task
System.String query
System.Collections.Hashtable parameters
Returns
Type Description
ITrackableTask
Overrides

Get(String, DSReadOption)

Retrieves the specified item from the Cache object.

Declaration
public override object Get(string key, DSReadOption dsReadOption)
Parameters
Type Name Description
System.String key

The identifier for the cache item to retrieve.
DSReadOption dsReadOption

Options regarding reading from data source
Returns
Type Description
System.Object

The retrieved cache item, or a null reference (Nothing in Visual Basic) if the key is not found.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

NCache.Cache.Get("MyTextBox.Value");

Or simply in a class deriving from or .

Cache.Get("MyTextBox.Value");
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

Get(String, DSReadOption, ref CacheItemVersion)

Retrieves the specified item from the Cache object. If the object is read thru the data source, put is against the given group and sub group.

Declaration
public override object Get(string key, DSReadOption dsReadOption, ref CacheItemVersion version)
Parameters
Type Name Description
System.String key

The identifier for the cache item to retrieve.
DSReadOption dsReadOption

Options regarding reading from data source
CacheItemVersion version

The version of the desired object passed by reference.
Returns
Type Description
System.Object

The retrieved cache item, or a null reference (Nothing in Visual Basic) if the key is not found.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Note: The group and subGroup parameters are used only if the object is read thru the data source. Otherwise the object will be returned from the cache whether it belongs to the given group and sub group or not.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

NCache.Cache.Get("MyTextBox.Value", "Customer", null);

Or simply in a class deriving from or .

Cache.Get("MyTextBox.Value", "Customer", null);
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.
System.ArgumentNullException

group contains a null reference (Nothing in Visual Basic).

Get(String, String, String, DSReadOption)

Retrieves the specified item from the Cache object. If the object is read thru the data source, put is against the given group and sub group.

Declaration
public override object Get(string key, string group, string subGroup, DSReadOption dsReadOpt)
Parameters
Type Name Description
System.String key

The identifier for the cache item to retrieve.
System.String group

The group of the cached object
System.String subGroup

The subGroup of the cached object
DSReadOption dsReadOpt
Returns
Type Description
System.Object

The retrieved cache item, or a null reference (Nothing in Visual Basic) if the key is not found.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Note: The group and subGroup parameters are used only if the object is read thru the data source. Otherwise the object will be returned from the cache whether it belongs to the given group and sub group or not.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

NCache.Cache.Get("MyTextBox.Value", "Customer", null);

Or simply in a class deriving from or .

Cache.Get("MyTextBox.Value", "group", "subGroup", "Customer", null);
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.
System.ArgumentNullException

group contains a null reference (Nothing in Visual Basic).

Get(String, TimeSpan, ref LockHandle, Boolean)

Retrieves the specified item from the Cache object and also locks the object if required.

Declaration
public override object Get(string key, TimeSpan lockTimeout, ref LockHandle lockHandle, bool acquireLock)
Parameters
Type Name Description
System.String key

The identifier for the cache item to retrieve.
System.TimeSpan lockTimeout
LockHandle lockHandle
System.Boolean acquireLock

A flag to determine whether to acquire a lock or not.
Returns
Type Description
System.Object

The retrieved cache item, or a null reference (Nothing in Visual Basic) if the key is not found.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached and acquire a lock

object lockId = null;
DateTime nowTime = DateTime.Now;

object cachedItem = theCache.Get("cachedItemKey", ref lockId, ref nowTime, true);
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

GetBulk(String[], DSReadOption)

Retrieves the object from the cache for the given keys as key value pairs

Declaration
public override IDictionary GetBulk(string[] keys, DSReadOption dsReadOption)
Parameters
Type Name Description
System.String[] keys

The keys against which items are to be fetched.
DSReadOption dsReadOption

Options regarding reading from data source
Returns
Type Description
System.Collections.IDictionary

The retrieved cache items.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

NCache.Cache.Get(keys);

Or simply in a class deriving from or .

Cache.Get(keys,DSReadOption.ReadThru);
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

GetBulk(String[], String, DSReadOption)

Retrieves the object from the cache for the given keys as key value pairs

Declaration
public override IDictionary GetBulk(string[] keys, string providerName, DSReadOption dsReadOption)
Parameters
Type Name Description
System.String[] keys

The keys against which items are to be fetched.
System.String providerName

A unique identifier for the data source
DSReadOption dsReadOption

Options regarding reading from data source
Returns
Type Description
System.Collections.IDictionary

The retrieved cache items.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

NCache.Cache.Get(keys);

Or simply in a class deriving from or .

Cache.Get(keys,DSReadOption.ReadThru);
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

GetByAllTags(Tag[])

Returns the cached objects that have all the same tags in common. (Returns the Intersection set.)

Declaration
public override Hashtable GetByAllTags(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Returns
Type Description
System.Collections.Hashtable

A dictionary containing cache keys and associated objects.
Overrides
Examples

The following example demonstrates how to get the objects that have all the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
Hashtable table = cache.GetByAllTags(tags);

GetByAnyTag(Tag[])

Returns the cached objects that have any of the same tags in common. (Returns the Union set.)

Declaration
public override Hashtable GetByAnyTag(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Returns
Type Description
System.Collections.Hashtable

A dictionary containing cache keys and associated objects.
Overrides
Examples

The following example demonstrates how to get the objects that have any of the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
Hashtable table = cache.GetByAnyTag(tags);

GetByTag(Tag)

Gets all the cached objects with the specified tag.

Declaration
public override Hashtable GetByTag(Tag tag)
Parameters
Type Name Description
Tag tag

The tag to search with.
Returns
Type Description
System.Collections.Hashtable

Returns a dictionary containing the cache keys and associated objects.
Overrides
Examples

The following example demonstrates how to get the objects with the specified tag.

Cache cache = NCache.InitializeCache("myCache");
Tag tag = new Tag("Sports");
Hashtable table = cache.GetByTag(tag);

GetCacheItem(String)

Get the cache item stored in cache.

Declaration
public override CacheItem GetCacheItem(string key)
Parameters
Type Name Description
System.String key

Key used to reference the desired object
Returns
Type Description
CacheItem

CacheItem
Overrides

GetCacheItem(String, String, String)

Get the cache item stored in cache.

Declaration
public override CacheItem GetCacheItem(string key, string group, string subGroup)
Parameters
Type Name Description
System.String key

Key used to reference the desired object
System.String group

The group whose data is to be returned.
System.String subGroup

The sub group of the group for which data is to be returned.
Returns
Type Description
CacheItem

CacheItem
Overrides

GetCacheItem(String, TimeSpan, ref LockHandle, Boolean)

Get the cache item stored in cache.

Declaration
public override CacheItem GetCacheItem(string key, TimeSpan lockTimeout, ref LockHandle lockHandle, bool acquireLock)
Parameters
Type Name Description
System.String key

Key used to reference the desired object
System.TimeSpan lockTimeout

The TimeSpan after which the lock is automatically released.
LockHandle lockHandle

An instance of LockHandle to hold the lock information.
System.Boolean acquireLock

A flag to determine whether to acquire a lock or not.
Returns
Type Description
CacheItem

The retrieved cache item, or a null reference (Nothing in Visual Basic) if the key is not found.
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

GetCacheStream(String, String, String, StreamMode, CacheDependency, DateTime, TimeSpan, CacheItemPriority)

Gets an instance of the CacheStream class.

Declaration
public override CacheStream GetCacheStream(string key, string group, string subGroup, StreamMode streamMode, CacheDependency dependency, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.String group

The group whose keys are to be returned.
System.String subGroup

The sub group of the group foe which keys are to be returned.
StreamMode streamMode

Enumeration to specify the desired mode to open the stream.
CacheDependency dependency

CacheDependency to be added. When any dependency changes, the object becomes invalid and is removed from the cache. If there are no dependencies, this paramter contains a null reference.
System.DateTime absoluteExpiration

The time at which the added stream expires and is removed from the cache. If absolute expiration is not desired, specify Cache.NoAbsoluteExpiration

System.TimeSpan slidingExpiration

The interval between the time the added stream was last accessed and when it expires. If this value is the equivalent of 20 minutes, the object expires and is removed from the cache 20 minutes after it is last accessed. If sliding expiration is not desired, specify Cache.NoSlidingExpiration

CacheItemPriority priority

The relative cost of the object, as expressed by the CacheItemPriority enumeration. The cache uses this value when it evicts objects; objects with a lower cost are removed from the cache before objects with a higher cost.
Returns
Type Description
CacheStream

An instance of CacheStream
Overrides

GetConnectedClientList()

Declaration
public override IList<ClientInfo> GetConnectedClientList()
Returns
Type Description
System.Collections.Generic.IList<ClientInfo>
Overrides

GetEnumerator()

Retrieves a dictionary enumerator used to iterate through the key settings and their values contained in the cache.

Declaration
public override IEnumerator GetEnumerator()
Returns
Type Description
System.Collections.IEnumerator

An enumerator to iterate through the Cache object.
Overrides
Remarks

If items are added or removed from the cache while enumerating through the items the behavior is not predictable. It is therefore advised not to update the cache keys while enumerating.

Note: Just like Count in a cluster especially partitioned this operation is an expensive one and may require network calls. It is therefore advised to use this method only when required.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

GetGroupData(String, String)

Retrieves the key and value pairs in a group or sub group.

Declaration
public override IDictionary GetGroupData(string group, string subGroup)
Parameters
Type Name Description
System.String group

The group whose data is to be returned.
System.String subGroup

The sub group of the group for which data is to be returned.
Returns
Type Description
System.Collections.IDictionary

The list of key and value pairs of a group or a sub group.
Overrides
Remarks

If only group is specified, data for the group and all the sub groups of the group are returned. If both the group and sub group are specified. Only the data related to the sub group are returned.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

Hashtable table = NCache.Cache.Get("Customer", "Orders");

Or simply in a class deriving from or .

Hashtable table = Cache.GetGroupData("Customer", "Orders");
Exceptions
Type Condition
System.ArgumentNullException

group contains a null reference (Nothing in Visual Basic).

GetGroupKeys(String, String)

Retrieves the keys of items in a group or sub group.

Declaration
public override ArrayList GetGroupKeys(string group, string subGroup)
Parameters
Type Name Description
System.String group

The group whose keys are to be returned.
System.String subGroup

The sub group of the group foe which keys are to be returned.
Returns
Type Description
System.Collections.ArrayList

The list of keys of a group or a sub group.
Overrides
Remarks

If only group is specified, keys for the group and all the sub groups of the group are returned. If both the group and sub group are specified. Only the keys related to the sub group are returned.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how to retrieve the value cached for an ASP.NET text box server control.

ArrayList list = NCache.Cache.Get("Customer", "Orders");

Or simply in a class deriving from or .

ArrayList list = Cache.GetGroupKeys("Customer", "Orders");
Exceptions
Type Condition
System.ArgumentNullException

group contains a null reference (Nothing in Visual Basic).

GetIfNewer(String, String, String, ref CacheItemVersion)

Gets an object from the cache only if a newer version of the object exists in cache.

Declaration
public override object GetIfNewer(string key, string group, string subGroup, ref CacheItemVersion version)
Parameters
Type Name Description
System.String key

key used to reference the desired object
System.String group

The group of the cached object
System.String subGroup

The subGroup of the cached object
CacheItemVersion version

The version of the desired object passed by reference.
Returns
Type Description
System.Object

If a newer object exists in the cache, the object is returned. Otherwise, null is returned.
Overrides

GetKeysByAllTags(Tag[])

Returns keys that have all the same tags in common. (Returns the Intersection set.)

Declaration
public override ICollection GetKeysByAllTags(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Returns
Type Description
System.Collections.ICollection

A collection containing cache keys.
Overrides
Examples

The following example demonstrates how to get the keys that have all the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
ICollection keys = cache.GetKeysByAllTags(tags);

GetKeysByAnyTag(Tag[])

Returns keys that have any of the same tags in common. (Returns the Union set.)

Declaration
public override ICollection GetKeysByAnyTag(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Returns
Type Description
System.Collections.ICollection

A collection containing cache keys.
Overrides
Examples

The following example demonstrates how to get the keys that have any of the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
ICollection keys = cache.GetKeysByAnyTag(tags);

GetKeysByTag(Tag)

Declaration
public override ICollection GetKeysByTag(Tag tag)
Parameters
Type Name Description
Tag tag
Returns
Type Description
System.Collections.ICollection
Overrides

GetRunningTasks()

Declaration
public override ArrayList GetRunningTasks()
Returns
Type Description
System.Collections.ArrayList
Overrides

GetTaskResult(String)

Declaration
public override ITrackableTask GetTaskResult(string taskId)
Parameters
Type Name Description
System.String taskId
Returns
Type Description
ITrackableTask
Overrides

InsertAsyncOperation(String, Object, CacheDependency, CacheSyncDependency, DateTime, TimeSpan, CacheItemPriority, DSWriteOption, CacheItemRemovedCallback, CacheItemUpdatedCallback, AsyncItemUpdatedCallback, DataSourceItemsUpdatedCallback, Boolean, String, String, Tag[], String, NamedTagsDictionary, CacheDataNotificationCallback, CacheDataNotificationCallback, EventDataFilter, EventDataFilter, String, Int16, Int16, Int16)

This function tries to do an Insert asynchronously in remote cache, if successful the operation is then done to client cache

Declaration
protected override void InsertAsyncOperation(string key, object value, CacheDependency dependency, CacheSyncDependency syncDependency, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority, DSWriteOption dsWriteOption, CacheItemRemovedCallback onRemoveCallback, CacheItemUpdatedCallback onUpdateCallback, AsyncItemUpdatedCallback onAsyncItemUpdateCallback, DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback, bool isResyncExpiredItems, string group, string subGroup, Tag[] tags, string providerName, NamedTagsDictionary namedTags, CacheDataNotificationCallback cacheItemUdpatedCallback, CacheDataNotificationCallback cacheItemRemovedCallaback, EventDataFilter itemUpdateDataFilter, EventDataFilter itemRemovedDataFilter, string clientId, short updateCallbackId, short removeCallbackId, short dsItemUpdateCallbackId)
Parameters
Type Name Description
System.String key
System.Object value
CacheDependency dependency
CacheSyncDependency syncDependency
System.DateTime absoluteExpiration
System.TimeSpan slidingExpiration
CacheItemPriority priority
DSWriteOption dsWriteOption
CacheItemRemovedCallback onRemoveCallback
CacheItemUpdatedCallback onUpdateCallback
AsyncItemUpdatedCallback onAsyncItemUpdateCallback
DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback
System.Boolean isResyncExpiredItems
System.String group
System.String subGroup
Tag[] tags
System.String providerName
NamedTagsDictionary namedTags
CacheDataNotificationCallback cacheItemUdpatedCallback
CacheDataNotificationCallback cacheItemRemovedCallaback
Alachisoft.NCache.Runtime.Events.EventDataFilter itemUpdateDataFilter
Alachisoft.NCache.Runtime.Events.EventDataFilter itemRemovedDataFilter
System.String clientId
System.Int16 updateCallbackId
System.Int16 removeCallbackId
System.Int16 dsItemUpdateCallbackId
Overrides

InsertBulk(String[], CacheItem[], DSWriteOption, DataSourceItemsUpdatedCallback)

Insert list of CacheItem to the cache

Declaration
public override IDictionary InsertBulk(string[] keys, CacheItem[] items, DSWriteOption dsWriteOptions, DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the items.
CacheItem[] items

The items that are to be stored
DSWriteOption dsWriteOptions

Options regarding updating data source
DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback
Returns
Type Description
System.Collections.IDictionary

returns keys that are added or updated successfully and their status.
Overrides
Remarks

If CacheItem contains invalid values the related exception is thrown. See CacheItem for invalid property values and related exceptions

Examples

The following example demonstrates how to assign an item high priority when you insert it into your application's Cache object.

Note: For more information about how to use this method with the CacheItemRemovedCallback delegate, see CacheItemRemovedCallback.

First create CacheItems.

string[] keys = {"SQLDSN", "ORADSN"};
CacheItem items[] = new CacheItem[2];
items[0] = new CacheItem(sqlConnectionString);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(2);
item.SlidingExpiration = TimeSpan.Zero;
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

items[1] = new CacheItem(oraConnectionString);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(1);
item.SlidingExpiration = TimeSpan.Zero;
item.Priority = CacheItemPriority.Low;
item.ItemRemoveCallback = onRemove;

Then insert CacheItems to the cache

NCache.Cache.Insert(keys, items, "Connection", null);

Or simply in a class deriving from or .

Cache.Insert(keys, items, "Connection", null);

InsertBulk(String[], CacheItem[], DSWriteOption, String, DataSourceItemsUpdatedCallback)

Insert list of CacheItem to the cache

Declaration
public override IDictionary InsertBulk(string[] keys, CacheItem[] items, DSWriteOption dsWriteOptions, string provider, DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the items.
CacheItem[] items

The items that are to be stored
DSWriteOption dsWriteOptions
System.String provider
DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback

A delegate that, if provided, is called when item is updated in data source.
Returns
Type Description
System.Collections.IDictionary

returns keys that are added or updated successfully and their status.
Overrides
Remarks

If CacheItem contains invalid values the related exception is thrown. See CacheItem for invalid property values and related exceptions

Examples

The following example demonstrates how to assign an item high priority when you insert it into your application's Cache object.

Note: For more information about how to use this method with the CacheItemRemovedCallback delegate, see CacheItemRemovedCallback.

First create CacheItems.

string[] keys = {"SQLDSN", "ORADSN"};
CacheItem items[] = new CacheItem[2];
items[0] = new CacheItem(sqlConnectionString);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(2);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

items[1] = new CacheItem(oraConnectionString);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(1);
item.Priority = CacheItemPriority.Low;
item.ItemRemoveCallback = onRemove;

Then insert CacheItems to the cache

Cache cache = NCache.InitializeCache("myCache");
string[] keys = new string[]{"myItem1", "myItem2"};
CacheItem[] items = new CacheItem[]{myItem1, myItem2};
cache.InsertBulk(keys, items, DSWriteOption.WriteThru, providerName, new DataSourceItemsUpdatedCallback(onDSItemsUpdated));

Lock(String, TimeSpan, out LockHandle)

Acquire a lock on an item in cache.

Declaration
public override bool Lock(string key, TimeSpan lockTimeout, out LockHandle lockHandle)
Parameters
Type Name Description
System.String key

key of cached item to be locked.
System.TimeSpan lockTimeout

TimeSpan after which the lock is automatically released.
LockHandle lockHandle

An instance of that will be filled in with the lock information if lock is acquired successfully.
Returns
Type Description
System.Boolean

Whether or not lock was acquired successfully.
Overrides
Examples

Following example demonstrates how to lock a cached item.

...
LockHandle lockHandle = new LockHandle();
bool locked = theCache.lock("cachedItemKey", new TimeSpan(0,0,10), out lockHandle);
...

RaiseCustomEvent(Object, Object)

Broadcasts a custom application defined event.

Declaration
public override void RaiseCustomEvent(object notifId, object data)
Parameters
Type Name Description
System.Object notifId

Application specific notification code/id
System.Object data

Application specific data
Overrides
Remarks

In most of the cases this method's implementation is close to O(1).

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Note: Custom event notifications can not be disabled through configuration.

Examples

The following example demonstrates how to raise a custom application defined event.

NCache.Cache.RaiseCustomEvent(MyNotificationCodes.ConsumeItem,
      new ItemData(DateTime.Now));

Cache.RaiseCustomEvent(MyNotificationCodes.ConsumeItem,
      new ItemData(DateTime.Now));

RegisterCacheNotification(CacheDataNotificationCallback, EventType, EventDataFilter)

Registers ItemAdded, ItemUpdate or ItemRemoved events with cache

Declaration
public override CacheEventDescriptor RegisterCacheNotification(CacheDataNotificationCallback cacheDataNotificationCallback, EventType eventType, EventDataFilter datafilter)
Parameters
Type Name Description
CacheDataNotificationCallback cacheDataNotificationCallback

the CacheDataNotificationCallback that is invoked when an item is added, updated or removed from the cache.
Alachisoft.NCache.Runtime.Events.EventType eventType

Tells whether the event is to be raised on Item Added, Updated or Removed
Alachisoft.NCache.Runtime.Events.EventDataFilter datafilter

Tells whether to receive metadata, data with metadata or none when a notification is triggered
Returns
Type Description
CacheEventDescriptor
Overrides
Remarks

Client application can show interest in receiving events if an item is added, update or removed from the cache. As soon as the item is added, updated or removed from the cache, the client application is notified and actions can be taken accordingly.

Examples

First create an ItemCallback

ItemCallback(string key, CacheEventArg e)
{
   ...
}

Then register the Cache Notification

Cache cache = NCache.InitializeCache("myCache");
CacheEventDescriptor descriptor=cache.RegisterCacheNotification(new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

RegisterCacheNotification(String, CacheDataNotificationCallback, EventType, EventDataFilter)

Registers the ItemUpdate or ItemRemoved events for the specified key.

Declaration
public override void RegisterCacheNotification(string key, CacheDataNotificationCallback selectiveCacheDataNotificationCallback, EventType eventType, EventDataFilter datafilter)
Parameters
Type Name Description
System.String key

The cache key used to reference the cache item.
CacheDataNotificationCallback selectiveCacheDataNotificationCallback
Alachisoft.NCache.Runtime.Events.EventType eventType

Tells whether the event is to be raised on Item Added, Updated or Removed
Alachisoft.NCache.Runtime.Events.EventDataFilter datafilter

Tells whether to receive metadata, data with metadata or none when a notification is triggered
Overrides
Examples

First create an ItemCallback

ItemCallback(string key, CacheEventArg e)
{
   ...
}

Then register the Key Notification

Cache cache = NCache.InitializeCache("myCache");
cache.RegisterCacheNotification(key, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

RegisterCacheNotification(String[], CacheDataNotificationCallback, EventType, EventDataFilter)

Registers the ItemUpdate or ItemRemoved events for the specified keys.

Declaration
public override void RegisterCacheNotification(string[] key, CacheDataNotificationCallback selectiveCacheDataNotificationCallback, EventType eventType, EventDataFilter datafilter)
Parameters
Type Name Description
System.String[] key
CacheDataNotificationCallback selectiveCacheDataNotificationCallback
Alachisoft.NCache.Runtime.Events.EventType eventType

Tells whether the event is to be raised on item updated or removed
Alachisoft.NCache.Runtime.Events.EventDataFilter datafilter

This enum is to describe when registering an event, upon raise how much data is retrieved from cache when the event is raised
Overrides
Examples

First create an ItemCallback

ItemCallback(string key, CacheEventArg e)
{
   ...
}

Then register the Key Notification

Cache cache = NCache.InitializeCache("myCache");
string[] keys=new string[size];
cache.RegisterCacheNotification(keys,new CacheDataNotificationCallback(ItemCallback), EventType.ItemUpdated, EventDataFilter.None);

RegisterCQ(ContinuousQuery)

Declaration
public override void RegisterCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query
Overrides

RegisterKeyNotificationCallback(String, CacheItemUpdatedCallback, CacheItemRemovedCallback)

Registers the CacheItemUpdatedCallback and/or CacheItemRemovedCallback for the specified key.

Declaration
public override void RegisterKeyNotificationCallback(string key, CacheItemUpdatedCallback updateCallback, CacheItemRemovedCallback removeCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the cache item.
CacheItemUpdatedCallback updateCallback

The CacheItemUpdatedCallback that is invoked if the item with the specified key is updated in the cache.
CacheItemRemovedCallback removeCallback

The CacheItemRemovedCallback is invoked when the item with the specified key is removed from the cache.
Overrides
Remarks

CacheItemUpdatedCallback and/or CacheItemRemovedCallback provided this way are very useful because a client application can show interest in any item already present in the cache. As soon as the item is updated or removed from the cache, the client application is notified and actions can be taken accordingly.

Remove(String, CacheItemVersion)

Declaration
public override object Remove(string key, CacheItemVersion version)
Parameters
Type Name Description
System.String key
CacheItemVersion version
Returns
Type Description
System.Object
Overrides

Remove(String, DSWriteOption, DataSourceItemsRemovedCallback)

Removes the object from the Cache.

Declaration
public override object Remove(string key, DSWriteOption dsWriteOption, DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
DSWriteOption dsWriteOption

Options regarding updating data source
DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback
Returns
Type Description
System.Object

The item removed from the Cache. If the value in the key parameter is not found, returns a null reference (Nothing in Visual Basic).
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

NCache.Cache.Remove("timestamp");

Or simply in a class deriving from or .

Cache.Remove("timestamp");
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

Remove(String, DSWriteOption, String, DataSourceItemsRemovedCallback)

Declaration
public override object Remove(string key, DSWriteOption dsWriteOption, string providerName, DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback)
Parameters
Type Name Description
System.String key
DSWriteOption dsWriteOption
System.String providerName
DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback
Returns
Type Description
System.Object
Overrides

Remove(String, LockHandle)

Declaration
public override object Remove(string key, LockHandle lockHandle)
Parameters
Type Name Description
System.String key
LockHandle lockHandle
Returns
Type Description
System.Object
Overrides

RemoveAsync(String, AsyncItemRemovedCallback, DSWriteOption, String, DataSourceItemsRemovedCallback)

Removes the object from the Cache asynchronously.

Declaration
public override void RemoveAsync(string key, AsyncItemRemovedCallback onAsyncItemRemoveCallback, DSWriteOption dsWriteOption, string providerName, DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
AsyncItemRemovedCallback onAsyncItemRemoveCallback

The delegate that can be used by the client application to get the result of the Asynchronous Remove operation.
DSWriteOption dsWriteOption

Options regarding updating data source
System.String providerName
DataSourceItemsRemovedCallback onDataSourceItemRemovedCallback
Overrides
Remarks

This is similar to Remove(String, LockHandle) except that the operation is performed asynchronously. A ItemRemoved event is fired upon successful completion of this method.It is not possible to determine if the actual operation has failed, therefore use this operation for the cases when it does not matter much.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

OnAsyncItemRemoved(string key, object result)
{
...
}

NCache.Cache.RemoveAsync("timestamp", new AsyncItemRemovedCallback(OnAsyncItemRemoved));

Or simply in a class deriving from or .

Cache.RemoveAsync("timestamp", new AsyncItemRemovedCallback(OnAsyncItemRemoved));
Exceptions
Type Condition
System.ArgumentNullException

key contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key is not serializable.

RemoveBulk(String[], DSWriteOption, DataSourceItemsRemovedCallback)

Removes the objects from the Cache.

Declaration
public override IDictionary RemoveBulk(string[] keys, DSWriteOption dsWriteOption, DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the item.
DSWriteOption dsWriteOption
DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback
Returns
Type Description
System.Collections.IDictionary

The items removed from the Cache. If the value in the keys parameter is not found, returns a null reference (Nothing in Visual Basic).
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

NCache.Cache.Remove(keys);

Or simply in a class deriving from or .

Cache.Remove(keys);
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

RemoveBulk(String[], DSWriteOption, String, DataSourceItemsRemovedCallback)

Removes the objects from the Cache.

Declaration
public override IDictionary RemoveBulk(string[] keys, DSWriteOption dsWriteOption, string providerName, DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback)
Parameters
Type Name Description
System.String[] keys

The cache keys used to reference the item.
DSWriteOption dsWriteOption
System.String providerName
DataSourceItemsRemovedCallback onDataSourceItemsRemovedCallback
Returns
Type Description
System.Collections.IDictionary

The items removed from the Cache. If the value in the keys parameter is not found, returns a null reference (Nothing in Visual Basic).
Overrides
Remarks

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception incase of failure.

Examples

The following example demonstrates how you can remove an item from your application's Cache object.

NCache.Cache.Remove(keys);

Or simply in a class deriving from or .

Cache.Remove(keys);
Exceptions
Type Condition
System.ArgumentNullException

keys contains a null reference (Nothing in Visual Basic).
System.ArgumentException

keys is not serializable.

RemoveByAllTags(Tag[])

Removes the cached objects that have all the same tags in common. (Returns the Union set.)

Declaration
public override void RemoveByAllTags(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Overrides
Examples

The following example demonstrates how to remove the objects that have all of the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
cache.RemoveByAllMatchingTags(tags);

RemoveByAnyTag(Tag[])

Removes the cached objects that have any of the same tags in common. (Returns the Union set.)

Declaration
public override void RemoveByAnyTag(Tag[] tags)
Parameters
Type Name Description
Tag[] tags

An array of Tag to search with.
Overrides
Examples

The following example demonstrates how to remove the objects that have any of the specified tags in common.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[2];
tags[0] = new Tag("Alpha");
tags[1] = new Tag("Beta");
cache.RemoveByAnyMatchingTag(tags);

RemoveByTag(Tag)

Removes the cached objects with the specified tag.

Declaration
public override void RemoveByTag(Tag tag)
Parameters
Type Name Description
Tag tag

A Tag to search with.
Overrides
Examples

The following example demonstrates how to remove the objects that have the specified tag.

Cache cache = NCache.InitializeCache("myCache");
Tag tag = new Tag("Alpha");
cache.RemoveByTag(tag);

RemoveGroupData(String, String)

Remove the group from cache.

Declaration
public override void RemoveGroupData(string group, string subGroup)
Parameters
Type Name Description
System.String group

group to be removed.
System.String subGroup

subGroup to be removed.
Overrides

Search(String, IDictionary)

Performs search on the Cache based on the query specified.

Declaration
public override ICollection Search(string query, IDictionary values)
Parameters
Type Name Description
System.String query

simple SQL like query syntax to oquery objects from cache
System.Collections.IDictionary values

The IDictionary of atribute names and values.
Returns
Type Description
System.Collections.ICollection

Returns a list of cache keys
Overrides
Examples

These operators are supported by NCache Queries.

  1. Comparison Operators = , == , != , <> , < , > , <=, >=, IN
  2. Logical Operators AND , OR , NOT
  3. Miscellaneous () , DateTime.Now , DateTime("any date time compatible string")
Hashtable values = new Hashtable();
values.add("Name", "Paul Jones");
"select Test.Application.Employee where this.Name = ?"

values.add("Salary", 2000);
"select Test.Application.Employee where this.Salary > ?"

values.Add("Name", "Paul jones");
values.Add("Salary", 2000);
"select Test.Application.Employee where this.Name = ? and this.Salary > ?"

values.Add("Name", "Paul Jones");
values.Add("Salary", 2000);
"select Test.Application.Employee where Not(this.Name = 'Paul Jones' and this.Salary > 2000)"

SearchCQ(ContinuousQuery)

Declaration
public override ICollection SearchCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query
Returns
Type Description
System.Collections.ICollection
Overrides

SearchEntries(String, IDictionary)

Performs search on the Cache based on the query specified.

Declaration
public override IDictionary SearchEntries(string query, IDictionary values)
Parameters
Type Name Description
System.String query

simple SQL like query syntax t oquery objects from cache
System.Collections.IDictionary values

The IDictionary of atribute names and values.
Returns
Type Description
System.Collections.IDictionary

Returns a dictionary containing cache keys and associated objects
Overrides
Examples

These operators are supported by NCache Queries.

  1. Comparison Operators = , == , != , <> , < , > , <=, >=, IN
  2. Logical Operators AND , OR , NOT
  3. Miscellaneous () , DateTime.Now , DateTime("any date time compatible string")
Hashtable values = new Hashtable();
values.add("Name", "Paul Jones");
"select Test.Application.Employee where this.Name = ?"

values.add("Salary", 2000);
"select Test.Application.Employee where this.Salary > ?"

values.Add("Name", "Paul jones");
values.Add("Salary", 2000);
"select Test.Application.Employee where this.Name = ? and this.Salary > ?"

values.Add("Name", "Paul Jones");
values.Add("Salary", 2000);
"select Test.Application.Employee where Not(this.Name = 'Paul Jones' and this.Salary > 2000)"

SearchEntriesCQ(ContinuousQuery)

Declaration
public override IDictionary SearchEntriesCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query
Returns
Type Description
System.Collections.IDictionary
Overrides

SetAttributes(String, CacheItemAttributes)

Add Attribute existing cache item.

Declaration
public override bool SetAttributes(string key, CacheItemAttributes attributes)
Parameters
Type Name Description
System.String key

key used to reference the required object
CacheItemAttributes attributes
Returns
Type Description
System.Boolean

True if the operation successeded otherwise false
Overrides

ToString()

Returns System.String that represents the current ClientCache object

Declaration
public override string ToString()
Returns
Type Description
System.String

String representing ClientCache
Overrides

Unlock(String)

Forcefully unlocks a locked cached item.

Declaration
public override void Unlock(string key)
Parameters
Type Name Description
System.String key

key of a cached item to be unlocked
Overrides
Examples

Following example demonstrates how to unlock a cached item.

...
theCache.Unlock("cachedItemKey");
...

Unlock(String, LockHandle)

Unlocks a locked cached item if the correct lock-id is specified.

Declaration
public override void Unlock(string key, LockHandle lockHandle)
Parameters
Type Name Description
System.String key

key of a cached item to be unlocked
LockHandle lockHandle

An instance of LockHandle that was generated when lock was acquired.
Overrides
Examples

Following example demonstrates how to unlock a cached item.

...
theCache.Unlock("cachedItemKey", lockHandle);
...

UnRegisterCacheNotification(CacheEventDescriptor)

Unregisters a cache level event that may have been registered

Declaration
public override void UnRegisterCacheNotification(CacheEventDescriptor discriptor)
Parameters
Type Name Description
CacheEventDescriptor discriptor

The descriptor returned when the general event was registered
Overrides
Examples

Let us consider you registered an event against a cache

Cache cache = NCache.InitializeCache("myCache");
CacheEventDescriptor eDescriptor=cache.RegisterCacheNotification(new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

Now, Unregister this event by using the CacheEventDescriptor returned by regitering the event

cache.UnRegisterCacheNotification(eDescriptor);

UnRegisterCacheNotification(String, CacheDataNotificationCallback, EventType)

Unregisters event that may have been registered against a specific key

Declaration
public override void UnRegisterCacheNotification(string key, CacheDataNotificationCallback callback, EventType eventType)
Parameters
Type Name Description
System.String key

The cache key used to reference the cache item
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that was specified while registering the event.
Alachisoft.NCache.Runtime.Events.EventType eventType

Type of the event to unregister
Overrides
Examples

Let us consider you registered an event against a key

Cache cache = NCache.InitializeCache("myCache");
cache.RegisterCacheNotification(key, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

Now, Unregister this event by providing the key, callback and eventtype

cache.UnRegisterCacheNotification(key, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded);

UnRegisterCacheNotification(String[], CacheDataNotificationCallback, EventType)

Unregisters any event that may have been registered by the user against multiple cache keys

Declaration
public override void UnRegisterCacheNotification(string[] key, CacheDataNotificationCallback callback, EventType eventType)
Parameters
Type Name Description
System.String[] key

An array of cache keys used to reference the cache itemst
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that was specified while registering the event.
Alachisoft.NCache.Runtime.Events.EventType eventType

Type of event to unregister
Overrides
Examples

Let us consider you registered an event against a bulk of keys

Cache cache = NCache.InitializeCache("myCache");
string[] keys=new string[size];
cache.RegisterCacheNotification(keys, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

Now, Unregister this event by providing the key, callback and eventtype

cache.UnRegisterCacheNotification(keys, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded);

UnRegisterCQ(ContinuousQuery)

Declaration
public override void UnRegisterCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query
Overrides

UnRegisterKeyNotificationCallback(String, CacheItemUpdatedCallback, CacheItemRemovedCallback)

Unregisters the CacheItemUpdatedCallback and/or CacheItemRemovedCallback already registered for the specified key.

Declaration
public override void UnRegisterKeyNotificationCallback(string key, CacheItemUpdatedCallback updateCallback, CacheItemRemovedCallback removeCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the cache item.
CacheItemUpdatedCallback updateCallback

CacheItemUpdatedCallback that is invoked when the item with the specified key is updated in the cache.
CacheItemRemovedCallback removeCallback

CacheItemRemovedCallback that is invoked when the item with the key is removed from the cache.
Overrides

UnRegisterKeyNotificationCallback(String[], CacheItemUpdatedCallback, CacheItemRemovedCallback)

Declaration
public override void UnRegisterKeyNotificationCallback(string[] keys, CacheItemUpdatedCallback updateCallback, CacheItemRemovedCallback removeCallback)
Parameters
Type Name Description
System.String[] keys
CacheItemUpdatedCallback updateCallback
CacheItemRemovedCallback removeCallback
Overrides

CacheCleared

Occurs after the Cache is cleared.

Declaration
public override event CacheClearedCallback CacheCleared
Event Type
Type Description
CacheClearedCallback
Overrides
Remarks

You can use this event to perform tasks when the Cache is cleared.

Since this callback is invoked every time an item is removed from the Cache, doing a lot of processing inside the callback might have an impact on the performance of the cache and cluster. It is therefore advisable to do minimal processing inside the handler.

For more information on how to use this callback see the documentation for CacheClearedCallback.

CacheClientConnectivityChanged

Declaration
public override event CacheClientConnectivityChangedCallback CacheClientConnectivityChanged
Event Type
Type Description
CacheClientConnectivityChangedCallback
Overrides

CacheStopped

Occurs after the cache has been stopped.

Declaration
public override event CacheStoppedCallback CacheStopped
Event Type
Type Description
CacheStoppedCallback
Overrides
Remarks

You can use this event to perform the tasks when a the cache has been stopped.

This callback is invoked when the cache has either been stopped intentionally or connection with the server has been lost due to some reason so that you can connect to another server.

For more information on how to use this callback see the documentation for CacheStoppedCallback.

CustomEvent

Occurs in response to a RaiseCustomEvent(Object, Object) method call.

Declaration
public override event CustomEventCallback CustomEvent
Event Type
Type Description
CustomEventCallback
Overrides
Remarks

You can use this event to handle custom application defined event notifications.

Doing a lot of processing inside the handler might have an impact on the performance of the cache and cluster. It is therefore advisable to do minimal processing inside the handler.

For more information on how to use this callback see the documentation for CustomEventCallback.

ItemAdded

Occurs after an item has been added to the Cache.

Declaration
public override event CacheItemAddedCallback ItemAdded
Event Type
Type Description
CacheItemAddedCallback
Overrides
Remarks

You can use this event to perform tasks when an item is added to the Cache.

Since this callback is invoked every time an item is removed from the Cache, doing a lot of processing inside the callback might have an impact on the performance of the cache and cluster. It is therefore advisable to do minimal processing inside the handler.

For more information on how to use this callback see the documentation for CacheItemAddedCallback.

ItemRemoved

Occurs after an has been removed from the Cache.

Declaration
public override event CacheItemRemovedCallback ItemRemoved
Event Type
Type Description
CacheItemRemovedCallback
Overrides
Remarks

You can use this event to perform tasks when an item is removed from the Cache.

Since this callback is invoked every time an item is removed from the Cache, doing a lot of processing inside the callback might have an impact on the performance of the cache and cluster. It is therefore advisable to do minimal processing inside the handler.

Note: If an item is removed from the Cache for which a callback is supplied as parameter to or method; that callback will be invoked instead of this callback.

For more information on how to use this callback see the documentation for CacheItemRemovedCallback.

ItemUpdated

Occurs after an item has been updated in the Cache.

Declaration
public override event CacheItemUpdatedCallback ItemUpdated
Event Type
Type Description
CacheItemUpdatedCallback
Overrides
Remarks

You can use this event to perform tasks when an item is updated in the Cache.

Since this callback is invoked every time an item is removed from the Cache, doing a lot of processing inside the callback might have an impact on the performance of the cache and cluster. It is therefore advisable to do minimal processing inside the handler.

For more information on how to use this callback see the documentation for CacheItemUpdatedCallback.

MemberJoined

Occurs after a new node has joined the cluster.

Declaration
public override event MemberJoinedCallback MemberJoined
Event Type
Type Description
MemberJoinedCallback
Overrides
Remarks

You can use this event to perform the tasks when a new node joins the cluster.

This callback is invoked every time a node joins the cluster. As part of the callback you receive the port at which the new node accepts the remote client connections.a

For more information on how to use this callback see the documentation for MemberJoinedCallback.

MemberLeft

Occurs after a node has left the cluster.

Declaration
public override event MemberLeftCallback MemberLeft
Event Type
Type Description
MemberLeftCallback
Overrides
Remarks

You can use this event to perform the tasks when a node leaves the cluster.

This callback is invoked every time an existing node leaves the cluster.

For more information on how to use this callback see the documentation for MemberLeftCallback.