Interface ITopicNotifications

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

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features.Control.Topics

Assembly: Diffusion.Client.dll

Syntax

public interface ITopicNotifications : IFeature

Remarks

Notifications

Sessions receive notifications through ITopicNotificationListener. The listener will be provided with the ITopicSpecification for all topics bound to paths that match registered selectors, and any subsequent notifications for the selected topics on those paths, via OnTopicNotification(String, ITopicSpecification, NotificationType). 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(String, ITopicSpecification, NotificationType) will be called once with a topic path of "a/b/c/d", a notification type of ADDED, and the topic's associated ITopicSpecification.

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 ITopicNotificationListener will receive notifications for all topics matching registered selections. Selection of topics using ITopicSelector expressions is provided by the INotificationRegistration 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(String, NotificationType). 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(String, ITopicSpecification, NotificationType).

For example, with a registered selector ">a", if a topic is added at path a/b then OnDescendantNotification(String, NotificationType) 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 SelectAsync(String) 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.

Added in version 6.0.

Methods

AddListenerAsync(ITopicNotificationListener)

Registers a listener to receive topic notifications.

Declaration

Task<INotificationRegistration> AddListenerAsync(ITopicNotificationListener listener)

Parameters

Type	Name	Description
ITopicNotificationListener	listener	The listener to receive topic specification notifications.

Returns

Type	Description
Task<INotificationRegistration>	The Task representing the current operation.

Remarks

If the operation completes successfully, the returned Task result will be a INotificationRegistration, which may be used to later close the listener and remove it from the server.

This method is the same as calling AddListenerAsync(ITopicNotificationListener, CancellationToken) with System.Threading.CancellationToken.None.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.

See Also

AddListenerAsync(ITopicNotificationListener, CancellationToken)

AddListenerAsync(ITopicNotificationListener, CancellationToken)

Registers a listener to receive topic notifications.

Declaration

Task<INotificationRegistration> AddListenerAsync(ITopicNotificationListener listener, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicNotificationListener	listener	The listener to receive topic specification notifications.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<INotificationRegistration>	The Task representing the current operation.

Remarks

If the operation completes successfully, the returned Task result will be a INotificationRegistration, which may be used to later close the listener and remove it from the server.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.