Item Level Event Notifications

The Item Level Event Notifications can be registered to get notifications for specific key/keys. Besides keys, the Item Level Events can also be registered using the CacheItem class. The notifications can be received when update or remove operations are performed on specified keys. The Item Level Events can be registered using the RegisterCacheNotification by providing the implemented callback, EventType, and EventDataFilter.

Important

The key must exist in the cache for the event to be registered. Only the update or remove event types can be registered for Item Level Events.

The relevant details of registering Item Level Events are discussed, as follows.

Prerequisites

To learn about the standard prerequisites required to work with all NCache client-side features, please refer to the given page on Client-Side API Prerequisites.
Make sure to enable event notifications using the NCache Management Center.
For API details, refer to: ICache, CacheItem, EventType, EventDataFilter, RegisterCacheNotification, UnRegisterCacheNotification, CacheDataNotificationCallback.

Implement Callback for Event Notifications

You can implement a callback for events where the EventType is specified according to the user's logic for ItemUpdated or ItemRemoved events. The example below shows how to register callbacks for event notifications.

public void OnCacheDataModification(string key, CacheEventArg args)
{
    switch (args.EventType)
    {

        case EventType.ItemUpdated:
            Console.WriteLine($"Item with Key '{key}' has been updated in the cache '{args.CacheName}'");

            // Item can be used if EventDataFilter is DataWithMetadata or Metadata
            if (args.Item != null)
            {
                Product updatedProduct = args.Item.GetValue<Product>();
                Console.WriteLine($"Updated Item is a Product having name '{updatedProduct.ProductName}' with ID '{updatedProduct.ProductID}' and price '{updatedProduct.UnitPrice}'");
            }
            break;

        case EventType.ItemRemoved:
            Console.WriteLine($"Key '{key}' has been removed from the cache '{args.CacheName}'");
            break;
      }
}

// Precondition: Events have been enabled

// Create a target method
public class CacheDataModificationListenerImpl implements CacheDataModificationListener {
      @Override
      public void onCacheDataModified(String key, CacheEventArg args) {
          switch (args.getEventType()) {

              case ItemUpdated:
                  System.out.println("Item with Key '" + key + "' has been updated in the cache '" + args.getCacheName() + "'");

                  // Item can be used if EventDataFilter is DataWithMetadata or Metadata
                  if (args.getItem() != null) {
                      Customer updatedCustomer = args.getItem().getValue(Customer.class); //Ignore error code works
                      System.out.println("Updated Item: " + updatedCustomer);
                  }
                  break;

              case ItemRemoved:
                  System.out.println("Item with Key '" + key + "' has been removed from the cache '" + args.getCacheName() + "'");
                  break;
          }
          System.out.println("Completed");
      }
}

def on_cache_data_modified(key: str, arg: ncache.CacheEventArg):
    if arg.get_event_type() is not None:
        if arg.get_event_type() is ncache.EventType.ITEM_UPDATED:
            # Key has been updated in cache
            print("Item updated")
        elif arg.get_event_type() is ncache.EventType.ITEM_REMOVED:
            # key has been removed from cache
            print("Item removed")

// Precondition: Events have been enabled

// Create a target method
onCacheDataModified(key, arg)
{
  if (null != arg.getEventType())
  {
    switch (arg.getEventType())
    {
      // perform operations
      case ncache.EventType.ItemUpdated:
        // key has been updated in cache

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

Note

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

Given that callback has been implemented, a target method is created which contains multiple callbacks. The appropriate EventType is provided for monitoring only the specific client operations. These event types include ItemUpdated and ItemRemoved which must be specified by a separate method call. The EventDataFilter is specified to quantify the amount of information returned upon an event execution.

Note

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

Here, we explain how you can register item notifications for a particular item or set of items.

Register Item Notifications for a Particular Item

To register item notification for a single item, use the RegisterCacheNotifications method by providing 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.

// Key of the cache item to be monitored events
string key = "Product:Chai";

// create CacheDataNotificationCallback object
var dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataUpdation);

// Register notifications for a specific item being updated in cache
// EventDataFilter as DataWithMetadata which returns keys along with their entire data
cache.MessagingService.RegisterCacheNotification(key, dataNotificationCallback, EventType.ItemUpdated, EventDataFilter.DataWithMetadata);

// Callback to Update Event Notifications
public void OnCacheDataUpdation(string key, CacheEventArg args)
{
    Console.WriteLine($"Item with Key '{key}' has been updated in the cache '{args.CacheName}'");

    // Item can be used if EventDataFilter is DataWithMetadata or Metadata
    if (args.Item != null)
    {
        Product updatedProduct = args.Item.GetValue<Product>();
        Console.WriteLine($"Updated Item is a Product having name '{updatedProduct.ProductName}' with ID '{updatedProduct.ProductID}' and price '{updatedProduct.UnitPrice}'");
    }
}

String key = "Product:Chai";

// Create CacheDataNotificationCallback object
CacheDataModificationListener dataModificationListener = new CacheDataModificationListenerImpl();

// Register notifications for a specific item being updated in cache
// EventDataFilter as DataWithMetadata which returns keys along with their entire data

cache.getMessagingService().addCacheNotificationListener(key, dataModificationListener, EnumSet.of(EventType.ItemUpdated), EventDataFilter.DataWithMetadata);
System.out.println("Item level notifications registered successfully for key: " + key);

key = "Product:1001"

# Register item notifications with 'ITEM_UPDATED' event type
# EventDataFilter as DATA_WITH_META_DATA which returns keys along with their
# entire data
messaging_service = cache.get_messaging_service()
messaging_service.add_cache_notification_listener(
    event_listener,
    [ncache.EventType.ITEM_UPDATED],
    ncache.EventDataFilter.DATA_WITH_META_DATA,
    key
  )

Register Item Notifications for a Set of Items

To register item notifications for a set of items, use the RegisterCacheNotifications method by providing an array of keys, the EventType, and the EventDataFilter. The following example shows how to register item notifications with the ItemUpdated event type for a set of items.

// Array of keys for items that need to be monitored on events
String[] keys = new String[]
{
    "Product:Chai", "Product:Coffee", "Product:Juice", "Product:Coke"
};

// create CacheDataNotificationCallback object
var dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataUpdation);

// Register notifications for specific set of items being updated in cache
// EventDataFilter as DataWithMetadata which returns keys along with their entire data
cache.MessagingService.RegisterCacheNotification(keys, dataNotificationCallback, EventType.ItemUpdated, EventDataFilter.DataWithMetadata);

String[] keys = new String[]{
    "Product:Chai", "Product:Coffee", "Product:Juice", "Product:Coke"
    };

// Create CacheDataNotificationCallback object
CacheDataModificationListener dataModificationListener = new CacheDataModificationListenerImpl();

// Register notifications for a specific set of items being updated in cache
// EventDataFilter as DataWithMetadata which returns keys along with their entire data
for (String key : keys) {
  cache.getMessagingService().addCacheNotificationListener(key, dataModificationListener, EnumSet.of(EventType.ItemUpdated), EventDataFilter.DataWithMetadata);
  }
System.out.println("Item level notifications registered successfully for the set of keys.");

# Register target method
data_modification_listener = event_listener
# Fetch all products from database
products = fetch_products_from_db()

# Create a array keys with the specified keys for which the cache
# fires notifications
keys = []

for product in products:
    keys.append("Product:" + str(product.get_product_id()))

# Register item notifications with 'ITEM_UPDATED' and 'ITEM_REMOVED' event type
# EventDataFilter as DATA_WITH_META_DATA which returns keys along with their
# entire data
messaging_service = cache.get_messaging_service()
messaging_service.add_cache_notification_listener(
    data_modification_listener,
    [ncache.EventType.ITEM_UPDATED],
    ncache.EventDataFilter.DATA_WITH_META_DATA,
    keys

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
);

Register Item Notifications Using CacheItem

The CacheItem is a custom class provided by NCache which can be used to add data to the cache. The Item Level Events can also be registered with a particular key by using the CacheItem.SetCacheDataNotification method. This method allows you to provide the appropriate information for registering the notifications for the CacheItem. The example below registers ItemUpdated and ItemRemoved events for a CacheItem.

string key = "Product:Chai";

// Fetch item from cache
CacheItem cacheItem = cache.GetCacheItem(key);

if(cacheItem == null)
{
    Product product = FetchProductFromDB("Chai");
    cacheItem = new CacheItem(product);
}

// create CacheDataNotificationCallback object
var dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataModification);

// 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);

String key = "Product:Chai";

// Fetch item from cache
CacheItem cacheItem = null;
 cacheItem = cache.getCacheItem(key);


if (cacheItem == null) {
    Customer customer = Customer.fetchCustomerFromDB("Customer:ALFKI");
    cacheItem = new CacheItem(customer);
}

// Create CacheDataNotificationCallback object
CacheDataModificationListener dataModificationListener = new CacheDataModificationListenerImpl();

// Register events with CacheItem with ItemRemoved and ItemUpdated EventType
// Set the EventDataFilter as DataWithMetadata which returns keys along with their entire data
cacheItem.addCacheDataNotificationListener(dataModificationListener, EnumSet.of(EventType.ItemRemoved, EventType.ItemUpdated), EventDataFilter.DataWithMetadata);

// Re-inserts the cacheItem into cache with events registered

cache.insert(key, cacheItem);
System.out.println("CacheItem inserted successfully");

# Get Product from database
product = fetch_product_from_db()

# Create a unique cache key for this product.
key = "Product:1001"

# Register events with CacheItem with ITEM_REMOVED and ITEM_UPDATED EventType
# Set the EventDataFilter as DATA_WITH_META_DATA which returns keys along with their entire data
cache_item = ncache.CacheItem(product)
cache_item.add_cache_data_notification_listener(
    event_listener,
    [ncache.EventType.ITEM_REMOVED, ncache.EventType.ITEM_UPDATED],
    ncache.EventDataFilter.DATA_WITH_META_DATA
)

# Inserts the cacheItem into cache with events registered
cache.insert(key, cache_item)

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);

Unregister Item Level Event Notifications

You can also unregister a previously registered Item Level Event 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. The following example shows how to unregister notifications for a specific key.

// Key of cached item to un-register events
string key = "Product:Chai";

// callback method triggered on cache item events
var dataNotificationCallback = new CacheDataNotificationCallback(OnCacheDataUpdation);

// Unregister notifications for the ItemUpdated EventType for particular key and specify the callback
cache.MessagingService.UnRegisterCacheNotification(key, dataNotificationCallback, EventType.ItemUpdated);

// Unregister notifications for the ItemRemoved EventType for particular key and specify callback
CacheDataModificationListener dataModificationListener = new CacheDataModificationListenerImpl();

CacheEventDescriptor eventDescriptor = cache.getMessagingService().addCacheNotificationListener(dataModificationListener, EnumSet.of(EventType.ItemAdded), EventDataFilter.None);

cache.getMessagingService().removeCacheNotificationListener(eventDescriptor);

# Unregister notifications for the ITEM_REMOVED EventType for the
# particular key and specify the callback
cache.get_messaging_service().remove_cache_notification_listener
    keys="key",
    callablefunction=event_listener,
    eventtypes=[ncache.EventType.ITEM_REMOVED]

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
);

Additional Resources

NCache provides a sample application for Item Level Event Notifications on GitHub.

Item Level Event Notifications

Important

Prerequisites

Implement Callback for Event Notifications

Note

Register Item Notifications

Note

Register Item Notifications for a Particular Item

Register Item Notifications for a Set of Items

Register Item Notifications Using CacheItem

Unregister Item Level Event Notifications

Additional Resources

See Also

Contact Us