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
This feature 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.
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.
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.
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 hierarchiesA 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.
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.
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
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 routing topics at or below the |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
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 |
SessionSecurityException | The calling session does not have REGISTER_HANDLER permissions. Thrown
by the returned |
HandlerConflictException | The session has already registered a missing topic handler for |
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 |
---|---|---|
String | topicPath | The branch of the topic tree. |
IMissingTopicNotificationStream | stream | The stream to use for routing topics at or below the |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
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 |
SessionSecurityException | The calling session does not have REGISTER_HANDLER permissions. Thrown
by the returned |
HandlerConflictException | The session has already registered a missing topic handler for |
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
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 |
ITopicControlAddContextCallback<TContext> | callback | The callback object to receive status notifications for this operation. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
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 |
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 |
ExistingTopicException | The topic bound to |
InvalidTopicPathException | The |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the
given |
ReferencedTopicDoesNotExistException | The |
InvalidTopicSpecificationException | The |
ClusterRoutingException | A transient cluster error occured. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
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 |
---|---|---|
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 |
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 |
ExistingTopicException | The topic bound to |
InvalidTopicPathException | The |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the
given |
ReferencedTopicDoesNotExistException | The |
InvalidTopicSpecificationException | The |
ClusterRoutingException | A transient cluster error occured. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
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 |
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 |
ExistingTopicException | The topic bound to |
InvalidTopicPathException | The |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the
given |
ReferencedTopicDoesNotExistException | The specification references an unknown topic. Thrown by the returned |
InvalidTopicSpecificationException | The specification is invalid. Thrown by the returned |
ClusterRoutingException | A transient cluster error occured. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
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 |
---|---|---|
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 |
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 |
ExistingTopicException | The topic bound to |
InvalidTopicPathException | The |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the
given |
ReferencedTopicDoesNotExistException | The specification references an unknown topic. Thrown by the returned |
InvalidTopicSpecificationException | The specification is invalid. Thrown by the returned |
ClusterRoutingException | A transient cluster error occured. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
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. |
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
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 |
ITopicControlRemovalContextCallback<TContext> | callback | The callback object to receive status notifications for this operation. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
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 |
Remarks
If the task completes successfully, the Task
result will bear a ITopicRemovalResult.
This provides the number of topics removed by calling
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
Exceptions
Type | Condition |
---|---|
SessionClosedException | The session is closed. Thrown by the returned |
See Also
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 |
Remarks
If the task completes successfully, the Task
result will bear a ITopicRemovalResult.
This provides the number of topics removed by calling
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
Exceptions
Type | Condition |
---|---|
SessionClosedException | The session is closed. Thrown by the returned |
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 |
Remarks
If the task completes successfully, the Task
result will bear a ITopicRemovalResult.
This provides the number of topics removed by calling
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 |
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 |
---|---|---|
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 |
Remarks
If the task completes successfully, the Task
result will bear a ITopicRemovalResult.
This provides the number of topics removed by calling
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 |