Event Notifications in Cache: An 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, and client applications can register for events they are interested in.

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

  • An event is generated only if a client application has registered for it.
  • Events are published only to subscribed clients.
  • The cache determines when an event is raised, while the client determines how to respond to it.
  • 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

Many applications today need to share data asynchronously with each other at runtime to maintain data integrity. They also need to update their state of data or synchronize their data snapshot with the server-side state. To achieve this, an application needs a mechanism to monitor its state of data with the server. Event Notifications provide this mechanism by notifying the client application every time data is changed in the cache.

Hence, events allow runtime data sharing among separate applications or among different modules of the same application. Moreover, NCache's event-driven data fetching 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 the 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. The 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 the EventDataFilter which is further discussed in the Event Filters section. The data-specific events can be further categorized as follows:

Cache Level Events

The 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. By default, the 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.

Warning

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

Item Level Events

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

Note

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

The cache will be responsible for monitoring changes to the specified keys. Since the selected dataset already exists in the cache, the Item Level Events are triggered only for update or remove operations. Applications register callback methods for specific keys in the cache using API calls, and they are notified whenever those keys are updated or removed from the cache. These notifications are sent asynchronously to the client, ensuring no additional overhead on the client's operations.

Note

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

Management Level Events

The Management Level Events are useful when you want to be notified about any management operation that is performed on the cache cluster using the NotificationService interface. These events can help validate whether operations on the cache are continuing as expected. For example, consider a multi-threaded client application where one 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 when the cache stops. This can be easily achieved by registering for an event against cache stop action.

This example also applies to cache clear notifications. If a client application thread performs validation while the cache is being cleared, those validations will fail unless the application accounts for a cache-clear event. The 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 performing operations without being aware that the cache has stopped, those operations will result in exceptions.

  • Member Joined Notification: Member joined notification is fired when a new node joins the cache cluster. A cache administrator or any user monitoring the cluster state can use this event to automate tasks related to cluster management. Therefore, when a member joins the cluster, the event should be handled to ensure that automated tasks continue without interruption.

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

Client Activity Events

Client activity events notify applications when clients connect to or disconnect from the cache. Any client connected to a clustered cache can subscribe to these events to receive notifications about the connection or disconnection of other clients.

You can also specify a 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 this retention period, the disconnect event is not fired.

This feature helps compensate for accidental or brief disconnections caused by unstable networks, since the NCache client automatically reconnects without disrupting operations. Note that this does not apply to the clients that manually dispose and reinitialize themselves. You need to enable client activity notifications in the NCache Management Center before they can be used.

Event Data Filters

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

Warning

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

None

This filter returns only the keys affected by an operation in the event notification. It is useful when the application needs to know which keys changed but does not require the associated values. For example, an e-commerce site may want to track which product keys were added without retrieving the product details 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. It is useful when an application needs to process the modified data itself. For example, a banking application may need to know which customer information has changed. By registering for an item update notifications with this filter, the application receives both the item key and the updated item when the event is fired.

Using the DataWithMetadata filter saves a trip when fetching items again with the Get API. However, it should be used only when necessary, as returning large amounts of data may increase network overhead.

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, the 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 that stores the criteria-based data is responsible for generating the corresponding event notifications.

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

In This Section

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

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

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