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.

Notification contents

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.

An immediate 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:

• a
• a/b
• a/c
• a/c/d
• a/e/f/g

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.