Interface TopicNotifications
- All Superinterfaces:
Feature
Notifications
Sessions receive notifications viaTopicNotificationListener
s. 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
NotificationType
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
RegisteredTopicNotificationListeners
will receive notifications for all topics
matching registered selections. Selection of topics using
TopicSelector
expressions is provided via the
TopicNotifications.NotificationRegistration
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 viaonDescendantNotification
. 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
NotificationType
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 TopicNotifications.NotificationRegistration.select(com.pushtechnology.diffusion.client.topics.TopicSelector)
was used to select the deeper topic path ">a/b"
.
Access control
A listener will only be notified about topics for which the session hasSELECT_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.- Since:
- 6.0
- Author:
- DiffusionData Limited
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
The NotificationRegistration represents the registration state of the associated listener on the server.static interface
Listener for topic notifications. -
Method Summary
Modifier and TypeMethodDescriptionRegister a listener to receive topic notifications.Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature
getSession
-
Method Details
-
addListener
CompletableFuture<TopicNotifications.NotificationRegistration> addListener(TopicNotifications.TopicNotificationListener listener) Register a listener to receive topic notifications.- Parameters:
listener
- the listener to receive topic specification notifications- Returns:
- A completable future providing the registration state
If the registration completes successfully, the CompletableFuture result will be a
TopicNotifications.NotificationRegistration
, which may be used to later close the listener and remove it from the server.Otherwise, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include:SessionClosedException
– if the session is closed.
-