Interface ITopicControl

The feature that allows a session to manage topics.

Inherited Members

IFeature.Session

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

AddMissingTopicHandler(String, IMissingTopicHandler)

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

Declaration

void AddMissingTopicHandler(string topicPath, IMissingTopicHandler handler)

Parameters

Type	Name	Description
String	topicPath	The branch of the topic tree.
IMissingTopicHandler	handler	The callback object to receive status notifications for this operation.

Remarks

Caution

Deprecated since 6.7. Prefer the Task-based alternative AddMissingTopicHandlerAsync(String, IMissingTopicNotificationStream) since it provides better error reporting.

The provided handler is called when a session subscribes using a topic selector that matches no existing topics.

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

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

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
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).
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
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
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.

AddTopic(String, ITopicSpecification, ITopicControlAddCallback)

Sends a request to the server to add a topic.

Declaration

void AddTopic(string topicPath, ITopicSpecification specification, ITopicControlAddCallback callback)

Parameters

Type	Name	Description
String	topicPath	The topic path to which the topic will be bound.
ITopicSpecification	specification	The topic specifications of the topic to be created.
ITopicControlAddCallback	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.

A specification can be created with NewSpecification(TopicType).

AddTopic<TContext>(String, ITopicSpecification, TContext, ITopicControlAddContextCallback<TContext>)

Sends a request to the server to add a topic.

Declaration

void AddTopic<TContext>(string topicPath, ITopicSpecification specification, TContext context, ITopicControlAddContextCallback<TContext> callback)

Parameters

Type	Name	Description
String	topicPath	The topic path to which the topic will be bound.
ITopicSpecification	specification	The topic specifications of the topic to be created.
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.
ITopicControlAddContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context 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.

A specification can be created with NewSpecification(TopicType).

AddTopicAsync(String, ITopicSpecification)

Requests creation of a topic.

Declaration

Task<AddTopicResult> AddTopicAsync(string topicPath, ITopicSpecification specification)

Parameters

Type	Name	Description
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
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
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.

See Also

AddTopicAsync(String, ITopicSpecification, CancellationToken)

AddTopicAsync(String, ITopicSpecification, CancellationToken)

Requests creation of a topic.

Declaration

Task<AddTopicResult> AddTopicAsync(string topicPath, ITopicSpecification specification, CancellationToken cancellationToken)

Parameters

Type	Name	Description
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).
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
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
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.

AddTopicAsync(String, TopicType)

Requests creation of a topic.

Declaration

Task<AddTopicResult> AddTopicAsync(string topicPath, TopicType topicType)

Parameters

Type	Name	Description
String	topicPath	The topic path to which the topic will be bound.
TopicType	topicType	The type of topic to be created.

Returns

Type	Description
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
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.

See Also

AddTopicAsync(String, TopicType, CancellationToken)

AddTopicAsync(String, TopicType, CancellationToken)

Requests creation of a topic.

Declaration

Task<AddTopicResult> AddTopicAsync(string topicPath, TopicType topicType, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	topicPath	The topic path to which the topic will be bound.
TopicType	topicType	The type of topic to be created.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
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
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.

NewSpecification(TopicType)

Creates a new ITopicSpecification for a given topic type.

Declaration

ITopicSpecification NewSpecification(TopicType topicType)

Parameters

Type	Name	Description
TopicType	topicType	The topic type.

Returns

Type	Description
ITopicSpecification	The new immutable specification with no properties set. New specifications with properties set may be produced using the WithProperty(String, String) or WithProperties(IDictionary<String, String>) methods of the provided specification.

Remarks

Caution

Deprecated since 6.7. Use NewSpecification(TopicType) instead.

Remove(String, ITopicControlRemovalCallback)

Sends a request to remove one or more topics.

Declaration

void Remove(string topicSelector, ITopicControlRemovalCallback callback)

Parameters

Type	Name	Description
String	topicSelector	The topic selector expression specifying the topics to remove.
ITopicControlRemovalCallback	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 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.

Remove<TContext>(String, TContext, ITopicControlRemovalContextCallback<TContext>)

Sends a request to remove one or more topics.

Declaration

void Remove<TContext>(string topicSelector, TContext context, ITopicControlRemovalContextCallback<TContext> callback)

Parameters

Type	Name	Description
String	topicSelector	The topic selector expression specifying the topics to remove.
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.
ITopicControlRemovalContextCallback<TContext>	callback	The callback object to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context 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 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.

RemoveTopicsAsync(ITopicSelector)

Sends a request to remove one or more topics.

Declaration

Task<ITopicRemovalResult> RemoveTopicsAsync(ITopicSelector topicSelector)

Parameters

Type	Name	Description
ITopicSelector	topicSelector	The selector specifying the topics to remove.

Returns

Type	Description
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
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

RemoveTopicsAsync(ITopicSelector, CancellationToken)

RemoveTopicsAsync(ITopicSelector, CancellationToken)

Sends a request to remove one or more topics.

Declaration

Task<ITopicRemovalResult> RemoveTopicsAsync(ITopicSelector topicSelector, CancellationToken cancellationToken)

Parameters

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

Returns

Type	Description
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
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
String	topicSelector	The selector expression specifying the topics to remove.

Returns

Type	Description
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
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

RemoveTopicsAsync(String, CancellationToken)

RemoveTopicsAsync(String, CancellationToken)

Sends a request to remove one or more topics.

Declaration

Task<ITopicRemovalResult> RemoveTopicsAsync(string topicSelector, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	topicSelector	The selector expression specifying the topics to remove.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
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
SessionClosedException	The session is closed. Thrown by the returned Task.