This feature allows a client session to receive notifications about changes
to selected topics.
Notifications
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.
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" .
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:
This feature allows a client session to receive notifications about changes to selected topics.
Notifications
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 patha/b/c/dwith 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 patha/bthen onDescendantNotification will be called with a topic path of"a/b"and a notification type of ADDED. If a topic was subsequently added at patha/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;