• Public
  • Public/Protected
  • All

Interface TopicNotifications

This feature allows a client session to receive notifications about changes to selected topics.


Sessions receive notifications via TopicNotificationListeners. The listener will be provided with the specifications for all topics bound to paths that match registered selectors, and any subsequent notifications for the selected topics on those paths, via onTopicNotificaion. Notifications will only be emitted for paths where a topic is bound.

For example, with a registered selector "?a//" , if a topic is added at path a/b/c/d with no topics bound to paths higher in the hierarchy onTopicNotification will be called once with a topic path of "a/b/c/d" , a notification type of ADDED, and the topic's associated TopicSpecification.

The nature of the notification is provided by the TopicNotificationType enum. ADDED and REMOVED represent structural changes to the topic tree; SELECTED indicates that a pre-existing topic has been selected by a new registered selector, and similarly DESELECTED indicates that a topic is no longer selected because of changes to the set of registered selectors for the listener.

Selection and deselection

Registered TopicNotificationListeners will receive notifications for all topics matching registered selections. Selection of topics using TopicSelector expressions is provided via the TopicNotificationRegistration associated for a specific listener.

A session 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.

Immediate descendant notifications

Listeners will be informed about the presence or absence of unselected immediate descendants via onDescendantNotification. This allows listeners to determine whether to select deeper topic paths in order to walk the topic tree. An immediate descendant is defined as the first bound topic on any branch below a given topic path.

For example, for topics at "a/b", "a/c", "a/c/d", "a/e/f/g" , the immediate descendants of "a"} would be "a/b", "a/c", "a/e/f/g" .

Immediate descendant notifications provide a TopicNotificationType to indicate the reason for the notification in the same manner as onTopicNotification.

For example, with a registered selector ">a" , if a topic is added at path a/b then onDescendantNotification will be called with a topic path of "a/b" and a notification type of ADDED. If a topic was subsequently added at path a/b/c , no further notifications will be received until TopicNotificationRegistration.select was used to select the deeper topic path ">a/b" .

Access control

A listener will only be notified about topics for which the session has SELECT_TOPIC and READ_TOPIC permissions. SELECT_TOPIC determines which selectors a listener may register; READ_TOPIC determines which selected topics the client may receive notifications for.

Accessing the feature

This feature may be obtained from a session as follows:

const notifications = session.notifications;


  • TopicNotifications






TopicNotificationType: TopicNotificationType

The topic notification type enum