Notification management

Brief description

The Kaa Notifications subsystem enables messages delivery from the Kaa cluster to endpoints (EP). It is based on auto-generated classes according to the topic's notification schema used during SDK generation.

Notification topics can be mandatory or optional. Mandatory topic notifications are delivered in an enforced manner. Optional topics require subscription. It is the responsibility of the client code to register the topic update listener and subscribe to optional topics.

Topics - usage examples

Access to available topics

using namespace kaa;

/*
 * Kaa initialization
 */

IKaaClient& kaaClient = Kaa::getKaaClient();
INotificationManager& notificationManager = kaaClient.getNotificationManager();
const auto& topics = notificationManager.getTopics();

for (const auto it : topics) {
    std::cout << "Id: " << it.first << ", name: " << it.second.name
              << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(
                      it.second.subscriptionType) << std::endl;
}

Updates of available topics

If there is need to receive updates of available topic, do following:

#include "kaa/notification/INotificationTopicListListener.hpp"

class BasicTopicUpdateListener : public INotificationTopicListListener {
public:
    // Will be called on each update of the topic list 
    virtual void onListUpdated(const Topics& newList) {
        for (const auto topic : newList) {
            std::cout << "Id: " << topic.id << ", name: " << topic.name
                      << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(
                              topic.subscriptionType) << std::endl;
        }
    }
};
...
// Create and subscribe listener to receive topic list updates
INotificationTopicListListenerPtr topicUpdateListener(new BasicTopicUpdateListener);
notificationManager.addTopicListListener(topicUpdateListener);
...
// Remove topic update listener
notificationManager.removeTopicListListener(topicUpdateListener);

Notifications - usage examples

In order to receive notifications, both mandatory or optional, at least one listener should be added. A particular listener may be added for a specified topic as well.

Assume, notification schema has the following form:

{
    "type": "record",
    "name": "BasicNotification",
    "namespace": "org.kaaproject.kaa.client.example",
    "fields": [
        {
            "name": "body",
            "type": "string"
        }
    ]
}

After calling avrogen.sh script Avro C++ compiler will be generated appropriate code and put it into NotificationGen.hpp header. So auto-generated notification class will be like:

struct BasicNotification {
    std::string body;
};

As mentioned earlier, there is two kind of topics - mandatory and optional. Further it will be discussed dealing with both of them.

Topic notification listener(s)

In order to receive notifications from all available topics (both mandatory and subscribed optional), do following:

#include "kaa/gen/NotificationGen.hpp" // auto-generated header
#include "kaa/notification/AbstractNotificationListener.hpp"

class BasicNotificationListener : public AbstractNotificationListener<BasicNotification> {
    virtual void onNotification(const std::string& id, const BasicNotification& notification) {
        std::cout << "Received notification with body: " << notification.body << std::endl;
    }
};
...
INotificationListenerPtr globalNotificationListener(new BasicNotificationListener);

// Add listener
notificationManager.addNotificationListener(globalNotificationListener);

...

// Remove listener
notificationManager.removeNotificationListener(globalNotificationListener);

Topic specific listener(s)

To add listener(s) for a specified topic, do following:

#include "kaa/gen/NotificationGen.hpp" // auto-generated header
#include "kaa/notification/AbstractNotificationListener.hpp"

class WheatherNotificationListener : public AbstractNotificationListener<BasicNotification> {
    virtual void onNotification(const std::string& id, const BasicNotification& notification) {
        std::cout << "What's weather: " << notification.body << std::endl;
    }
};

class NewsNotificationListener : public AbstractNotificationListener<BasicNotification> {
    virtual void onNotification(const std::string& id, const BasicNotification& notification) {
        std::cout << "What's news: " << notification.body << std::endl;
    }
};

// Add specific listeners both for news and weather topics
INotificationListenerPtr weatherTopicListener(new WheatherNotificationListener);
INotificationListenerPtr newsTopicListener(new NewsNotificationListener);

// Add listener
notificationManager.addNotificationListener("wheather_topic_id", weatherTopicListener);
notificationManager.addNotificationListener("news_topic_id", newsTopicListener);

...

// Remove listener
notificationManager.removeNotificationListener("wheather_topic_id", weatherTopicListener);
notificationManager.removeNotificationListener("news_topic_id", newsTopicListener);

Optional topic (un)subscription

To receive notifications relating to some optional topic, firstly you should to subscribe to this topic:

notificationManager.subscribeToTopic("optional_topic_id", true);

Unsubscription:

notificationManager.unsubscribeFromTopic("optional_topic_id", true);

There is a similar stuff to deal with a group of optional topics - kaa::INotificationManager::subscribeToTopics() and kaa::INotificationManager#unsubscribeFromTopics() .

Performance

To increase Kaa performance in case of several subsequent subscription changes and avoid possible race conditions, we recommend to use following approach:

// Make subscription changes with parameter forceSync set to false
notificationManager.subscribeToTopics({"optional_topic1", "optional_topic2", "optional_topic3"}, false);
notificationManager.unsubscribeFromTopic("optional_topic4", false);

// Add listener(s) (optional)

// Commit changes
notificationManager.sync();