Interface ITopicUpdate
The feature that provides a client session with the ability to update topics.
Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features
Assembly: Diffusion.Client.dll
Syntax
public interface ITopicUpdate : IFeature
Remarks
A session does not have to be subscribed to a topic to update it.
Constraints can be applied to the setting of a value and creation of an update stream. Constraints describe a condition that must be satisfied for the operation to succeed. The constraints are evaluated on the server. The available constraints: are an active session lock, the current value of the topic being updated and a part of the current value of the topic being updated.
When a topic of type STRING), INT64, or
DOUBLE is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification. Attempting to set any other type of topic
to null
will cause a
To update a topic a session needs UPDATE_TOPIC permission for the topic path. To create a topic a session needs MODIFY_TOPIC permission for the topic. Requests that combine adding a topic and setting the value such as AddAndSetAsync<TValue>(String, ITopicSpecification, TValue) require both permissions.
Methods
AddAndSetAsync<TValue>(String, ITopicSpecification, TValue)
Adds the topic if it does not exist and sets it to a specified value.
Declaration
Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
TValue | value | The value. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists.
If a topic does not exist at the path
, one will be created using the
specification
. If a topic does exist, its specification must match
specification
, otherwise the operation will fail with
IncompatibleTopicException.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleParentTopicException | A topic could not be added because a topic at a parent path is incompatible. Thrown by the returned
|
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC and the
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, CancellationToken)
Adds the topic if it does not exist and sets it to a specified value.
Declaration
Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
TValue | value | The value. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists.
If a topic does not exist at the path
, one will be created using the
specification
. If a topic does exist, its specification must match
specification
, otherwise the operation will fail with
IncompatibleTopicException.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleParentTopicException | A topic could not be added because a topic at a parent path is incompatible. Thrown by the returned
|
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC and the
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
See Also
AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint)
Adds the topic if it does not exist and sets it to a specified value.
Declaration
Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, IUpdateConstraint constraint)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
TValue | value | The value. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists.
If a topic does not exist at the path
, one will be created using the
specification
. If a topic does exist, its specification must match
specification
, otherwise the operation will fail with
IncompatibleTopicException.
Takes a constraint that must be satisfied for the topic to be created or the update to be applied.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleParentTopicException | A topic could not be added because a topic at a parent path is incompatible. Thrown by the returned
|
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC and the
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
See Also
AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint, CancellationToken)
Adds the topic if it does not exist and sets it to a specified value.
Declaration
Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, IUpdateConstraint constraint, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
TValue | value | The value. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists.
If a topic does not exist at the path
, one will be created using the
specification
. If a topic does exist, its specification must match
specification
, otherwise the operation will fail with
IncompatibleTopicException.
Takes a constraint that must be satisfied for the topic to be created or the update to be applied.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleParentTopicException | A topic could not be added because a topic at a parent path is incompatible. Thrown by the returned
|
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC and the
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
CreateUpdateStream<TValue>(String)
Creates an IUpdateStream<TValue> to use for updating a specific topic.
Declaration
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
Returns
Type | Description |
---|---|
IUpdateStream<TValue> | The new IUpdateStream<TValue> instance. |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
See Also
CreateUpdateStream<TValue>(String, IUpdateConstraint)
Creates an IUpdateStream<TValue> to use for updating a specific topic.
Declaration
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, IUpdateConstraint constraint)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
Returns
Type | Description |
---|---|
IUpdateStream<TValue> | The new IUpdateStream<TValue> instance. |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
Takes a constraint that must be satisfied for the update stream to be validated.
CreateUpdateStream<TValue>(String, ITopicSpecification)
Creates an IUpdateStream<TValue> to use for updating a specific topic.
Declaration
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, ITopicSpecification specification)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
Returns
Type | Description |
---|---|
IUpdateStream<TValue> | The new IUpdateStream<TValue> instance. |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If a topic does not exist at the path
one will be created using the
specification
when the update stream is validated. If a topic does exist, its
specification must match specification
, otherwise the operation will fail with
IncompatibleTopicException.
See Also
CreateUpdateStream<TValue>(String, ITopicSpecification, IUpdateConstraint)
Creates an IUpdateStream<TValue> to use for updating a specific topic.
Declaration
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, ITopicSpecification specification, IUpdateConstraint constraint)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
ITopicSpecification | specification | The required specification of the topic. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
Returns
Type | Description |
---|---|
IUpdateStream<TValue> | The new IUpdateStream<TValue> instance. |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If a topic does not exist at the path
one will be created using the
specification
when the update stream is validated. If a topic does exist, its
specification must match specification
, otherwise the operation will fail with
IncompatibleTopicException.
Takes a constraint that must be satisfied for the update stream to be validated.
SetAsync<TValue>(String, TValue)
Sets the topic to a specified value.
Declaration
Task<object> SetAsync<TValue>(string path, TValue value)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
TValue | value | The value. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be null
.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have the UPDATE_TOPIC permission for
|
SessionClosedException | The session is closed. Thrown by the returned |
See Also
SetAsync<TValue>(String, TValue, CancellationToken)
Sets the topic to a specified value.
Declaration
Task<object> SetAsync<TValue>(string path, TValue value, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
TValue | value | The value. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be null
.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have the UPDATE_TOPIC permission for
|
SessionClosedException | The session is closed. Thrown by the returned |
See Also
SetAsync<TValue>(String, TValue, IUpdateConstraint)
Sets the topic to a specified value.
Declaration
Task<object> SetAsync<TValue>(string path, TValue value, IUpdateConstraint constraint)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
TValue | value | The value. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be null
.
Takes a constraint that must be satisfied for the update to be applied.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
UnsatisfiedConstraintException | The |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have the UPDATE_TOPIC permission for
|
SessionClosedException | The session is closed. Thrown by the returned |
See Also
SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)
Sets the topic to a specified value.
Declaration
Task<object> SetAsync<TValue>(string path, TValue value, IUpdateConstraint constraint, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path of the topic. |
TValue | value | The value. |
IUpdateConstraint | constraint | The constraint that must be satisfied for the topic to be updated. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<Object> | The |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
If the task completes successfully, the Task
result will be null
.
Takes a constraint that must be satisfied for the update to be applied.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics is set to null
, the topic will be updated to have no
value. If a previous value was present subscribers will receive a notification that the new value is
null
. New subscribers will not receive a value notification.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
UnsatisfiedConstraintException | The |
ExclusiveUpdaterConflictException | Updates cannot be applied to the topic because an exclusive update source is registered for its path.
Thrown by the returned |
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
ClusterRepartitionException | The cluster was repartitioning. Thrown by the returned |
SessionSecurityException | The calling session does not have the UPDATE_TOPIC permission for
|
SessionClosedException | The session is closed. Thrown by the returned |