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;
INotificationManager& notificationManager = kaaClient.getNotificationManager();
const auto& topics = notificationManager.getTopics();
for (const auto it : topics) {
std::cout << "Id: " << it.first << ", name: " << it.second.name
it.second.subscriptionType) << std::endl;
}
Updates of available topics
If there is need to receive updates of available topic, do following:
class BasicTopicUpdateListener : public INotificationTopicListListener {
public:
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;
}
}
};
...
INotificationTopicListListenerPtr topicUpdateListener(new BasicTopicUpdateListener);
notificationManager.addTopicListListener(topicUpdateListener);
...
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"
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);
notificationManager.addNotificationListener(globalNotificationListener);
...
notificationManager.removeNotificationListener(globalNotificationListener);
Topic specific listener(s)
To add listener(s) for a specified topic, do following:
#include "kaa/gen/NotificationGen.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;
}
};
INotificationListenerPtr weatherTopicListener(new WheatherNotificationListener);
INotificationListenerPtr newsTopicListener(new NewsNotificationListener);
notificationManager.addNotificationListener("wheather_topic_id", weatherTopicListener);
notificationManager.addNotificationListener("news_topic_id", newsTopicListener);
...
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:
notificationManager.subscribeToTopics({"optional_topic1", "optional_topic2", "optional_topic3"}, false);
notificationManager.unsubscribeFromTopic("optional_topic4", false);
notificationManager.sync();