com.pushtechnology.diffusion.client.features.control.topics

Interface TopicNotifications

All Superinterfaces:

Feature

public interface TopicNotifications
extends Feature

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 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

Registered TopicNotificationListeners 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 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 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 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.

Since:

6.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TopicNotifications.NotificationRegistration The NotificationRegistration represents the registration state of the associated listener on the server.
static interface	TopicNotifications.TopicNotificationListener Listener for topic notifications.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<TopicNotifications.NotificationRegistration>	addListener(TopicNotifications.TopicNotificationListener listener) Register a listener to receive topic notifications.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

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 the cause, include:

• SessionClosedException – if the session is closed.