Interface ITopicControl

The feature that allows a session to manage topics.

Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features.Control.Topics
Assembly: Diffusion.Client.dll
Syntax
public interface ITopicControl : IFeature
Remarks

It provides the following capabilities:

  • Adding and removing topics.
  • Missing topic notifications — listening for requests to subscribe to topics that do not exist thus allowing dynamic topic creation on demand.
  • Topic event listeners — listening for topic events, such as the number of subscribers to a topic changing from zero to greater than zero or from greater than zero to zero.

Topics

The Diffusion server stores data in topics. Each topic is bound to a topic path in the topic tree, and may have a current value. Sessions can subscribe to topics. Updates to topic values are broadcast to subscribing sessions. There are several types of topic. The TopicType determines the type of the data values a topic publishes to subscribers.

Adding topics

Creating topics

The simplest way to create a topic is to call AddTopicAsync(String, TopicType), supplying a topic type. Success or failure is reported asynchronously by the returned Task.

The nature of a topic depends primarily on its topic type, but can be customized using topic properties. Some types of topic cannot be created without supplying mandatory topic properties. Topic properties can be supplied in a ITopicSpecification using AddTopicAsync(String, ITopicSpecification). Topic specifications can be created using NewSpecification(TopicType) and further customized with builder methods.

See TopicSpecificationProperty for details of the available topic properties and their effects on the different types of topic.

Topic creation is idempotent. If AddTopicAsync(String, ITopicSpecification) is called and there is already a topic bound to topicPath with a topic specification equal to specification, the call will complete normally with an EXISTS result. However, if there is a topic bound to topicPath with a different topic specification, the call will complete exceptionally with an ExistingTopicException.

Removing topics

Topics can be removed using RemoveTopicsAsync(String). Only those selected topics that the caller has MODIFY_TOPIC permission to will be removed, any others will remain.

Topics can also be automatically removed according to a removal criteria specified using the Removal topic property.

Managing topic tree hierarchies

A topic can be bound to any path in the topic tree namespace. The only restriction is that two topics can not have the same path. In general, topics can be created in any order.

Topics can be removed without affecting the topics subordinate to them in the topic tree using RemoveTopicsAsync(String) providing a path expression. By using the // topic selector qualifier it is possible to remove a topic and all of its descendant topics, that is to remove whole topic tree branches.

Access control

To add or remove a topic, a session needs MODIFY_TOPIC permission for the topic path. When removing topics with a topic selector that matches more than one topic, only topics with paths for which the session has MODIFY_TOPIC permission will be removed.

To register a AddMissingTopicHandlerAsync(String, IMissingTopicNotificationStream) the session needs REGISTER_HANDLER permission.

Accessing the feature

This feature may be obtained from an ISession as follows: 

var topicControl = session.TopicControl;

Added in version 5.0.

Methods

AddMissingTopicHandlerAsync(String, IMissingTopicNotificationStream)

Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree.

Declaration
Task<IRegistration> AddMissingTopicHandlerAsync(string topicPath, IMissingTopicNotificationStream stream)
Parameters
Type Name Description
System.String topicPath

The branch of the topic tree.
IMissingTopicNotificationStream stream

The stream to use for notifying topics at or below the topicPath (unless there is a stream registered for a more specific topic path).
Returns
Type Description
System.Threading.Tasks.Task<IRegistration>

The Task representing the current operation.
Remarks

The provided handler is called when a session subscribes using a topic selector that matches no existing topics. This allows a control session to be notified when another session requests a topic that does not exist.

A session can register multiple handlers, but may only register a single handler for a given topic path. If there is already a handler registered for the topic path the operation will fail with a HandlerConflictException. A handler will only be called for topic selectors with a path prefix that starts with or is equal to topicPath. If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

If registration was successful, the Task will complete successfully with a IRegistration result which can be used to unregister the stream.

Exceptions
Type Condition
System.ArgumentNullException

The topicPath or stream is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
SessionSecurityException

The calling session does not have REGISTER_HANDLER permissions. Thrown by the returned Task.
HandlerConflictException

The session has already registered a missing topic handler for topicPath. Thrown by the returned Task.
See Also

AddMissingTopicHandlerAsync(String, IMissingTopicNotificationStream, CancellationToken)

Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree.

Declaration
Task<IRegistration> AddMissingTopicHandlerAsync(string topicPath, IMissingTopicNotificationStream stream, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String topicPath

The branch of the topic tree.
IMissingTopicNotificationStream stream

The stream to use for notifying topics at or below the topicPath (unless there is a stream registered for a more specific topic path).
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<IRegistration>

The Task representing the current operation.
Remarks

The provided handler is called when a session subscribes using a topic selector that matches no existing topics. This allows a control session to be notified when another session requests a topic that does not exist.

A session can register multiple handlers, but may only register a single handler for a given topic path. If there is already a handler registered for the topic path the operation will fail with a HandlerConflictException. A handler will only be called for topic selectors with a path prefix that starts with or is equal to topicPath. If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

If registration was successful, the Task will complete successfully with a IRegistration result which can be used to unregister the stream.

Exceptions
Type Condition
System.ArgumentNullException

The topicPath or stream is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
SessionSecurityException

The calling session does not have REGISTER_HANDLER permissions. Thrown by the returned Task.
HandlerConflictException

The session has already registered a missing topic handler for topicPath. Thrown by the returned Task.

AddTopicAsync(String, ITopicSpecification)

Requests creation of a topic.

Declaration
Task<AddTopicResult> AddTopicAsync(string topicPath, ITopicSpecification specification)
Parameters
Type Name Description
System.String topicPath

The topic path to which the topic will be bound.
ITopicSpecification specification

The topic specification that defines the topic to be created. Can be created using NewSpecification(TopicType).
Returns
Type Description
System.Threading.Tasks.Task<AddTopicResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

Exceptions
Type Condition
System.ArgumentNullException

The topicPath or specification is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
ExistingTopicException

The topic bound to topicPath already exists with different specifications. Thrown by the returned Task.
InvalidTopicPathException

The topicPath is invalid. Thrown by the returned Task.
SessionSecurityException

The calling session does not have MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned Task.
ReferencedTopicDoesNotExistException

The specification references an unknown topic. Thrown by the returned Task.
InvalidTopicSpecificationException

The specification is invalid. Thrown by the returned Task.
ClusterRoutingException

A transient cluster error occured. Thrown by the returned Task.
AddTopicException

The topic could not be created. Thrown by the returned Task.
System.InvalidOperationException

The server response was invalid. Thrown by the returned Task.
See Also

AddTopicAsync(String, ITopicSpecification, CancellationToken)

Requests creation of a topic.

Declaration
Task<AddTopicResult> AddTopicAsync(string topicPath, ITopicSpecification specification, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String topicPath

The topic path to which the topic will be bound.
ITopicSpecification specification

The topic specification that defines the topic to be created. Can be created using NewSpecification(TopicType).
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<AddTopicResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

Exceptions
Type Condition
System.ArgumentNullException

The topicPath or specification is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
ExistingTopicException

The topic bound to topicPath already exists with different specifications. Thrown by the returned Task.
InvalidTopicPathException

The topicPath is invalid. Thrown by the returned Task.
SessionSecurityException

The calling session does not have MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned Task.
ReferencedTopicDoesNotExistException

The specification references an unknown topic. Thrown by the returned Task.
InvalidTopicSpecificationException

The specification is invalid. Thrown by the returned Task.
ClusterRoutingException

A transient cluster error occured. Thrown by the returned Task.
AddTopicException

The topic could not be created. Thrown by the returned Task.
System.InvalidOperationException

The server response was invalid. Thrown by the returned Task.

AddTopicAsync(String, TopicType)

Requests creation of a topic.

Declaration
Task<AddTopicResult> AddTopicAsync(string topicPath, TopicType topicType)
Parameters
Type Name Description
System.String topicPath

The topic path to which the topic will be bound.
TopicType topicType

The type of topic to be created.
Returns
Type Description
System.Threading.Tasks.Task<AddTopicResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

This is a convenience method that is equivalent to calling AddTopicAsync(String, ITopicSpecification) given a topic specification created with NewSpecification(TopicType).

Exceptions
Type Condition
System.ArgumentNullException

The topicPath is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
ExistingTopicException

The topic bound to topicPath already exists with different specifications. Thrown by the returned Task.
InvalidTopicPathException

The topicPath is invalid. Thrown by the returned Task.
SessionSecurityException

The calling session does not have MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned Task.
ReferencedTopicDoesNotExistException

The specification references an unknown topic. Thrown by the returned Task.
InvalidTopicSpecificationException

The specification is invalid. Thrown by the returned Task.
ClusterRoutingException

A transient cluster error occured. Thrown by the returned Task.
AddTopicException

The topic could not be created. Thrown by the returned Task.
System.InvalidOperationException

The server response was invalid. Thrown by the returned Task.
See Also

AddTopicAsync(String, TopicType, CancellationToken)

Requests creation of a topic.

Declaration
Task<AddTopicResult> AddTopicAsync(string topicPath, TopicType topicType, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String topicPath

The topic path to which the topic will be bound.
TopicType topicType

The type of topic to be created.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<AddTopicResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

Exceptions
Type Condition
System.ArgumentNullException

The topicPath is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
ExistingTopicException

The topic bound to topicPath already exists with different specifications. Thrown by the returned Task.
InvalidTopicPathException

The topicPath is invalid. Thrown by the returned Task.
SessionSecurityException

The calling session does not have MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned Task.
ReferencedTopicDoesNotExistException

The specification references an unknown topic. Thrown by the returned Task.
InvalidTopicSpecificationException

The specification is invalid. Thrown by the returned Task.
ClusterRoutingException

A transient cluster error occured. Thrown by the returned Task.
AddTopicException

The topic could not be created. Thrown by the returned Task.
System.InvalidOperationException

The server response was invalid. Thrown by the returned Task.

RemoveTopicsAsync(ITopicSelector)

Sends a request to remove one or more topics.

Declaration
[Obsolete("Topic selectors are now deprecated and will be removed in a future release.Instead, use the RemoveTopicsAsync method that accepts a string argument.", false)]
Task<ITopicRemovalResult> RemoveTopicsAsync(ITopicSelector topicSelector)
Parameters
Type Name Description
ITopicSelector topicSelector

The selector specifying the topics to remove.
Returns
Type Description
System.Threading.Tasks.Task<ITopicRemovalResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will bear a ITopicRemovalResult. This provides the number of topics removed by calling RemovedCount.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing / or //), can be used to remove descendant topics. If a single / qualifier is specified, all descendants of the matched topic paths will be removed. If // is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

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
System.ArgumentNullException

The topicSelector expression is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
See Also

RemoveTopicsAsync(ITopicSelector, CancellationToken)

Sends a request to remove one or more topics.

Declaration
[Obsolete("Topic selectors are now deprecated and will be removed in a future release.Instead, use the RemoveTopicsAsync method that accepts a string argument.", false)]
Task<ITopicRemovalResult> RemoveTopicsAsync(ITopicSelector topicSelector, CancellationToken cancellationToken)
Parameters
Type Name Description
ITopicSelector topicSelector

The selector specifying the topics to remove.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<ITopicRemovalResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will bear a ITopicRemovalResult. This provides the number of topics removed by calling RemovedCount.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing / or //), can be used to remove descendant topics. If a single / qualifier is specified, all descendants of the matched topic paths will be removed. If // is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

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
System.ArgumentNullException

The topicSelector expression is null.
SessionClosedException

The session is closed. Thrown by the returned Task.

RemoveTopicsAsync(String)

Sends a request to remove one or more topics.

Declaration
Task<ITopicRemovalResult> RemoveTopicsAsync(string topicSelector)
Parameters
Type Name Description
System.String topicSelector

The selector expression specifying the topics to remove.
Returns
Type Description
System.Threading.Tasks.Task<ITopicRemovalResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will bear a ITopicRemovalResult. This provides the number of topics removed by calling RemovedCount.

The given topicSelector expression will be evaluated by the server.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing / or //), can be used to remove descendant topics. If a single / qualifier is specified, all descendants of the matched topic paths will be removed. If // is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Exceptions
Type Condition
System.ArgumentNullException

The topicSelector expression is null.
SessionClosedException

The session is closed. Thrown by the returned Task.
See Also

RemoveTopicsAsync(String, CancellationToken)

Sends a request to remove one or more topics.

Declaration
Task<ITopicRemovalResult> RemoveTopicsAsync(string topicSelector, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String topicSelector

The selector expression specifying the topics to remove.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<ITopicRemovalResult>

The Task representing the current operation.
Remarks

If the task completes successfully, the Task result will bear a ITopicRemovalResult. This provides the number of topics removed by calling RemovedCount.

The given topicSelector expression will be evaluated by the server.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing / or //), can be used to remove descendant topics. If a single / qualifier is specified, all descendants of the matched topic paths will be removed. If // is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Exceptions
Type Condition
System.ArgumentNullException

The topicSelector expression is null.
SessionClosedException

The session is closed. Thrown by the returned Task.