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 (or fetch) 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.
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. A SLAVE topic can only be created if its master topic already exists.
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) or a AddTopicEventListenerAsync(String, ITopicEventStream) 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 or fetches using a topic selector that matches no
existing topics. This allows a control session to intercede when another session requests a topic that does
not exist. The control session may use any of the AddTopicAsync
methods to create the topic, take
some other action, or do nothing, before allowing the client operation to proceed by calling
Proceed(). Alternatively, the control session can call
Cancel() to discard the request.
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 or fetches using a topic selector that matches no
existing topics. This allows a control session to intercede when another session requests a topic that does
not exist. The control session may use any of the AddTopicAsync
methods to create the topic, take
some other action, or do nothing, before allowing the client operation to proceed by calling
Proceed(). Alternatively, the control session can call
Cancel() to discard the request.
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 or fetches using a topic selector that matches no
existing topics. This allows a control session to intercede when another session requests a topic that does
not exist. The control session may use any of the AddTopicAsync
methods to create the topic, take
some other action, or do nothing, before allowing the client operation to proceed by calling
Proceed(). Alternatively, the control session can call
Cancel() to discard the request.
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 |
ClusterRepartitionException | The cluster was repartitioning. 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 |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
AddTopicAsync(String, TopicType)
Declaration
Task<AddTopicResult> AddTopicAsync(string topicPath, TopicType topicType)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | |
TopicType | topicType |
Returns
Type | Description |
---|---|
Task<AddTopicResult> |
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 |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
AddTopicException | The topic could not be created. Thrown by the returned |
AddTopicEventListener(String, ITopicControlTopicEventListener)
Registers a ITopicControlTopicEventListener to receive topic events for a branch of the topic tree.
Declaration
void AddTopicEventListener(string topicPath, ITopicControlTopicEventListener listener)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The branch of the topic tree. |
ITopicControlTopicEventListener | listener | The event listener for the given topic tree branch. |
Remarks
Deprecated: The main use case for this method is the removal of unused topics, now much better
satisfied by the Removal topic property, using the
"subscriptions < n for"
condition. This method only takes into account local sessions. The
REMOVAL topic property is fully cluster aware. This method will be removed in a future release.
Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.
AddTopicEventListenerAsync(String, ITopicEventStream)
Registers a ITopicEventStream to receive topic events for a branch of the topic tree.
Declaration
Task<IRegistration> AddTopicEventListenerAsync(string topicPath, ITopicEventStream stream)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The branch of the topic tree. |
ITopicEventStream | stream | The stream for the specified branch (unless overridden by a stream registered against a more specific branch). |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
Remarks
Deprecated: The main use case for this method is the removal of unused topics, now much better
satisfied by the Removal topic property, using the
"subscriptions < n for"
condition. This method only takes into account local sessions. The
REMOVAL topic property is fully cluster aware. This method will be removed in a future release.
If the task completes successfully, the Task
result will be a
IRegistration.
Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.
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 event stream for the |
See Also
AddTopicEventListenerAsync(String, ITopicEventStream, CancellationToken)
Registers a ITopicEventStream to receive topic events for a branch of the topic tree.
Declaration
Task<IRegistration> AddTopicEventListenerAsync(string topicPath, ITopicEventStream stream, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The branch of the topic tree. |
ITopicEventStream | stream | The stream for the specified branch (unless overridden by a stream registered against a more specific branch). |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
Remarks
Deprecated: The main use case for this method is the removal of unused topics, now much better
satisfied by the Removal topic property, using the
"subscriptions < n for"
condition. This method only takes into account local sessions. The
REMOVAL topic property is fully cluster aware. This method will be removed in a future release.
If the task completes successfully, the Task
result will be a
IRegistration.
Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.
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 event stream for the |
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<object> RemoveTopicsAsync(ITopicSelector topicSelector)
Parameters
Type | Name | Description |
---|---|---|
ITopicSelector | topicSelector | The selector specifying the topics to remove. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Remarks
If the task completes successfully, the Task
result will be null
.
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(ITopicSelector, CancellationToken)
Sends a request to remove one or more topics.
Declaration
Task<object> 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<Object> | The |
Remarks
If the task completes successfully, the Task
result will be null
.
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 |
RemoveTopicsAsync(String)
Sends a request to remove one or more topics.
Declaration
Task<object> RemoveTopicsAsync(string topicSelector)
Parameters
Type | Name | Description |
---|---|---|
String | topicSelector | The selector expression specifying the topics to remove. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Remarks
If the task completes successfully, the Task
result will be null
.
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<object> 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<Object> | The |
Remarks
If the task completes successfully, the Task
result will be null
.
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 |
RemoveTopicsWithSession(String, ITopicTreeHandler)
Registers a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.
Declaration
void RemoveTopicsWithSession(string topicPath, ITopicTreeHandler registrationHandler)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The path of the topic to be removed. |
ITopicTreeHandler | registrationHandler | The callback object to receive status notifications for this operation. |
Remarks
Deprecated: The preferred method for automatic removal of topics is the
Removal topic property. To achieve the equivalent of this method
the property can be specified as: "when this session closes remove \"?topicPath//\""
. To achieve a
dependency upon more than one session, a condition specifying a principal name or some other session
property can be used. This method will be removed in a future release.
The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.
For example, suppose two sessions both call this method with a topicPath
of
"a/b"
. When both sessions are closed, either explicitly using Close() or by the
server, the topic a/b
and all of its descendants will be removed. This method is typically used by a
session that has added topics to remove the topics if it is ever disconnected from the server or otherwise
fails.
The server will reject a the method call if the topicPath
conflicts with existing
registrations. Different sessions can call this method for the same topic path, but not for topic paths
above or below existing registrations on the same branch of the topic tree.
The following callbacks will be delivered to the given registrationHandler
:
- If registration succeeds, OnRegistered(String, IRegistration) will be called as notification that the deferred action is active. A IRegistration is provided that allows the deferred action to be deregistered.
-
If deregistration is successful, OnClose(String) will be called
as notification that the deferred action is no longer active. No further calls will be made to the given
registrationHandler
. -
If the registration or deregistration fails,
OnError(String, ErrorReason) will be called and no further calls
will be made to the given
registrationHandler
. In general, this is non-recoverable; the deferred action may or may not be active and the application can do little more than report the condition. In the specific case that OnError is called with TOPIC_TREE_REGISTRATION_CONFLICT, registration has failed due to a pre-existing registration on the same branch of the topic tree as the giventopicPath
.
The last session to close must have MODIFY_TOPIC permission for all
topics to be removed beneath topicPath
. If this is not the case at the time the session
closes, only those topics that the last session had permission to remove will be removed.
RemoveTopicsWithSessionAsync(String)
Registers a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.
Declaration
Task<IRegistration> RemoveTopicsWithSessionAsync(string topicPath)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic and its descendants to be removed if the action is executed. |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
Remarks
Deprecated: The preferred method for automatic removal of topics is the
Removal topic property. To achieve the equivalent of this method
the property can be specified as: "when this session closes remove \"?topicPath//\""
. To achieve a
dependency upon more than one session, a condition specifying a principal name or some other session
property can be used. This method will be removed in a future release.
If the registration was successful, the Task
will complete successfully with a
IRegistration result as notification that the deferred removal action is active.
The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.
For example, suppose two sessions both call this method with a topicPath
of
"a/b"
. When both sessions are closed, either explicitly using Close() or by the
server, the topic a/b
and all of its descendants will be removed. This method is typically used by a
session that has added topics to remove the topics if it is ever disconnected from the server or otherwise
fails.
The server will reject a the method call if the topicPath
conflicts with existing
registrations. Different sessions can call this method for the same topic path, but not for topic paths
above or below existing registrations on the same branch of the topic tree.
The last session to close must have MODIFY_TOPIC permission for all
topics to be removed beneath topicPath
. If this is not the case at the time the session
closes, only those topics that the last session had permission to remove will be removed.
Exceptions
Type | Condition |
---|---|
SessionClosedException | The session is closed. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the path
prefix of the given selector. Thrown by the returned |
HandlerConflictException | A session has already registered an active RemoveTopicsWithSessionAsync(String) registration
for a different topic path belonging to the same branch of the topic tree. Thrown by the returned
|
See Also
RemoveTopicsWithSessionAsync(String, CancellationToken)
Registers a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.
Declaration
Task<IRegistration> RemoveTopicsWithSessionAsync(string topicPath, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic and its descendants to be removed if the action is executed. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<IRegistration> | The |
Remarks
Deprecated: The preferred method for automatic removal of topics is the
Removal topic property. To achieve the equivalent of this method
the property can be specified as: "when this session closes remove \"?topicPath//\""
. To achieve a
dependency upon more than one session, a condition specifying a principal name or some other session
property can be used. This method will be removed in a future release.
If the registration was successful, the Task
will complete successfully with a
IRegistration result as notification that the deferred removal action is active.
The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.
For example, suppose two sessions both call this method with a topicPath
of
"a/b"
. When both sessions are closed, either explicitly using Close() or by the
server, the topic a/b
and all of its descendants will be removed. This method is typically used by a
session that has added topics to remove the topics if it is ever disconnected from the server or otherwise
fails.
The server will reject a the method call if the topicPath
conflicts with existing
registrations. Different sessions can call this method for the same topic path, but not for topic paths
above or below existing registrations on the same branch of the topic tree.
The last session to close must have MODIFY_TOPIC permission for all
topics to be removed beneath topicPath
. If this is not the case at the time the session
closes, only those topics that the last session had permission to remove will be removed.
Exceptions
Type | Condition |
---|---|
SessionClosedException | The session is closed. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC permissions for the path
prefix of the given selector. Thrown by the returned |
HandlerConflictException | A session has already registered an active RemoveTopicsWithSessionAsync(String) registration
for a different topic path belonging to the same branch of the topic tree. Thrown by the returned
|