Interface ITopic

The ITopic 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.

Assembly: Alachisoft.NCache.Runtime.dll
Syntax
public interface ITopic : IDisposable

Properties

ExpirationTime

The default expiry time of messsage for the topic. Its default value is TimeSpan.MaxValue.

Declaration
TimeSpan ExpirationTime { get; set; }
Property Value
Type Description
System.TimeSpan

Time interval after which the message expires.

IsClosed

This property specifies whether the topic is closed or not?

Declaration
bool IsClosed { get; }
Property Value
Type Description
System.Boolean

Boolean value, either true or false.

MessageCount

Number of messages published for this topic.

Declaration
long MessageCount { get; }
Property Value
Type Description
System.Int64

Number of published messages.
Remarks

This property returns value for a specific topic. Count of other topics play no role.

Name

Specifies the topic's name.

Declaration
string Name { get; }
Property Value
Type Description
System.String

Name of the topic.

OnTopicDeleted

Topic deletion events are delivered through this callback.

Declaration
TopicDeletedCallback OnTopicDeleted { set; }
Property Value
Type Description
TopicDeletedCallback

Topic deletion events.
Remarks

You can use this event to perform the tasks when a topic is deleted. For more information on how to use this callback, see the documentation for TopicDeletedCallback.

Priority

Defines the relative priority of the topic.

Declaration
TopicPriority Priority { get; }
Property Value
Type Description
TopicPriority

Relative priority of the topic.

SearchOptions

Returns whether the user has subscribed to the pattern based or the simple subscription.

Declaration
TopicSearchOptions SearchOptions { get; }
Property Value
Type Description
TopicSearchOptions

Type of subscription.

Methods

CreateDurableSubscription(String, SubscriptionPolicy, MessageReceivedCallback, Nullable<TimeSpan>, DeliveryMode)

It creates a Durable subscription.

Declaration
IDurableTopicSubscription CreateDurableSubscription(string subscriptionName, SubscriptionPolicy subscriptionPolicy, MessageReceivedCallback messageReceivedCallback, TimeSpan? timespan = default(TimeSpan? ), DeliveryMode deliveryMode = DeliveryMode.Sync)
Parameters
Type Name Description
System.String subscriptionName

Name of the Subscription.
SubscriptionPolicy subscriptionPolicy

Subscription policy whether Shared or Exclusive.
MessageReceivedCallback messageReceivedCallback

Message is delivered through this callback.
System.Nullable<System.TimeSpan> timespan

An optional paramater that determines the expiration time.
DeliveryMode deliveryMode

An optional parameter which specifies whether to deliver messages to register subscribers synchronously or asynchronously. Default value of this parameter is Sync.
Returns
Type Description
IDurableTopicSubscription

Definition of the subscription created.

CreateSubscription(MessageReceivedCallback, DeliveryMode)

This method is used to register against a topic on the cache if a topic exists, otherwise throws exception.

Declaration
ITopicSubscription CreateSubscription(MessageReceivedCallback messageReceivedCallback, DeliveryMode deliveryMode = DeliveryMode.Sync)
Parameters
Type Name Description
MessageReceivedCallback messageReceivedCallback

The Message is delivered through this callback.

DeliveryMode deliveryMode

An optional parameter which specifies whether to deliver messages to register subscribers synchronously or asynchronously. Default value of this parameter is Sync.
Returns
Type Description
ITopicSubscription

It returns the created topic subscription.
Examples

The following example demonstrates how to create a subscription on a topic.

First, initialize the cache.

ICache cache = CacheManager.GetCache("myCache");

Then, get messaging service from the cache.

IMessagingService messagingService=cache.MessagingService;

Then, get topic from the messagingService.

ITopic topic=messagingService.GetTopic("mytopic");  
if(topic==null)  //If topic not exists create it.
{
  topic=messagingService.CreateTopic("mytopic");
}

Then, create the subscription.

void MessageReceivedCallback(object sender, MessageEventArgs args)
{

}

topic.CreateSubscription(MessageReceivedCallback);

Publish(Message, DeliveryOption, Boolean)

This method is used to publish the message in the cache with the specified DeliveryOption. And the option to notify the publisher if the message has failed to deliver because of expiration, eviction or internal system issue.

Declaration
void Publish(Message message, DeliveryOption deliverOption, bool notifyDeliveryFailure = false)
Parameters
Type Name Description
Message message

Message to be published.
DeliveryOption deliverOption

Specified delivery option.

System.Boolean notifyDeliveryFailure

Specifies if MessageDeliveryFailure event is required for this message.
Examples

The following example demonstrates how to publish message on a topic.

First, initialize the cache.

ICache cache = CacheManager.GetCache("myCache");

Then, get messaging service from the cache.

IMessagingService messagingService=cache.MessagingService;

Then, get the topic from the messagingService.

ITopic topic=messagingService.GetTopic("mytopic");  
if(topic==null)  //If topic not exists create it.
{
  topic=messagingService.CreateTopic("mytopic");
}

Then, publish the message on the topic.

object payload = "mymessage"; 
Message message = new Message(payload);   //creating message
topic.Publish(message, DeliveryOption.All);

Publish(Message, DeliveryOption, String, Boolean)

This method is used to publish the message in the cache with the specified DeliveryOption and the SequenceName. The order of messages with the same sequence name is retained. And the option to notify the publisher if the message has failed to deliver because of expiration, eviction or internal system issue.

Declaration
void Publish(Message message, DeliveryOption deliverOption, string sequenceName, bool notifyDeliveryFailure = false)
Parameters
Type Name Description
Message message

Message to be published.
DeliveryOption deliverOption

Delivery Option.

System.String sequenceName

Sequence name of the message to be publsihed. The messages with same sequence name will be delivered in the same order as they are published.
System.Boolean notifyDeliveryFailure

Specifies if MessageDeliveryFailure event required for the specified message.
Examples

The following example demonstrates how to publish message on a topic.

First, initialize the cache.

ICache cache = CacheManager.GetCache("myCache");

Then, get the messaging service from the cache.

IMessagingService messagingService=cache.MessagingService;

Then, get the topic from the messagingService.

ITopic topic=messagingService.GetTopic("mytopic");  
if(topic==null)  //If topic not exists create it.
{
  topic=messagingService.CreateTopic("mytopic");
}

Then, publish the message on the topic.

object payload = "mymessage"; 
string sequenceName = "myOrderedMessages";
Message message = new Message(payload);   //creating message
topic.Publish(message, DeliveryOption.All, sequenceName);

PublishAsync(Message, DeliveryOption, Boolean)

This method is used to publish a message asynchronously in the cache with the specified DeliveryOption and the option to notify the publisher if the message has failed to deliver because of expiration, eviction or internal system issue.

Declaration
Task PublishAsync(Message message, DeliveryOption deliverOption, bool notifyDeliveryFailure = false)
Parameters
Type Name Description
Message message

Message to be published.
DeliveryOption deliverOption

Specifies delivery option.

System.Boolean notifyDeliveryFailure

Specifies whether the MessageDeliveryFailure event required for this message.
Returns
Type Description
System.Threading.Tasks.Task

Returns the Task.
Examples

The following example demonstrates how to publish a message asynchronously on a topic.

First, initialize the cache.

ICache cache = CacheManager.GetCache("myCache");

Then, get messaging service from the cache.

IMessagingService messagingService=cache.MessagingService;

Then, get topic from the messagingService.

ITopic topic=messagingService.GetTopic("mytopic");  
if(topic==null)  //If topic not exists create it.
{
  topic=messagingService.CreateTopic("mytopic");
}

Then, publish message on the topic.

object payload = "mymessage"; 
Message message = new Message(payload);   //creating message
topic.PublishAsync(message, DeliveryOption.All).ContinueWith(task => 
{
    if (task.Status == TaskStatus.RanToCompletion)
    {
        Console.WriteLine("Message Published Successfully");
    }
    if (task.Status == TaskStatus.Faulted)
    {
        Console.WriteLine("Error has occurred");
    }
    if (task.Exception != null)
    {
        Console.WriteLine(task.Exception);
    }
});

PublishBulk(IEnumerable<Tuple<Message, DeliveryOption>>, Boolean)

Declaration
IDictionary<Message, Exception> PublishBulk(IEnumerable<Tuple<Message, DeliveryOption>> messages, bool notifyDeliveryFailure = false)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<System.Tuple<Message, DeliveryOption>> messages
System.Boolean notifyDeliveryFailure
Returns
Type Description
System.Collections.Generic.IDictionary<Message, System.Exception>

Events

MessageDeliveryFailure

Subscribes for message delivery failure events.

Declaration
event MessageDeliveryFailureCallback MessageDeliveryFailure
Event Type
Type Description
MessageDeliveryFailureCallback

Failure notification to any publisher which has registered a message delivery failure event on that topic.
Remarks

You can use this event to perform tasks when message delivery fails. For more information on how to use this callback see the documentation for MessageDeliveryFailureCallback.