Item Level Event Notifications

Item Level Data Notifications can be used when you want to be notified about a limited set of data rather than every operation performed on cache.

For example, if the cache contains a large amount of data and gets notified every time any change occurs in the data set, which causes an overhead and the application's performance gets affected. To provide better performance for the application, you can select a particular data set and get notifications for that.

The cache will be responsible for monitoring changes for the specified chunk. Since the data set to be selected is already added in the cache, the cache provides notifications on performing the UPDATE or REMOVE operation.

Applications register callback method for a specific key in cache using API calls and get a notification when that key gets updated or removed from cache.

These Notifications are asynchronously sent to the client so there is no overhead on client’s activities.

Pre-Requisites

Install the following NuGet packages in your application:
- Alachisoft.NCache.SDK
Include the following namespaces in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Events
- Alachisoft.NCache.Runtime.Exceptions
The application must be connected to cache before performing the operation.
Cache must be running.
Make sure that the data being added is serializable.
For API details, refer to: ICache, CacheItem, EventType, EventDataFilter.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add the following Maven dependencies in your pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-client</artifactId>
    <version>5.2.0</version>
</dependency>

Import the following packages in your application:
- import com.alachisoft.ncache.client.*;
- import com.alachisoft.ncache.runtime.exceptions.*;
- import com.alachisoft.ncache.runtime.events.*;
The application must be connected to cache before performing the operation.
Cache must be running.
Make sure that the data being added is serializable.
For API details, refer to: Cache, CacheItem,getEventType, EventDataFilter,EventType.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Include the following modules in your application:
- const ncache = require('ncache-client')
The application must be connected to cache before performing the operation.
Cache must be running.
For API details, refer to: Cache, CacheItem, EventType, EventDataFilter.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Step 1: Register Callback for Event Notifications

First step is to register a callback for the multiple events. The example below shows how to register callbacks event notifications.

// Create a target method
// Precondition: Events have been enabled
public static void OnCacheDataModification(string key, CacheEventArg args)
{
    switch (args.EventType)
    {
        case EventType.ItemUpdated:
        // 'key' has been updated in the cache
        // Get the updated product
        if (args.Item != null)
        {
            Product updatedProduct = args.Item.GetValue<Product>();
            // Perform operations
        }
        break;

        case EventType.ItemRemoved:
        // 'key' has been removed from the cache
        break;
    }
}

// Create a target method
// Precondition: Events have been enabled
public void onCacheDataModification(String key, CacheEventArg args) 
{
    switch (args.getEventType()) 
    {
        case ItemAdded:
            // Key has been added to the cache
            break;
        case ItemUpdated:
            // 'key' has been updated in the cache
            // get the updated product

            if (args.getItem() != null) 
            {
                Product updateProduct = args.getItem().getValue(Product.class);
                // perform operations
            }
            break;
        case ItemRemoved:
            // 'key' has been removed from the cache
            break;
    }
}

// Create a target method
// Pre-condition: Events have been enabled 
onCacheDataModified(key, arg) 
{    
    if (null != arg.getEventType()) 
    {
        switch (arg.getEventType()) 
        {
            // perform operations
        case ncache.EventType.ItemAdded:
            // key has been added to cache
            break;
        case ncache.EventType.ItemUpdated:
            // key has been updated in cache
            break;
        case ncache.EventType.ItemRemoved:
            // key has been removed from cache
            break;
        default:
            break;
        }
    }
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Step 2: Register Item Notifications

After registering the callbacks, a target method is created which contains multiple callbacks.

Appropriate EventType is used to restrict the cache for monitoring only the specific client operation. Event type includes ItemUpdated and ItemRemovedevent type that must be specified by a separate method call. Multiple event types can also be specified in a single method call.

EventDataFilter is specified to quantify the amount of information returned upon an event execution. Events that are registered then provide the user with the information based on these data filters. Following are the data filters that can be specified by the user.

None: On specifying this filter, only the affected keys are returned in the event notification.
MetaData: On specifying this filter, the affected keys along with their metadata are returned in the event notification. The metadata that is returned includes the groups and subgroups, cache item priority, provider name and the expiration of the items.
DataWithMetadata: On specifying this filter, the keys along with the metadata as well as their entire values are returned. It provides the entire data and metadata in the event notification.

For more detail please refer to the Events Overview section.

Note

The key must exist in cache for the event to be registered. Only update or remove event types can be registered in item level events.

Register Item Notifications for a Particular Item

In order to register item notification for a single specified item, use the RegisterCacheNotifications method which takes a single key, the EventType and the EventDataFilter.

The following example shows how to register item notifications with the ItemUpdated event type for a particular item.

Note

If EventDataFilter is not specified, EventDataFilter.None is set automatically.

try
{
    // PreCondition: Cache is already initialized
    // Register target method

    CacheDataNotificationCallback dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataModification);

    // Register item notifications with 'ItemUpdated' event type
    // EventDataFilter as DataWithMetadata which returns keys along with their 
    // entire data
    cache.MessagingService.RegisterCacheNotification(key, dataNotificationCallback,
    EventType.ItemUpdated,
    EventDataFilter.DataWithMetadata);

    // Perform your business logic
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentException, ArgumentNullException
}

try 
{
    // Precondition: Cache is already connected
    // Register target method

    var dataModificationListener = onCacheDataModification(key, args);
    CacheDataModification dataModification = new CacheDataModification(dataModificationListener);

    // Register item notification with "ItemUpdated" event type
    // EventDataFilter as DataWithMetadata which returns keys along with their entire data
    EnumSet<com.alachisoft.ncache.runtime.events.EventType> enumSet = EnumSet.of(EventType.ItemAdded);
    cache.getMessagingService().addCacheNotificationListener(key, dataModification, enumSet, EventDataFilter.DataWithMetadata);

    // Perform your business logic
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection failures
    // Operation timeout
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

try 
{
    // PreCondition: Cache is already initialized

    // Register target method
    let dataModificationListener = new ncache.CacheDataModificationListener(this.onCacheDataModified, this.onCacheCleared);
    let key = "Product:1001";

    // Register item notifications with 'ItemUpdated' event type
    // EventDataFilter as DataWithMetadata which returns keys along with their 
    // entire data
    let messagingService = await this.cache.getMessagingService();
    await messagingService.addCacheNotificationListener(key, dataModificationListener, ncache.EventType.ItemUpdated, ncache.EventDataFilter.DataWithMetadata);
}
catch (error) 
{
    // Handle any errors
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Register Item Notifications for a Specified Items

In order to register item notification for a chunk of specified item, use the RegisterCacheNotifications method which takes an array of keys, the EventType and the EventDataFilter.

The following example shows how to register item notifications with the ItemUpdated and ItemRemoved event type for a particular item.

Note

If EventDataFilter is not specified, EventDataFilter.None is set automatically.

try
{
    // PreCondition: Cache is already initialized

    // Register target method
    CacheDataNotificationCallback dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataModification);

    // Fetch all products from database
    Product[] products = FetchProductsFromDB();

    // Create a new array keys with the specified keys for which the cache 
    // fires notifications
    string[] keys = new string[products.Length];
    int index = 0;
    foreach (var product in products)
    {
        // Generate a unique cache key for this product
        keys[index] = $"Product:{product.ProductID}";
        index++;
    }

    // Register item notifications with 'ItemUpdated' and 'ItemRemoved' event type
    // EventDataFilter as DataWithMetadata which returns keys along with their 
    // entire data
    cache.MessagingService.RegisterCacheNotification(keys, dataNotificationCallback,
    EventType.ItemUpdated,
    EventDataFilter.DataWithMetadata);

    // Perform your business logic
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentException, ArgumentNullException
}

try 
{
    // Precondition: Cache is already connected

    // Register target method
    var dataModificationListener = onCacheDataModification(key, args);
    CacheDataModification dataModification = new CacheDataModification(dataModificationListener);

    // Fetch all products from database
    com.Product[] products = fetchProductsFromDB();

    // Create a new array of keys for which the cache fires notifications
    String[] keys = new String[products.length];
    int index = 0;
    for (var product : products) 
    {
        // Generate a unique cache key for this product
        keys[index] = "Product:" + product.productID;
        index++;
    }

    // Create EnumSet with ItemUpdated and ItemRemoved event type
    EnumSet<EventType> enumSet = EnumSet.of(EventType.ItemUpdated, EventType.ItemRemoved);

    // Register item notification with ItemUpdated and ItemRemoved event type
    // EventDataFilter as DataWithMetadata which returns keys along with their entire data
    var data = cache.getMessagingService().addCacheNotificationListener(key, dataModification, enumSet, EventDataFilter.DataWithMetadata);

    // Perform your business logic
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection failures
    // Operation timeout
} 
catch (Exception exception) 
{
    // Any generic exception
}

// This is an async method
try 
{
    // PreCondition: Cache is already initialized

    // Register target method
    let dataModificationListener = new ncache.CacheDataModificationListener(this.onCacheDataModified, this.onCacheCleared);
    // Fetch all products from database
    let products = this.fetchProductsFromDB();

    // Create a new array keys with the specified keys for which the cache 
    // fires notifications
    let keys = new String[products.length];
    var index = 0;
    products.forEach(element => {
    keys[index] = "Product:1001";
    index++;
    });

    // Register item notifications with 'ItemUpdated' and 'ItemRemoved' event type
    // EventDataFilter as DataWithMetadata which returns keys along with their 
    // entire data
    let messagingService = await this.cache.getMessagingService();
    await messagingService.addCacheNotificationListener(keys, dataModificationListener, ncache.EventType.ItemUpdated, ncache.EventDataFilter.DataWithMetadata);
} 
catch (error) 
{
    // Handle errors
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Step 3: Register Item Notifications Using CacheItem

CacheItem is a custom class provided by NCache which can be used to add data to the cache. Item level events can also be registered with a particular key by registering as a property of CacheItem.

SetCacheDataNotification method allows you to provide appropriate information for registering the notifications for the CacheItem.

The example below registers item notifications for a cache item with the event type of ItemUpdated and ItemRemoved.

try
{
    // PreCondition: Cache is already initialized

    // Register target method
    var dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataModification);

    // Get Product from database against given ProductID
    Product product = FetchProductFromDB("1001");

    // Create a unique cache key for this customer.
    string key = $"Products:{product.ProductID}";

    // Create a new CacheItem
    var cacheItem = new CacheItem(product);

    // Register events with CaceItem with Item Removed and ItemUpdated EventType
    // Set the EventDataFilter as DataWithMetadata which returns keys along with their entire data
    cacheItem.SetCacheDataNotification(dataNotificationCallback, EventType.ItemRemoved | EventType.ItemUpdated, EventDataFilter.DataWithMetadata);

    //Re-inserts the cacheItem into cache with events registered
    cache.Insert(key, cacheItem);  
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentException, ArgumentNullException
}

try 
{
    // Precondition: Cache is already connected

    // Register target method
    var dataModificationListener = onCacheDataModification(key, args);
    CacheDataModification dataModification = new CacheDataModification(dataModificationListener);

    // Get product from database
    com.Product product = fetchProductFromDB(productid);

    // Create a unique cache key for this product
    String productKey = "Product:" + product.productID;

    // Create a new CacheItem
    CacheItem cacheItem = new CacheItem(product);

    // Create EnumSet of ItemUpdated and ItemRemoved event types
    EnumSet<EventType> enumSet = EnumSet.of(EventType.ItemUpdated, EventType.ItemRemoved);

    // Register events with CacheItem with Item Removed and ItemUpdated EventType
    // Set the EventDataFilter as DataWithMetadata which returns keys along with their entire data
    cacheItem.addCacheDataNotificationListener(dataModification, enumSet, EventDataFilter.DataWithMetadata);

    // Insert the cache item in the cache with events registered
    cache.insert(productKey, cacheItem);
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection failures
    // Operation timeout
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

// This is an async method
try 
{
    // PreCondition: Cache is already initialized

    // Register target method
    let eventListener = new ncache.CacheDataModificationListener(this.onCacheDataModified, this.onCacheCleared);
    let messagingService = await this.cache.getMessagingService();
    await messagingService.addCacheNotificationListener("key", eventListener, ncache.EventType.ItemAdded, ncache.EventDataFilter.Metadata);

    // Get Product from database against given ProductID
    let products = this.fetchProductsFromDB();
    // Create a unique cache key for this customer.
    let key = "Product:1001";

    // Register events with CaceItem with Item Removed and ItemUpdated EventType
    // Set the EventDataFilter as DataWithMetadata which returns keys along with their entire data  
    let messagingService2 = await this.cache.getMessagingService();
    await messagingService2.addCacheNotificationListener(eventListener, ncache.EventType.ItemAdded, ncache.EventType.ItemRemoved,
    ncache.EventType.ItemUpdated, ncache.EventDataFilter.Metadata);
    let cacheItem = ncache.CacheItem;

    //Inserts the cacheItem into cache with events registered
    this.cache.insert(key, cacheItem);
} 
catch (error) 
{
    // Handle errors
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Step 3: Unregister Item Level Notifications

You can also unregister a previously registered item level notification using the UnRegisterCacheNotification method if you don't want to receive further notifications. For Java, use the removeCacheDataModificationListener method to unregister the registered notifications.

Using this method, the appropriate key, callback CacheDataNotificationCallback and EventType must be specified.

Following example shows how to unregister notifications for a specific key.

try
{
    // Unregister notifications for the ItemRemoved EventType for the 
    // particular key and specify the callback
    cache.MessagingService.UnRegisterCacheNotification(key, new CacheDataNotificationCallback(OnItemRemovedCallback), EventType.ItemRemoved);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentException, ArgumentNullException
}

try 
{
    // Unregister notifications for the ItemRemoved EventType for particular key
    // Specify callback
    var dataModificationListener = onCacheDataModification(key, args);
    EnumSet<EventType> enumSet = EnumSet.of(EventType.ItemRemoved);
    cache.getMessagingService().removeCacheNotificationListener(key, dataModificationListener, enumSet);
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection failures
    // Operation timeout
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

// This is an async method
try 
{
    let eventListener;
    // Unregister notifications for the ItemRemoved EventType for the 
    // particular key and specify the callback
    await this.cache.removeCacheNotificationListener("key", eventListener, ncache.EventType.ItemRemoved);
} 
catch (error) 
{
    // Handle errors
}

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Additional Resources

For a full functioning .NET application executing events, you can use the sample placed on GitHub.

Item Level Event Notifications

Pre-Requisites

Step 1: Register Callback for Event Notifications

Step 2: Register Item Notifications

Note

Register Item Notifications for a Particular Item

Note

Register Item Notifications for a Specified Items

Note

Step 3: Register Item Notifications Using CacheItem

Step 3: Unregister Item Level Notifications

Additional Resources

See Also