Publish Messages to Topic

The ITopic/Topic interface facilitates creating subscription and publishing of messages against the topic. This also provides event registrations for message delivery failure, receiving messages and deleting topics.

It provides the Publish method which publishes the message to a specific topic in the cache. It allows the user to specify the message delivery option using an enum DeliveryOption which has two options:

All (1): Delivers message to all the registered subscribers.
Any (0): Delivers the message to any one of the registered subscribers.

Moreover, it allows the publisher to get notified if the message has failed to deliver because of any issue using the NotifyDeliveryFailure flag.

Note

To use Maven packages for NCache Professional Edition, change the <artifactId> as shown below:
- <artifactId>ncache-professional-client</artifactId>
To use Node.js API in NCache Professional Edition, install and include the ncache-professional-client npm package in your Node.js application.

Pre-Requisites

Install the following NuGet packages in your application:
- Alachisoft.NCache.SDK
Include the following namespace in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime
- 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, ITopic, Publish, GetTopic.
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.*;
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, Topic, getTopic.
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, getTopic, deleteTopic.
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.

The following code sample does the following:

Create dedicated topics for Order related messages.
Register MessageDeliveryFailure event for topic.
Register OnTopicDeleted event for topic.
Create messages for each topic, enabling expiration and delivery options.
Publish the messages.

try
{
    // Pre-Condition: Cache is already connected

    // Topic "orderTopic" exists in cache
    string topicName = "orderTopic";

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

    if (orderTopic != null)
    {
        // Create the object to be sent in message
        Order order = FetchOrderFromDB(10248);

        // Create the new message with the object order
        var orderMessage = new Message(order);

        // Set the expiration time of the message
        orderMessage.ExpirationTime = TimeSpan.FromSeconds(5000);

        // Register message delivery failure
        orderTopic.MessageDeliveryFailure += OnFailureMessageReceived;

        //Register topic deletion notification
        orderTopic.OnTopicDeleted = TopicDeleted;

        // Publish the order with delivery option set as all
        // and register message delivery failure
        orderTopic.Publish(orderMessage, DeliveryOption.All, true);
    }
    else
    {
        // No topic exists
    }
}
catch (OperationFailedException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS)
    {
        // Message ID already exists, specify a new ID
    }
    if (ex.ErrorCode == NCacheErrorCodes.TOPIC_DISPOSED)
    {
        // Specified topic has been disposed 
    }
    if (ex.ErrorCode == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED)
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    }
    else
    {
        // 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
}

try 
{
    // Precondition: Cache is already connected

    // Already existing topic
    String topicName = "orderTopic";

    // Get topic
    Topic orderTopic = cache.getMessagingService().getTopic(topicName);

    if (topicName != null) {
        // Create object to be sent in the message
        Order order = fetchOrdersFromDB(1100);

        // Create new message
        Message orderMessage = new Message(order);

        TimeSpan expiryTime = new TimeSpan(12, 12, 12);
        // Set expiration time of the message
        orderMessage.setExpirationTime(expiryTime);

        // Register message delivery failure
        MyTopicListener topicListener = new MyTopicListener();
        orderTopic.addMessageDeliveryFailureListener(topicListener);
        orderTopic.addTopicDeletedListener(topicListener);

        // Publish the order with delivery option set as All
        // and register message delivery failure
        orderTopic.publish(orderMessage, DeliveryOption.All, true);
    } 
    else 
    {
        // No topic exists
    }
} 
catch (OperationFailedException exception) 
{
    if (exception.getErrorCode() == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS) 
    {
        // Message ID already exists. Specify a new ID
    }
    if (exception.getErrorCode() == NCacheErrorCodes.TOPIC_DISPOSED) 
    {
        // Specified topic has been disposed
    }
    if (exception.getErrorCode() == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED) 
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    } 
    else 
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

// This is an async method
try 
{
    // Precondition: Cache is already connected 

    // Topic "orderTopic" exists in the cache
    let topicName = "orderTopic";

    // Get the topic
    let orderTopic = await ncache.getMessagingService().getTopic(topicName);

    if (!(orderTopic == null)) 
    {
        // Create object to be sent in message 
        let order = await this.fetchOrdersFromDb(this.orderId);

        // Create a new message with the object order 
        let orderMessage = new ncache.Message(order);

        // Set the expiration time of the message 
        let expiryTime = new ncache.TimeSpan(12, 12, 12);
        orderMessage.setExpirationTime(expiryTime);

        let topicListener = new ncache.MyTopicListener;

        // Register message delivery failure
        orderTopic.addMessageDeliveryFailureListener(topicListener);

        // Register topic deletion notification 
        orderTopic.addTopicDeletedListener(topicListener);

        // Publish the order with delivery option set as All
        // and register message delivery failure
        orderTopic.publish(orderMessage, ncache.DeliveryOption.All, true);
    }
    else 
    {
        // No topic exists
    }
} 
catch (error) 
{
    // Handle any errors
}

Publish Asynchronously

Note

This feature is only available from NCache 5.0 SP2 onwards.

PublishAsync lets you publish the messages on the topic asynchronously so that the application does not wait for the operation completion for the next operation. The user has the control returned to him immediately for further processing.

The following example lets you publish a message asynchronously.

.NET/.NET Core
Java

try
{
    // Pre-Condition: Cache is already connected

    // Topic "orderTopic" exists in cache
    string topicName = "orderTopic";

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

    if (orderTopic != null)
    {
        // Create the object to be sent in message
        Order order = FetchOrderFromDB(10248);

        // Create the new message with the object order
        var orderMessage = new Message(order);

        // Set the expiration time of the message
        orderMessage.ExpirationTime = TimeSpan.FromSeconds(5000);

        // Register message delivery failure
        orderTopic.MessageDeliveryFailure += OnFailureMessageRecieved;

        //Register topic deletion notification
        orderTopic.OnTopicDeleted = TopicDeleted;

        // Publish the order with delivery option set as all
        // and register message delivery failure
        Task task = orderTopic.PublishAsync(orderMessage, DeliveryOption.All, true);

        if(task.IsFaulted)
        {
            // Task Failed
        }
    }
    else
    {
        // No topic exists
    }
}
catch (OperationFailedException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS)
    {
        // Message ID already exists, specify a new ID
    }
    if (ex.ErrorCode == NCacheErrorCodes.TOPIC_DISPOSED)
    {
        // Specified topic has been disposed 
    }
    if (ex.ErrorCode == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED)
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    }
    else
    {
        // 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
}

try 
{
    // Precondition: Cache is connected

    // Topic orderTopic already exists in the cache
    String topicName = "orderTopic";

    // Get the topic
    Topic orderTopic = cache.getMessagingService().getTopic(topicName);

    if (orderTopic != null) 
    {
        // Create object to be sent in the message
        Order order = fetchOrdersFromDB(1100);

        // Create new message
        Message orderMessage = new Message(order);

        TimeSpan expiryTime = new TimeSpan(12, 12, 12);
        // Set expiration time of the message
        orderMessage.setExpirationTime(expiryTime);

        // Register message delivery failure
        MyTopicListener topicListener = new MyTopicListener();
        orderTopic.addMessageDeliveryFailureListener(topicListener);
        orderTopic.addTopicDeletedListener(topicListener);

        // Publish the order with delivery option set as All
        // and register message delivery failure
        TimeScheduler.Task task = (TimeScheduler.Task) orderTopic.publishAsync(orderMessage, DeliveryOption.All, true);

        if (task.IsCancelled()) 
        {
            // task cancelled
        }

    } 
    else 
    {
        // No topic exists
    }
} 
catch (OperationFailedException exception) 
{
    if (exception.getErrorCode() == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS) 
    {
        // Message ID already exists. Specify a new one
    }
    if (exception.getErrorCode() == NCacheErrorCodes.TOPIC_DISPOSED) 
    {
        // OrderTopic does not exist
    }
    if (exception.getErrorCode() == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED) 
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    } 
    else 
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

Publish Bulk Messages

Note

This feature is only available from NCache 5.0 SP2 onwards.

NCache now lets you publish a multiple number of messages in a single call using the PublishBulk method. This improves the performance and memory usage as a bulk of messages will be combined and published in a single call.

The code below takes an instance of an already created topic orderTopic and shows the bulk publishing of messages on the topic.

try
{    
    // Pre-Condition: Cache is already connected

    // Topic "orderTopic" exists in cache
    ITopic topic = cache.MessagingService.GetTopic("orderTopic");

    if (topic != null)
    {
        // create dictionary for storing bulk
        List<Tuple<Message, DeliveryOption>> messageList = new List<Tuple<Message, DeliveryOption>>();
        Order[] orders = FetchOrdersFromDB();
            for (int i = 0; i < 100; i++)
        {
            Message message = new Message(orders[i]);
            message.ExpirationTime = TimeSpan.FromSeconds(10000);
            messageList.Add(new Tuple<Message, DeliveryOption>(message, DeliveryOption.All));
        }
        // Register message delivery failure
        topic.MessageDeliveryFailure += OnFailureMessageRecieved;

        //Register topic deletion notification
        topic.OnTopicDeleted = TopicDeleted;

        // Publish the order with delivery option set as all
        // and register message delivery failure
        // In case of failed publishing of messages, exceptions
        // will be returned
        IDictionary<Message, Exception> keys = topic.PublishBulk(messageList, true);
    }
}
catch (OperationFailedException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS)
    {
        // Message ID already exists, specify a new ID
    }
    if (ex.ErrorCode == NCacheErrorCodes.TOPIC_DISPOSED)
    {
        // Specified topic has been disposed 
    }
    if (ex.ErrorCode == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED)
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    }
    else
    {
        // 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
}

try {
    // precondition: cache is connected

    // topic already exists
    String topicName = "orderTopic";
    String customerID = "DUMON";
    Topic topic = cache.getMessagingService().getTopic(topicName);

    if (topic != null) 
    {
        // create dictionary for storing bulk
        Map messageMap = new HashMap();

        Order[] orders = fetchOrdersFromDb(customerID);

        for (int i = 0; i < 100; i++) 
        {
            Message message = new Message(orders[i]);
            message.setExpirationTime(TimeSpan.FromSeconds(10000));
            messageMap.put(message, DeliveryOption.All);
        }
        MyTopicListener topicListener = new MyTopicListener();

        // Register message delivery failure
        topic.addMessageDeliveryFailureListener(topicListener);

        // Register topic deletion notification
        topic.addTopicDeletedListener(topicListener);

        Map<Message, Exception> keys = topic.publishBulk(messageMap, true);
    } 
    else 
    {
        // topic is null
    }
} 
catch (OperationFailedException exception) 
{
    if (exception.getErrorCode() == NCacheErrorCodes.MESSAGE_ID_ALREADY_EXISTS) 
    {
        // Message ID already exists. Specify a new one
    }
    if (exception.getErrorCode() == NCacheErrorCodes.TOPIC_DISPOSED) 
    {
        // Specified topic has been disposed
    }
    if (exception.getErrorCode() == NCacheErrorCodes.PATTERN_BASED_PUBLISHING_NOT_ALLOWED) 
    {
        // Message publishing on pattern based topic is not allowed
        // Get non-pattern based topic
    } 
    else 
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
} 
catch (Exception exception) 
{
    // Any generic exception
}

// This is an async method
try 
{
    // Precondition: Cache is already connected

    // Topic "orderTopic" exists in the cache
    let topicName = "orderTopic";

    // Get the topic
    let topic = ncache.getMessagingService().getTopic(topicName);

    if (topic != null) 
    {
        // Create Map for storing messages in bulk
        let messageMap = new Map();

        let orders = this.fetchOrdersByCustomerId(this.customerId);
        var i;
        for (i = 0; i < 100; i++)
        {
            let message = new ncache.Message(orders[i]);
            message.setExpirationTime(ncache.TimeSpan.FromSeconds(10000));
            messageMap.set(message, ncache.DeliveryOption.All);
        }
        let topicListener = new ncache.TopicListener();

        // Register message delivery failure 
        topic.addMessageDeliveryFailureListener(topicListener);

        // Register topic deletion notification 
        topic.addTopicDeletedListener(topicListener);

        // Publish the order with delivery option set as All
        // and register message delivery failure 
        // In case of failed publishing of messages, exception will be returned
        let keys = topic.publishBulk(messageMap, true);
    }
    else 
    {
        // No topic exists
    }
} 
catch (error) 
{
    // Handle any errors
}

Publish Ordered Messages

Note

This feature is only available in NCache 5.1 and onward.

Messages can be published by mentioning a sequence name resulting in publishing the messages in a specific order. In order to specify ordered messages, a string sequence name is added with the chain of the messages which makes sure to publish all the messages belonging to a specific sequence name on the same server node.

In the example given below, sequence name is added with the messages and the messages are then published using the Publish method.

try
{
    // Pre-condition: Cache is already connected

    // Specify the topic name that already exists
    string topicName = "orderTopic";
    // Get the topic with the specified name
    ITopic orderTopic = cache.MessagingService.GetTopic(topicName);
    if (topicName != null)
    {
        for (int i = 0; i < 30; i++)
        {
            // Create the object to be sent in message
            Order order = FetchOrderFromDB(10248);

            // Create the new message with the object order
            var orderMessage = new Message(order);

            // Specify a unique sequence name for the messages
            string sequenceName = "OrderMessages";

            // Set the expiration time of the message
            orderMessage.ExpirationTime = TimeSpan.FromSeconds(5000);

            // Publish message with the sequence name
            orderTopic.Publish(orderMessage, DeliveryOption.All, sequenceName, true);
        }
    }
    else
    {
        // No topic found
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

try 
{
    // Precondition: Cache is already connected

    // Specify the topic name that already exists
    String topicName = "orderTopic";

    // Get the topic with the specified name
    Topic orderTopic = cache.getMessagingService().getTopic(topicName);

    if (topicName != null) 
    {
        for (int i = 0; i < 30; i++) 
        {
            // Create the object to be sent in the message
            Order order = fetchOrdersFromDB(10248);

            // Create the new message with the object order
            var orderMessage = new Message(order);

            // Specify a unique sequence name for the message
            String sequenceName = "OrderMessage";

            // Set the expiration time of the message
            orderMessage.setExpirationTime(TimeSpan.FromSeconds(5000));

            // Publish message with the sequence name
            orderTopic.publish(orderMessage, DeliveryOption.All, sequenceName, true);
        }
    } 
    else 
    {
        // No topic found
    }
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
} 
catch (Exception exception) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

// This is an async method
try 
{
    // Precondition: Cache is already connected

    // Specify the topic name that already exists
    let topicName = "orderTopic";

    // Get the topic with the specified name
    let orderTopic = await this.cache.getMessagingService().getTopic(topicName);

    if (topicName != null) 
    {
        var i;
        for (i = 0; i < 30; i++) 
        {
            // Create the object to be sent in the message
            let order = await this.fetchOrderFromDB(10248);

            // Create the new message with the object order
            var orderMessage = new ncache.Message(order);

            // Specify a unique sequence name for the message
            let sequenceName = "OrderMessage";

            // Set the expiration time of the message
            orderMessage.setExpirationTime(ncache.TimeSpan.FromSeconds(5000));

            // Publish message with the sequence name
            orderTopic.publish(orderMessage, ncache.DeliveryOption.All, sequenceName, true);
        }
    } 
    else 
    {
        // No topic found
    }
} 
catch (error) 
{
    // Handle any errors
}

Register Callbacks

private void OnFailureMessageReceived(object sender, MessageFailedEventArgs args)
{
    // Failure reason can be get from args.MessageFailureReason
}

private void TopicDeleted(object sender, TopicDeleteEventArgs args)
{
    // Deleted topic is args.TopicName
}

@Override
public void onTopicDeleted(Object sender, TopicDeleteEventArgs args) 
{
    // Deleted topic is args.getTopicName();
}

@Override
public void onMessageDeliveryFailure(Object sender, MessageFailedEventArgs args)
{
    // Failure reason is args.getMessageFailureReason();
}

@Override
public void onMessageReceived(Object sender, MessageEventArgs args) 
{
    // Perform operations
}

onTopicDeleted(sender, args)
{
    // Deleted topic is args.getTopicName()
}

onMessageDeliveryFailure(sender, args)
{
    // Failure reason is args.getMessageFailureReason()
}

onMessageReceived(sender, args)
{
    // Perform operations
}

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

NCache provides sample application for Pub/Sub on GitHub.

Publish Messages to Topic

Note

Publish Asynchronously

Note

Publish Bulk Messages

Note

Publish Ordered Messages

Note

Register Callbacks

Additional Resources

See Also