Interface IMessagingService

This interface contains properties and methods required for Messaging Service.

Assembly: Alachisoft.NCache.Client.dll
Syntax
public interface IMessagingService

Methods

CreateTopic(String, TopicPriority)

Creates and retrieves the topic instance against the specified topic name.

Declaration
ITopic CreateTopic(string topicName, TopicPriority topicPriority = TopicPriority.Normal)
Parameters
Type Name Description
System.String topicName

Name or a pattern to identify topic.
TopicPriority topicPriority

Topic Priority is an optional parameter which has a default value of TopicPriority.Normal.
Returns
Type Description
ITopic

Returns the topic instance, null if it does not exist.
Examples

The following example demonstrates how to create a topic. First, initialize the cache.

ICache cache = CacheManager.GetCache("demoCache");

Then, get messaging service from the cache.

IMessagingService messagingService = cache.MessagingService;

Then, create the topic from messagingService.

ITopic topic = messagingService.CreateTopic("mytopic");

DeleteTopic(String)

Deletes the topic instance against the specified topic name.

Declaration
void DeleteTopic(string topicName)
Parameters
Type Name Description
System.String topicName

Name to identify topic.
Examples

The following example demonstrates how to delete a topic.

First, initialize the cache.

ICache cache = CacheManager.GetCache("demoCache");

Then, get messaging service from cache.

IMessagingService messagingService=cache.MessagingService;

The,n delete topic from messagingService.

messagingService.DeleteTopic("mytopic");

DeleteTopicAsync(String)

Deletes the topic instance asynchronously, against the specified topic name.

Declaration
Task DeleteTopicAsync(string topicName)
Parameters
Type Name Description
System.String topicName

Name to identify topic.
Returns
Type Description
System.Threading.Tasks.Task

Task that performs an delete topic operation in the background. Task Status property can be used to determine status of the Task that can be canceled, completed or faulted.
Examples

The following example demonstrates how to delete a topic.

First, initialize cache.

ICache cache = CacheManager.GetCache("demoCache");

Then, get messaging service from cache.

IMessagingService messagingService=cache.MessagingService;

Then, delete topic from messagingService.

messagingService.DeleteTopicAsync("mytopic").ContinueWith(task => 
{
    if (task.Status == TaskStatus.RanToCompletion)
    {
        Console.WriteLine("Topic Deleted Successfully");
    }
    if (task.Status == TaskStatus.Faulted)
    {
        Console.WriteLine("Error has occurred");
    }
    if (task.Exception != null)
    {
        Console.WriteLine(task.Exception);
    }
});

GetTopic(String, TopicSearchOptions)

Retrieves the topic instance against the TopicSearchOptions and provided name or pattern.

Declaration
ITopic GetTopic(string topicName, TopicSearchOptions searchOptions = TopicSearchOptions.ByName)
Parameters
Type Name Description
System.String topicName

Name or pattern to identify topic.
TopicSearchOptions searchOptions

TopicSearchOptions specifies to search topic by name or pattern.
Returns
Type Description
ITopic

Returns the topic instance, null if it does not exist.
Examples

The following example demonstrates how to get topic by name. First, initialize the cache.

ICache cache = CacheManager.GetCache("demoCache");

Then, get topic from MessagingService.

ITopic topic = cache.MessagingService.GetTopic("mytopic", TopicSearchOptions.ByName);
TopicSearch Option is an optional paramater which has default value of ByName

RegisterCacheNotification(CacheDataNotificationCallback, EventType, EventDataFilter)

Registers cache notification EventType of type item added, updated or removed against specified keys in cache.

Declaration
CacheEventDescriptor RegisterCacheNotification(CacheDataNotificationCallback callback, EventType eventType, EventDataFilter eventDataFilter = EventDataFilter.None)
Parameters
Type Name Description
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that is invoked when specified EventType is triggered in cache.
EventType eventType

Tells whether the event is to be raised on Item Added, Updated or Removed.
EventDataFilter eventDataFilter

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

Instance of CacheEventDescriptor required to

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

The following example demonstrates how to register Item added, updated or removed notification in cache. First, create an ItemCallback.

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

Then, register the Cache Notification.

ICache cache = CacheManager.GetCache("demoCache");
CacheEventDescriptor descriptor = cache.MessagingService.RegisterCacheNotification(new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

RegisterCacheNotification(IEnumerable<String>, CacheDataNotificationCallback, EventType, EventDataFilter)

Registers cache notification EventType of type item added, updated or removed against specified keys in cache.

Declaration
void RegisterCacheNotification(IEnumerable<string> keys, CacheDataNotificationCallback callback, EventType eventType, EventDataFilter eventDataFilter = EventDataFilter.None)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<System.String> keys

IEnumerable list of keys to identify the cache item.
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that is invoked when specified EventType is triggered against specified keys in cache.
EventType eventType

Tells whether the event is to be raised on item added, updated or removed.
EventDataFilter eventDataFilter

Tells whether to receive metadata, data with metadata or none when a notification is triggered.
Remarks

Only single notification is registered against duplicate keys in keys.

Examples

The following example demonstrates how to register item added, updated or removed notification against multiple keys in cache. First, create an ItemCallback.

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

Then, register the Key Notification.

ICache cache = CacheManager.GetCache("demoCache");
List<string> keys = new List<string>()
{
    "Product0",
    "Product1",
    "Product2"
};

cache.MessagingService.RegisterCacheNotification(keys, new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.DataWithMetadata);

RegisterCacheNotification(String, CacheDataNotificationCallback, EventType, EventDataFilter)

Registers cache notification EventType of type item added, updated or removed against specified key in cache.

Declaration
void RegisterCacheNotification(string key, CacheDataNotificationCallback callback, EventType eventType, EventDataFilter eventDataFilter = EventDataFilter.None)
Parameters
Type Name Description
System.String key

Unique key to identify the cache item.
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that is invoked when specified EventType is triggered against specified key in cache.
EventType eventType

States whether the event is to be raised on item added, updated or removed.
EventDataFilter eventDataFilter

States whether to receive metadata, data with metadata or none when a notification is triggered.
Examples

The following example demonstrates how to register item added, updated or removed notification against a key in cache. First, create an ItemCallback.

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

Then, register the Key Notification.

ICache cache = CacheManager.GetCache("demoCache");
cache.MessagingService.RegisterCacheNotification(key, new CacheDataNotificationCallback(ItemCallback), EventType.ItemUpdated, EventDataFilter.DataWithMetadata);

RegisterCQ(ContinuousQuery)

Registers the specified Continuous Query with the cache server. You can use this method multiple times in your application depending on its need to receive the notifications for a change in the dataset of your query. This method takes as argument an object of ContinuousQuery which has the query and the callbacks registered to it.

Declaration
void RegisterCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query

SQL-like query to be executed on cache.
Examples

The following example demonstrates how to register a continuous query with item added, updated and removed callbacks.

ICache cache = CacheManager.GetCache("demoCache");

string queryString = "SELECT MyApplication.Employee WHERE this.Salary > ?";

QueryCommand queryCommand = new QueryCommand(queryString);
queryCommand.Parameters.Add("Salary", 50000);

ContinuousQuery continuousQuery = new ContinuousQuery(queryCommand);

continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemAdded), EventType.ItemAdded, EventDataFilter.None);
continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemUpdated), EventType.ItemUpdated, EventDataFilter.DataWithMetadata);
continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemRemoved), EventType.ItemRemoved, EventDataFilter.None);

cache.MessagingService.RegisterCQ(continuousQuery);

UnRegisterCacheNotification(CacheEventDescriptor)

Unregisters a cache-level event that may have been registered.

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

The descriptor returned when the general event was registered.
Examples

Let us consider you registered an event against a cache.

ICache cache = CacheManager.GetCache("demoCache");
CacheEventDescriptor descriptor = cache.MessagingService.RegisterCacheNotification(new CacheDataNotificationCallback(ItemCallback), EventType.ItemAdded, EventDataFilter.None);

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

cache.MessagingService.UnRegisterCacheNotification(descriptor);

UnRegisterCacheNotification(IEnumerable<String>, CacheDataNotificationCallback, EventType)

Unregisters cache notification against specified keys in cache.

Declaration
void UnRegisterCacheNotification(IEnumerable<string> keys, CacheDataNotificationCallback callback, EventType EventType)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<System.String> keys

IEnumerable list of keys to identify the cache item.
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that is invoked when specified EventType is triggered against specified keys in cache.
EventType EventType

Tells whether the event is to be raised on Item Added, Updated or Removed.
Examples

The following example demonstrates how to unregister Item added, updated or removed notification against multiple keys in cache. First, create an ItemCallback.

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

Then, register the Key Notification.

ICache cache = CacheManager.GetCache("demoCache");

List<string> keys = new List<string>()
{
    "Product0",
    "Product1",
    "Product2"
};

cache.MessagingService.RegisterCacheNotification(keys, new CacheDataNotificationCallback(ItemAdded), EventType.ItemAdded, EventDataFilter.DataWithMetadata);

Now, Unregister this event.

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

UnRegisterCacheNotification(String, CacheDataNotificationCallback, EventType)

Unregisters the Alachisoft.NCache.Client.CacheItemUpdatedCallback already registered for the specified key.

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

Unique key to identify the cache item.
CacheDataNotificationCallback callback

The CacheDataNotificationCallback that is invoked when specified EventType is triggered in cache.
EventType EventType

Tells whether the event is to be raised on Item Added, Updated or Removed.
Examples

The following example registers and unregisters update and remove notification against a key First, create an ItemCallback.

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

Then, register the Key Notification.

ICache cache = CacheManager.GetCache("demoCache");
cache.MessagingService.RegisterCacheNotification(key, new CacheDataNotificationCallback(ItemCallback), EventType.ItemUpdated, EventDataFilter.DataWithMetadata);

Now, Unregister this event.

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

UnRegisterCQ(ContinuousQuery)

Unregisters an already registered continuous query to deactivate it on the cache server. Like RegisterCQ, it takes as argument an object of ContinuousQuery to unregister the callbacks which are no more fired after this call.

This method is used when the user is no more interested in receiving notifications for changes in a query result set.

Declaration
void UnRegisterCQ(ContinuousQuery query)
Parameters
Type Name Description
ContinuousQuery query

SQL-like query to be executed over the cache.
Examples

The following example demonstrates how to unregister a Continuous Query on the cache.

ICache cache = CacheManager.GetCache("demoCache");

string queryString = "SELECT MyApplication.Employee WHERE this.Salary > ?";

QueryCommand queryCommand = new QueryCommand(queryString);
queryCommand.Parameters.Add("Salary", 50000);

ContinuousQuery continuousQuery = new ContinuousQuery(queryCommand);

continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemAdded), EventType.ItemAdded, EventDataFilter.None);
continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemUpdated), EventType.ItemUpdated, EventDataFilter.DataWithMetadata);
continuousQuery.RegisterNotification(new QueryDataNotificationCallback(query_ItemRemoved), EventType.ItemRemoved, EventDataFilter.None);

cache.MessagingService.RegisterCQ(continuousQuery);

cache.MessagingService.UnRegisterCQ(continuousQuery);