Event Notifications Overview

In a distributed caching paradigm, your client application may need to get notified about the variety of operations happening in the cache. NCache can generate different types of events while your client applications can register for events of interest to get notified.

Note

This feature is only available in NCache Enterprise.

Here are some key points related to events in the cache:

  • An event is generated only if a client application has registered for it.
  • An event is published only to subscribed clients.
  • The cache determines when an event is raised and the client determines the action to be taken in response to an event.
  • A client can register for multiple events and can also handle multiple events from multiple caches.
Note

An application will not be able to receive events unless it registers itself against the cache using the specific event registration API call.

Importance of Event Notifications in Cache

Many applications today need to share data asynchronously with each other at runtime to provide data integrity. In addition, they need to update their state of data or synchronize the snapshot of data with the server-side state. Therefore, the application needs a mechanism to monitor its state of data with the server. Event Notifications provide this mechanism for notifying the client application every time data is changed in the cache.

Hence, events allow runtime data sharing among separate applications or separate modules of the same application. Moreover, event-driven data fetching supported by NCache enables client applications to receive data without any explicit data fetch request to the cache server.

Events in NCache

Events may be raised for cache-level activity specific to data or management operations. Here, we categorize events and discuss relevant details.

Data Specific Events

As the name indicates, these events are triggered when data in the cache is modified due to add, update, or remove operations. Aside from these basic CRUD operations, data-specific events are also fired when data is added, updated, or removed in cache due to Cache Startup Loader/Refresher and Backing Source.

To register these events for notification, the MessagingService.RegisterCacheNotification method is used. Similarly, data-specific notifications can be easily unregistered if no longer required, using the MessagingService.UnRegisterCacheNotification method.

You need to specify the appropriate EventType while registering for data-specific events using EventType enum. Following notifications can be fired based on registered EventType:

  • Add Notification: Add notification is triggered when the ItemAdded event type is registered and a new item is added to the cache.

  • Update Notification: Update notification is triggered when the ItemUpdated event type is registered and an existing item is updated in the cache.

  • Remove Notification: Remove notification is triggered when the ItemRemoved event type is registered and an item is removed from the cache.

You can also control the information returned upon an event execution using EventDataFilter which is further discussed in Event Filters section.

Data-specific events can be further categorized as follows:

Cache Level Events

Cache Level Events are general events for cache which are triggered upon the execution of the Add, Update, or Remove operations on cache data. The purpose is to notify different clients about every operation performed on the cache.

Warning

Cache Level Events might degrade your application performance when notifications are registered for all operations on the entire cache data set.

By default, Cache Level Events are disabled (except for cache cleared operation) for any cache configuration and must be enabled for events to be published using the NCache Management Center.

Item Level Events

Item Level Events can be useful when you want to be notified about a limited set of data rather than every operation performed on the cache. For example, if the cache contains a large amount of data and gets notified every time any change occurs in the data set, it causes overhead and the application's performance gets affected.

Note

For better performance, you can register notifications for the data set of interest only.

The cache will be responsible for monitoring changes for the specified keys. Since the selected data set already exists in the cache, Item Level Events are received on the update or remove operation only. Applications register callback methods for a specific key in the cache using API calls and get a notification when that key gets updated or removed from the cache. These notifications are asynchronously sent to the client so there is no overhead on the client’s activities.

Note

Since Item Level Events are registered for data set already in the cache, add notification can not be received.

Management Level Events

Management Level Events can register to be notified when any management operation is performed on the cache cluster using the NotificationService interface.

These events can be used for validation to see if operations continue on the cache or not. For example, the client is a multi-threaded application where a thread is dedicated to inserting items at a constant rate. If the cache is stopped during insertion, the NCache client will throw OperationFailedException. To prevent the exception from being thrown, the thread must take appropriate action upon stopping of cache. This can be simply achieved by registering for an event against cache stop action.

This example also applies to cache clear notifications if the client application’s thread validates operations during its execution while the cache is cleared. All validations will fail if the client application does not consider a clear cache event.

Following notifications are fired when management operations are performed on the cache:

  • Cache Cleared Notification: Cache cleared notification is fired when the cache is cleared.

  • Cache Stopped Notification: Cache stopped notification is fired when cache is stopped. If an application continues to perform operations when the cache is stopped without knowing that the cache is stopped, an exception will be thrown for the operations performed.

  • Member Joined Notification: Member joined notification is fired when a member joins the cluster. A cache administrator or a user monitoring the state of the cache during operations could automate their tasks for monitoring the state of the cluster. Hence, if a member joins the cluster, the event should be handled to prevent any interruption in the automated tasks.

  • Member Left Notification: Member left notification is fired when a member leaves the cluster.

Client Activity Events

Client activity events notify the connection/disconnection of clients. Each client connected to a clustered cache can subscribe to these events to get notified about the connect/disconnect events of other clients.

You can also specify the Retention Period, which is the time after which a disconnected client is considered disconnected, and its disconnect event is fired. If a client reconnects within the retention period, its disconnect event is not fired.

This is to compensate for any accidental disconnects occurring due to buggy networks since the NCache client automatically reconnects in such networks without disrupting the client operations. Note that this does not apply to the clients that manually dispose and reinitialize themselves.

You need to enable client activity notifications in NCache Management Center before use.

Event Data Filters

NCache provides EventDataFilter to control the amount of information returned upon execution of data-specific events. The types of event filters are explained below.

Warning

Event data filter must be carefully set to avoid unnecessary network bandwidth consumption.

None

This filter returns only the keys affected by the operation in the event notification. This is used if the application is only interested in knowing which keys were affected. For instance, an e-commerce site wants to know which product keys were added and not the values themselves.

Metadata

With this filter, the affected keys along with their metadata are returned in the event notification. The metadata that is returned includes the group, cache item priority, expiration, CacheItemVersion, ResyncOptions, CacheItemRemovedReason, and EntryType. This information may be required by the user. For instance, when an application wants to know which keys were removed from the cache and which groups they belonged to.

DataWithMetadata

This filter returns the keys along with the cached items and their associated metadata. This can be used in cases when an application needs to process the modified data. For instance, a banking application might require knowing which customer's information has been modified. Hence, it can register notifications for item update operations with this filter so that the item key and modified item are also returned to the user once the event is fired.

Using the DataWithMetadata filter saves a trip when fetching items again with the Get API. However, this filter must be used where necessary, since it may cause network hogging when the amount of data returned is huge.

Warning

In case of client disconnection, the events are not logged during the disconnected time span of the client.

Topology Wise Behavior

Event notifications are fired according to the cache topology being used. The topology-wise behavior for event notifications is described as follows:

  • Mirror Topology: In the Mirror Topology, an active node of the cluster is responsible for notifying the event to the client.

  • Replicated Topology: In the Replicated Topology, the node in the cluster that is connected to the client is responsible for raising the event notifications.

  • Partition-Replica Topology: In the Partition-Replica Topology, events are fired from the active nodes. The node where criteria-based data resides is responsible for event notifications.

  • Partitioned Topology: In the Partitioned Topology, events are fired from all nodes. The node where criteria-based data resides is responsible for event notifications.

In This Section

Cache Level Events
Explains how to use a notification mechanism for events occurring at the cache level.

Item Level Events
Explains how to use a notification mechanism for events occurring at the item level.

Management Level Events
Explains how to add a management-level events mechanism.