Custom Events

In multiple clients connected to cache environment, the best way to communicate among them is important. Custom Notifications are special type of notification which follows a publisher and subscriber communication model. It is a simple message passing mechanism to control flow among clients connected to a cache.

Custom Events work on the Pub/Sub model. In order to get more detail related to this please refer to the Pun/Sub Messaging section.

Custom Notification provides communication directly among the clients. And data or message is shared through it involving the cache as medium. As the data shared through custom event is not stored in cache, so there is no overhead of memory on cache.

Custom Notification is used in scenarios like when you want to raise the notification from the client application or you want to write logic of raising notification on client side rather than cache to decide when to raise notification.

One example for custom notification is that if there are multiple applications running and the discount price for a specific product is being changed on one application, then you can raise a custom event to notify other client applications about the updated discount price so that they can also update the discount price for that product.

Pre-Requisites for Regestering Custom Event Notifications

Include the following namespaces in your application:
- Alachisoft.NCache.Web.Caching
- 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.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Registering Custom Event Notification

Step 1: Register Custom Event

The user can create a custom event according to his/her requirements. This event needs to be registered with CustomEvent.

// Create a target method
public static void CacheCustomEvent(object notifId, object data)
{
  // Implement your custom business logic
}

Step 2: Register Custom Event Callback

The method then need to be registered with the CustomEevent event properly.

cache.CustomEvent += new CustomEventCallback(CacheCustomEvent);

Step 3: Raise Custom Event

NCache does not raise the custom events on its own, therefore in order to trigger it RaiseCustomEvent method needs to be called.

The following example registers the custom event and then raise it so that the event notifications can be triggered.

try
{
  // Get product from database against given product ID
  Product product = FetchProductFromDB(1001);

  // Generate a unique cache key for this product
  string key = $"Product:{product.ProductID}";

  // Registering custom event
  cache.CustomEvent += new CustomEventCallback(CacheCustomEvent);

  // Perform operation according to the business logic

  // Raise Custom event upon according to need.
  cache.RaiseCustomEvent(cacheName, product);
}
catch (OperationFailedException ex)
{
  // NCache specific exceptions:
  // Connection Failure
  // Operation Timeout
}
catch (Exception ex)
{
  // Any generic exception like ArgumentException, ArgumentNullException
}

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

Shipped Sample Code

For a full functioning .NET application executing events, you can use the sample shipped with NCache which is placed at:

.NET Framework: %NCHOME%\samples\dotnet\Events
.NET Core: %NCHOME%\samples\dotnetcore\Events
.NET JAVA: %NCHOME%\samples\java\Events