Pub/Sub Topics

A Topic contains the message itself, along with additional subscriber and publisher information. The ITopic/Topic interface in Pub/Sub facilitates creating a Topic, set Topic priority while creation, get a Topic, delete a Topic simply, and asynchronously.

Prerequisites

Before using the NCache client-side APIs, ensure that the following prerequisites are fulfilled:

How to Create a Pub/Sub Topic in NCache

The CreateTopic method creates a Topic in the cache with a specified name. If the Topic already exists, an instance of the Topic is returned as ITopic. Whenever a message is published on a Topic, it is delivered based on subscriber preferences who are registered on that Topic. The following example creates a Topic orderTopic.

try
{
  // Precondition: Cache is already connected

  // Mention the name of the Topic
  string topicName = "orderTopic";

  // Create the Topic
  ITopic topic = cache.MessagingService.CreateTopic(topicName);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
    // Topic name is null/empty
}
Note

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

Create Topic with Priority

Note

This feature is only available in NCache 5.2 and onwards.

NCache Pub/Sub allows you to set Topic priority to prioritize the delivery of critical messages. Priority is specified using the TopicPriority property as Low, Normal, and High. In case eviction is enabled, the Topic with the lowest priority are evicted first, and the ones with the highest priority are evicted last. Topics created with no priority specified will be created with the default priority, i.e., Normal. The following example creates a Topic, orderTopic, with priority as high to avoid early eviction (if eviction is enabled).

Important

Priority of a Topic can be specified at the time of Topic creation only and cannot be modified afterwards.

// Precondition: Cache is already connected

// Mention the name of the Topic
string topicName = "orderTopic";

// Create the Topic with priority
ITopic topic = cache.MessagingService.CreateTopic(topicName, Alachisoft.NCache.Runtime.Messaging.TopicPriority.High);

Get Topic

The GetTopic method fetches an instance of the specified Topic from the cache. If the Topic exists, it is returned, otherwise an exception is thrown. The following example gets an existing Topic orderTopic from the cache.

// Precondition: Cache is already connected

// Mention the name of the Topic
string topicName = "orderTopic";

// Get the Topic from the cache
ITopic orderTopic = cache.MessagingService.GetTopic(topicName);

// Verify successful Topic retrieval
if (orderTopic != null)
{
    // orderTopic will be used for receiving and/or publishing messages
}
else
{
    // No Topic exists
}

Delete Topic

The DeleteTopic method unregisters the Topic from the cache and removes all messages associated with that Topic. If registered, a Topic deletion callback OnTopicDeleted will be triggered upon this method call. The following example deletes the existing Topic orderTopic from the cache and removes all messages associated with that Topic. If the OnTopicDeleted callback is registered, it will be triggered upon this method call.

// Precondition: Cache is already connected

// Define the Topic to be deleted
string topicName = "orderTopic";

// Delete the Topic "orderTopic"
cache.MessagingService.DeleteTopic(topicName);

// Callback will be triggered if registered

Delete Topic Asynchronously

The DeleteTopicAsync method deletes the Topic asynchronously. Whenever a Topic is deleted asynchronously, a Task is returned to the user for performing further tasks without waiting for the Topic to be deleted. The following example shows the asynchronous deletion of the Topic orderTopic.

// Precondition: Cache is already connected

// Define the Topic to be deleted
string topicName = "orderTopic";

// Delete the Topic "orderTopic"
Task task = cache.MessagingService.DeleteTopicAsync(topicName);

// Use task to perform further operations according to business logic
// Callback will be triggered if registered

Properties of ITopic Interface

Members Type Description
MessageDeliveryFailure MessageDeliveryFailureCallback Event on the Topic so that publisher receives all failed messages that are not delivered to any subscriber or maybe messages are expired or evicted before delivery.
Name string Name of the Topic specified during Topic creation.
OnTopicDeleted TopicDeletedCallback Event to handle Topic deletion by publisher and subscriber.
ExpirationTime TimeSpan If message level expiration is not provided, then this Topic level expiration expires messages in the Topic by default. The value is TimeSpan.MaxValue by default.
IsClosed bool Check whether Topic is disposed, before performing any operation.
Dispose IDisposable Removes registered Topic's subscription from cache server.

Additional Resources

NCache provides a sample application for Pub/Sub on GitHub.

See Also

.NET: Alachisoft.NCache.Runtime.Caching namespace.
Java: com.alachisoft.ncache.runtime.caching namespace.
Python: ncache.client.services class.
Node.js: Topic class.