Interface ITopics

This feature allows a client session to subscribe to topics to receive streamed topic updates, fetch the state of topics and/or update topics with new values.

Inherited Members

ITopicViews.CreateTopicViewAsync(String, String)

ITopicViews.CreateTopicViewAsync(String, String, CancellationToken)

ITopicViews.ListTopicViewsAsync()

ITopicViews.ListTopicViewsAsync(CancellationToken)

ITopicViews.GetTopicViewAsync(String)

ITopicViews.GetTopicViewAsync(String, CancellationToken)

ITopicViews.RemoveTopicViewAsync(String)

ITopicViews.RemoveTopicViewAsync(String, CancellationToken)

ITopicUpdate.SetAsync<TValue>(String, TValue)

ITopicUpdate.SetAsync<TValue>(String, TValue, CancellationToken)

ITopicUpdate.SetAsync<TValue>(String, TValue, IUpdateConstraint)

ITopicUpdate.SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, CancellationToken)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint, CancellationToken)

ITopicUpdate.CreateUpdateStream<TValue>(String)

ITopicUpdate.CreateUpdateStream<TValue>(String, IUpdateConstraint)

ITopicUpdate.CreateUpdateStream<TValue>(String, ITopicSpecification)

ITopicUpdate.CreateUpdateStream<TValue>(String, ITopicSpecification, IUpdateConstraint)

ITopicUpdate.NewUpdateStreamBuilder()

ITopicUpdate.ApplyJSONPatchAsync(String, String)

ITopicUpdate.ApplyJSONPatchAsync(String, String, CancellationToken)

ITopicUpdate.ApplyJSONPatchAsync(String, String, IUpdateConstraint)

ITopicUpdate.ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features

Assembly: Diffusion.Client.dll

Syntax

public interface ITopics : ITopicViews, ITopicUpdate, IFeature

Remarks

Specifically, the feature provides the ability to:

• Subscribe to topics and specify streams to receive updates.
• Fetch the current state of topics (even if not subscribed).
• By extending the ITopicUpdate feature, update topics with new values.
• By extending the ITopicViews feature, manage topic views.

Subscription and unsubscription

A session can issue requests to subscribe to topics at any time, even if the topics do not exist at the server. Each subscription request provides a ITopicSelector that is evaluated by the server to select matching topics. The session will be subscribed to any topics that match the selector unless they are already subscribed, or the session has insufficient permission. The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

Sessions receive notifications from topics that they are subscribed to via subscription streams (see below). When a session is subscribed to a topic, all matching streams will first receive a subscription notification that provides details about the topic. If the server has a value for the topic, the value will be delivered to the streams before any other notifications.

A session can unsubscribe from topics at any time. This is also specified using a topic selector. On unsubscription, matching streams are notified via the OnUnsubscription(String, ITopicSpecification, TopicUnsubscribeReason) notification. This notification will give the reason for unsubscription (for example, by request of the session, request of the server, or topic removal).

Subscriptions and unsubscriptions can occur for reasons other than requests from the session. A session can be subscribed to or unsubscribed from a topic by another session using the ISubscriptionControl feature. The removal of a topic also automatically causes unsubscription for subscribed sessions.

Subscription requests are subject to authorization checks. The session must have SELECT_TOPIC permission for the topic selector used to subscribe. Matching topics will be further filtered to those for which the session has READ_TOPIC permission.

Subscription streams

A session can listen to subscription events and updates for a selection of topics by adding one or more streams. A stream is registered using a topic selector which specifies the topics that the stream applies to. When an update is received for a topic then it will be routed to every stream that matches both the topic selector and the stream's value type. If more than one stream matches, all will receive the update; the order in which they are notified is not defined.

A stream can be added several times for different selectors. If the same stream (determined by object.Equals(object)) is registered for several selectors that match an event, the stream will only be notified of the event once. The mapping of topic selectors to streams is maintained locally in the client process.

It is also possible to add one or more fallback streams which will receive updates that do not match any stream registered with a selector. This is useful for default processing or simply to catch unprocessed updates. A fallback stream can be added using AddFallbackStream<TValue>(IValueStream<TValue>). Zero, one, or more fallback streams may be assigned. If no fallback stream is specified, any updates that are not routed to any other stream will simply be discarded.

If the session is already subscribed to a topic when a matching stream is added, the stream will immediately receive a subscription notification. For most topic types, the latest value is locally cached and will be provided to the stream following the subscription notification.

A stream will receive an OnClose() callback when unregistered and an OnError(ErrorReason)) callback with a SESSION_CLOSED reason, if the session is closed.

Value streams

A IValueStream<TValue> receives values for matching topics as and when updates are received from the server. Delta updates received from the server are automatically applied to locally cached values so that the stream always receives full values for each update.

Value streams are typed to a specified value class and only updates for compatible topics will be routed to the stream. The following table shows how the value class maps to compatible topic types that will be routed to the stream:

Value Class	Compatible Topic Types
IJSON	JSON, STRING, INT64, DOUBLE
string	STRING
long	INT64
double	DOUBLE
IBinary	BINARY
IBytes	JSON, STRING, INT64, DOUBLE, BINARY, RECORD_V2
IRecordV2	RECORD_V2

Value stream implementations can be added using AddStream<TValue>(String, IValueStream<TValue>).

A value stream can be added to received updates from ITimeSeries topics using AddTimeSeriesStream<TValue>(String, IValueStream<IEvent<TValue>>). The following table shows how the value class specified when adding the stream maps to the event value class of time series topics that will be routed to the stream:

Value Class	Compatible Topic Types
IJSON	JSON, STRING, INT64, DOUBLE
string	STRING
long	INT64
double	DOUBLE
IBinary	BINARY
IBytes	JSON, STRING, INT64, DOUBLE, BINARY, RECORD_V2
IRecordV2	RECORD_V2

Fetch

A session can issue a request to fetch details of a topic or topics (subject to authorization) at any time. The topics required are specified using a topic selector.

The results of a fetch will return the topic path and type of each selected topic. The results may also optionally return the topic values and/or properties.

A new request can be created using FetchRequest and modified to specify additional requirements of the fetch operation. The request is issued to the server using the FetchAsync(String) method on the request. This will return the results via a Task.

Access control

A session must have SELECT_TOPIC permission for the path prefix of the topic selector used to subscribe to fetch. The topics that result from a subscription or fetch request are further filtered using the READ_TOPIC permission.

The READ_TOPIC permission is required to retrieve the topic details.

No access control restrictions are applied to unsubscription.

Accessing the feature

This feature may be obtained from an ISession as follows:

var topicControl = session.Topics;

Added in version 5.0.

Properties

FetchRequest

Gets an unconfigured fetch request.

Declaration

IFetchRequest FetchRequest { get; }

Property Value

Type	Description
IFetchRequest	The unconfigured fetch request.

Remarks

If the request is invoked by calling FetchAsync(String), the fetch result will provide the paths and types of all of the topics which the session has permission to read.

You will usually want to restrict the query to a subset of the topic tree, and to retrieve the topic values and/or properties. This is achieved by applying one or more of the fluent builder methods to produce more refined requests.

For example:

var result = await topics.FetchRequest.WithValues<string?>.FetchAsync( "A/B//" );

See Also

IFetchRequest

IFetchRequest<TValue>

Methods

AddFallbackStream<TValue>(IValueStream<TValue>)

Adds a fallback value stream.

Declaration

void AddFallbackStream<TValue>(IValueStream<TValue> stream)

Parameters

Type	Name	Description
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details regarding the use of fallback streams.

AddStream<TValue>(ITopicSelector, IValueStream<TValue>)

Adds a value stream to receive topic events for topics that match a given ITopicSelector and have a value type that matches the specified type.

Declaration

void AddStream<TValue>(ITopicSelector selector, IValueStream<TValue> stream)

Parameters

Type	Name	Description
ITopicSelector	selector	The selector of one or more topics.
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details of the use of value streams.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

AddStream<TValue>(String, IValueStream<TValue>)

Adds a value stream to receive topic events for topics that match a given ITopicSelector expression and have a value type that matches the specified type.

Declaration

void AddStream<TValue>(string topics, IValueStream<TValue> stream)

Parameters

Type	Name	Description
String	topics	The topics as a ITopicSelector expression.
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details of the use of value streams.

AddTimeSeriesStream<TValue>(ITopicSelector, IValueStream<IEvent<TValue>>)

Adds a value stream to receive topic events for time series topics that match a given ITopicSelector and have a compatible time series value type.

Declaration

void AddTimeSeriesStream<TValue>(ITopicSelector selector, IValueStream<IEvent<TValue>> stream)

Parameters

Type	Name	Description
ITopicSelector	selector	The ITopicSelector.
IValueStream<IEvent<TValue>>	stream	The time series value stream.

Type Parameters

Name	Description
TValue	The time series value type.

Remarks

See the ITopics documentation for details of the use of value streams, and the ITimeSeries documentation for details of time series topics.

This method must be used instead of AddStream<TValue>(ITopicSelector, IValueStream<TValue>) to add a IValueStream<TimeSeries.IEvent<TValue>>. The stream can be removed with RemoveStream(IStream).

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

AddTimeSeriesStream<TValue>(String, IValueStream<IEvent<TValue>>)

Adds a value stream to receive topic events for time series topics that match a given ITopicSelector expression and have a compatible time series value type.

Declaration

void AddTimeSeriesStream<TValue>(string topics, IValueStream<IEvent<TValue>> stream)

Parameters

Type	Name	Description
String	topics	The ITopicSelector expression.
IValueStream<IEvent<TValue>>	stream	The time series value stream.

Type Parameters

Name	Description
TValue	The time series value type.

Remarks

See the ITopics documentation for details of the use of value streams, and the ITimeSeries documentation for details of time series topics.

This method must be used instead of AddStream<TValue>(String, IValueStream<TValue>) to add a IValueStream<TimeSeries.IEvent<TValue>>. The stream can be removed with RemoveStream(IStream).

RemoveStream(IStream)

Removes a stream.

Declaration

void RemoveStream(IStream stream)

Parameters

Type	Name	Description
IStream	stream	The value stream to remove.

Remarks

More formally, this method removes all streams that compare equal to the given stream, regardless of the topic selector for which they are registered. It will also remove any fallback stream equal to the given stream. If there are no such streams, no changes are made.

Subscribe(ITopicSelector, ITopicsCompletionCallback)

Requests subscription to topics.

Declaration

void Subscribe(ITopicSelector selector, ITopicsCompletionCallback callback)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
ITopicsCompletionCallback	callback	The callback object to receive status notifications for this operation.

Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

Subscribe(String, ITopicsCompletionCallback)

Requests subscription to topics.

Declaration

void Subscribe(string topics, ITopicsCompletionCallback callback)

Parameters

Type	Name	Description
String	topics	Specifies the topics to request subscription to.
ITopicsCompletionCallback	callback	The callback object to receive status notifications for this operation.

Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

The given topics expression will be evaluated by the server.

Subscribe<TContext>(ITopicSelector, TContext, ITopicsCompletionContextCallback<TContext>)

Requests subscription to topics.

Declaration

void Subscribe<TContext>(ITopicSelector selector, TContext context, ITopicsCompletionContextCallback<TContext> callback)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
TContext	context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including null.
ITopicsCompletionContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context object type.

Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

Subscribe<TContext>(String, TContext, ITopicsCompletionContextCallback<TContext>)

Requests subscription to topics.

Declaration

void Subscribe<TContext>(string topics, TContext context, ITopicsCompletionContextCallback<TContext> callback)

Parameters

Type	Name	Description
String	topics	Specifies the topics to request subscription to.
TContext	context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including null.
ITopicsCompletionContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context object type.

Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

The given topics expression will be evaluated by the server.

SubscribeAsync(ITopicSelector)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(ITopicSelector selector)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.

Returns

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

Remarks

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the path prefix of the given selector. Thrown by the returned Task.

See Also

SubscribeAsync(ITopicSelector, CancellationToken)

SubscribeAsync(ITopicSelector, CancellationToken)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(ITopicSelector selector, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the path prefix of the given selector. Thrown by the returned Task.

SubscribeAsync(String)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics)

Parameters

Type	Name	Description
String	topics	Specifies the topics to request subscription to.

Returns

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

Remarks

The given topics expression will be evaluated by the server.

The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the returned task completes.

The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the path prefix of the given selector expression. Thrown by the returned Task.

See Also

SubscribeAsync(String, CancellationToken)

SubscribeAsync(String, CancellationToken)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	topics	Specifies the topics to request subscription to.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the path prefix of the given selector expression. Thrown by the returned Task.

Unsubscribe(ITopicSelector, ITopicsCompletionCallback)

Unsubscribes from topics.

Declaration

void Unsubscribe(ITopicSelector selector, ITopicsCompletionCallback callback)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
ITopicsCompletionCallback	callback	The callback object to receive status notifications for this operation.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

Unsubscribe(String, ITopicsCompletionCallback)

Unsubscribes from topics.

Declaration

void Unsubscribe(string topics, ITopicsCompletionCallback callback)

Parameters

Type	Name	Description
String	topics	The topics to unsubscribe from.
ITopicsCompletionCallback	callback	The callback object to receive status notifications for this operation.

Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

The given topics expression will be evaluated by the server.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

Unsubscribe<TContext>(ITopicSelector, TContext, ITopicsCompletionContextCallback<TContext>)

Unsubscribes from topics.

Declaration

void Unsubscribe<TContext>(ITopicSelector selector, TContext context, ITopicsCompletionContextCallback<TContext> callback)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
TContext	context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including null.
ITopicsCompletionContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context object type.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

Unsubscribe<TContext>(String, TContext, ITopicsCompletionContextCallback<TContext>)

Unsubscribes from topics.

Declaration

void Unsubscribe<TContext>(string topics, TContext context, ITopicsCompletionContextCallback<TContext> callback)

Parameters

Type	Name	Description
String	topics	The topics to unsubscribe from.
TContext	context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including null.
ITopicsCompletionContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context object type.

Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

The given topics expression will be evaluated by the server.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

UnsubscribeAsync(ITopicSelector)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(ITopicSelector selector)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.

Returns

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

Remarks

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

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

See Also

UnsubscribeAsync(ITopicSelector, CancellationToken)

UnsubscribeAsync(ITopicSelector, CancellationToken)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(ITopicSelector selector, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

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

UnsubscribeAsync(String)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics)

Parameters

Type	Name	Description
String	topics	The topics to unsubscribe from.

Returns

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

Remarks

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

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

See Also

UnsubscribeAsync(String, CancellationToken)

UnsubscribeAsync(String, CancellationToken)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	topics	The topics to unsubscribe from.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

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