Topic notifications enable a client to receive information about the topic tree structure, without
A client can receive notifications about changes to selected topics through the
topic notifications feature.
The client must use a topic notification listener to receive notifications. Use
topic selectors to specify which
topics the client will be notified about.
Selection and deselection
A client can request selections at any time, even if the topics do not exist at the server.
Selections are stored on the server and any subsequently added topics that match registered selectors
will generate notifications.
Each notification includes:
- The topic specification of the topic
- A notification type describing the change
Table 1. Notification types
||A new topic has been added matching a registered selector
||A selected topic has been removed
||A newly-registered selector matched a topic that already exists
||An existing topic is no longer selected due to a selector being removed
For example, suppose a topic tree contains only the topic a/b/c.
A listener registers the topic selector ?a//
which selects the topic a and all topics below it.
The listener will receive a notification containing the topic specification of the topic at
a/b/c, and the notification type SELECTED.
If a new topic is added at a/b/c/d, another
notification will be received with the specification of the new topic, and a notification type ADDED.
Immediate descendant notifications
Listeners receive notifications about whether each selected topic has unselected immediate descendants.
descendant means the first bound topic on any branch below a given topic path. By monitoring immediate
descendant notifications, you can implement a listener
which selects deeper topic paths as more topics are added, in order to walk the topic tree.
For example, in a topic tree which
contains only these topics:
The immediate descendants of a are a/b,
a/c and a/e/f/g.
a/c/d is not an immediate descendant of a,
because its parent a/c is a descendant of a.
Immediate descendant notifications provide the topic path and a notification type (with the same possible values as above).
In the example topic tree above, suppose that a topic notification listener had selected topic
a using the topic selector "a". If a topic is now added at
a/x, the listener receives an immediate descendant notification
with the path a/x and the notification type ADDED.
If a topic is then added at a/x/y, the listener does not receive
another notification, because a/x/y is not an immediate descendant.
Considerations when using topic notifications
Topic notifications are useful when your client needs to know which topics are present,
without the overhead of receiving the topic values. This can be useful when developing monitoring tools
or interfaces designed to browse large numbers of topics.
A client will only be notified about topics for which it has both
select_topic and read_topic permissions.
The select_topic permission is required to select a topic
with a listener. The read_topic permission is required to receive notifications for a topic.