Interface ITopicUpdate

The feature that provides a client session with the ability to update topics.

Inherited Members

IFeature.Session

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.

Topics can be set to new values using stateless SetAsync<TValue>(String, TValue) operations or an IUpdateStream<TValue>. Both ensure that new values are applied safely to appropriate topics.

Additionally, JSON topics can be updated with a JSON Patch (ApplyJSONPatchAsync(String, String)). A patch is a list of operations that modifies a JSON value, removing the need to supply a complete new value. This is useful if the source of the updates doesn't provide values. For one-off, small changes to large JSON values, it can be significantly cheaper to apply a patch than to use SetAsync<TValue>(String, TValue) to provide the complete value.

Update streams

An update stream is created for a specific topic. An UpdateStreamBuilder can be obtained using NewUpdateStreamBuilder(). The type of the topic must match the type of values passed to the update stream. An update stream can be used to send any number of updates. It sends a sequence of updates for a specific topic to the server. If supported by the data type, updates will be sent to the server as a stream of binary deltas.

Update streams have additional ways of failing compared to stateless set operations but when used repeatedly have lower overheads. This is because update streams maintain a small amount of state that reduces the overhead of operations but can become invalid for example, if the topic is deleted, or some other session updates the topic value.

By default, update streams use a form of optimistic locking. An update stream can update its topic incrementally as long as nothing else updates the topic. If the topic is updated independently (for example, by another session, or by the current session via set or a different update stream), then the next update performed by the update stream will result in an InvalidUpdateStreamException.

Applications can choose to use collaborative locking to coordinate exclusive access to a topic. To follow this pattern acquire a ISessionLock, and use it with a Locked(ISessionLock). The application is responsible for designing a locking scheme which determines which lock is required to access a particular topic, and for ensuring that all parts of the application that update the topic follow this scheme. Lock constraints and an application locking scheme can also ensure a sequence of set operations has exclusive access to the topic.

Removing values

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 ArgumentNullException to be thrown.

Adding topics

When setting a value using either stateless operations or update streams it is possible to add a topic if one is not present.This is done using the ApplyJSONPatchAsync(String, String) methods or providing a topic specification when creating the update stream. If a topic exists these methods will update the existing topic.

Time series topics

All methods provided by this feature are compatible with time series topics except for ApplyJSONPatchAsync(String, String). The ITimeSeries feature can be used to update time series topics with custom metadata and provides query capabilities.

Access control

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.

Accessing the feature

This feature may be obtained from an ISession as follows:

var topicUpdate = session.TopicUpdate;

This feature is also extended by the ITopics feature. This means it is possible to use the methods described here through the ITopics feature.

Added in version 6.2.

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 Task representing the current operation.

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 Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
InvalidTopicPathException	path is not a valid topic path. Thrown by the returned Task.
InvalidTopicSpecificationException	The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned Task.
TopicLicenseLimitException	The topic could not be added as it would breach a licensing limit. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have MODIFY_TOPIC and the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

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 Task representing the current operation.

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 Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
InvalidTopicPathException	path is not a valid topic path. Thrown by the returned Task.
InvalidTopicSpecificationException	The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned Task.
TopicLicenseLimitException	The topic could not be added as it would breach a licensing limit. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have MODIFY_TOPIC and the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint, CancellationToken)

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 Task representing the current operation.

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 Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
UnsatisfiedConstraintException	The constraint is not satisfied by the topic path. Thrown by the returned Task.
InvalidTopicPathException	path is not a valid topic path. Thrown by the returned Task.
InvalidTopicSpecificationException	The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned Task.
TopicLicenseLimitException	The topic could not be added as it would breach a licensing limit. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have MODIFY_TOPIC and the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint, CancellationToken)

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 Task representing the current operation.

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 Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
UnsatisfiedConstraintException	The constraint is not satisfied by the topic path. Thrown by the returned Task.
InvalidTopicPathException	path is not a valid topic path. Thrown by the returned Task.
InvalidTopicSpecificationException	The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned Task.
TopicLicenseLimitException	The topic could not be added as it would breach a licensing limit. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have MODIFY_TOPIC and the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

ApplyJSONPatchAsync(String, String)

Applies a JSON Patch to a JSON topic.

Declaration

Task<IJSONPatchResult> ApplyJSONPatchAsync(string path, string patch)

Parameters

Type	Name	Description
String	path	The path of the topic to patch.
String	patch	The JSON patch.

Returns

Type	Description
Task<IJSONPatchResult>	The Task representing the current operation.

Remarks

This method is the same as calling ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken) without an update constraint and with System.Threading.CancellationToken.None.

Exceptions

Type	Condition
InvalidPatchException	The patch is not a valid JSON patch. Thrown by the returned Task.
FailedPatchException	Applying the patch failed. This will occur if the topic's present value is invalid CBOR (ValidateValues). Thrown by the returned Task.
NoSuchTopicException	There is no topic bound to path. Thrown by the returned Task.
IncompatibleTopicException	patch cannot be applied to the topic, for example if the topic type is not JSON. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

ApplyJSONPatchAsync(String, String, CancellationToken)

Applies a JSON Patch to a JSON topic.

Declaration

Task<IJSONPatchResult> ApplyJSONPatchAsync(string path, string patch, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	path	The path of the topic to patch.
String	patch	The JSON patch.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IJSONPatchResult>	The Task representing the current operation.

Remarks

This method is the same as calling ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken) without an update constraint.

Exceptions

Type	Condition
InvalidPatchException	The patch is not a valid JSON patch. Thrown by the returned Task.
FailedPatchException	Applying the patch failed. This will occur if the topic's present value is invalid CBOR (ValidateValues). Thrown by the returned Task.
NoSuchTopicException	There is no topic bound to path. Thrown by the returned Task.
IncompatibleTopicException	patch cannot be applied to the topic, for example if the topic type is not JSON. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

ApplyJSONPatchAsync(String, String, IUpdateConstraint)

Applies a JSON Patch to a JSON topic.

Declaration

Task<IJSONPatchResult> ApplyJSONPatchAsync(string path, string patch, IUpdateConstraint constraint)

Parameters

Type	Name	Description
String	path	The path of the topic to patch.
String	patch	The JSON patch.
IUpdateConstraint	constraint	The constraint that must be satisfied for the patch to be applied.

Returns

Type	Description
Task<IJSONPatchResult>	The Task representing the current operation.

Remarks

This method is the same as calling ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken) with System.Threading.CancellationToken.None.

Exceptions

Type	Condition
InvalidPatchException	The patch is not a valid JSON patch. Thrown by the returned Task.
FailedPatchException	Applying the patch failed. This will occur if the topic's present value is invalid CBOR (ValidateValues). Thrown by the returned Task.
NoSuchTopicException	There is no topic bound to path. Thrown by the returned Task.
IncompatibleTopicException	patch cannot be applied to the topic, for example if the topic type is not JSON. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

Applies a JSON Patch to a JSON topic.

Declaration

Task<IJSONPatchResult> ApplyJSONPatchAsync(string path, string patch, IUpdateConstraint constraint, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	path	The path of the topic to patch.
String	patch	The JSON patch.
IUpdateConstraint	constraint	The constraint that must be satisfied for the patch to be applied.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IJSONPatchResult>	The Task representing the current operation.

Remarks

If the operation completes successfully, the Task result will be a IJSONPatchResult.

The constraint must be satisfied for the update to be applied.

The patch argument should be formatted according to the JSON Patch standard (https://tools.ietf.org/html/rfc6902).

Patches are a sequence of JSON Patch operations contained in an array. They are applied as an atomic update to the previous value if the resulting update is successfully calculated. The following patch will check the value at a specific key and update if the expected value is correct:

[{"op": "test", "path": "/price", "value": 22},
{"op": "add", "path": "/price", "value": 23}]

The available operations are:

• Add: {"op": "add", "path": "/a/b/c", "value": ["foo", "bar"]}
• Remove: {"op": "remove", "path": "/a/b/c"}
• Replace: {"op": "replace", "path": "/a/b/c", "value": 43}
• Move: {"op": "move", "from": "/a/b/c", "path": "/a/b/d"}
• Copy: {"op": "copy", "from": "/a/b/c", "path": "/a/b/e"}
• Test: {"op": "test", "path": "/a/b/c", "value": "foo"}

The test operation checks that the CBOR representation of the value of a topic is identical to the value provided in the patch after converting it to CBOR. If the value is represented differently as CBOR, commonly due to different key ordering, then the patch will return the index of the failed operation, e.g. the values {"foo": "bar", "count": 43} and {"count": 43, "foo": "bar"} are unequal despite semantic equality due to the differences in a byte for byte comparison.

Exceptions

Type	Condition
InvalidPatchException	The patch is not a valid JSON patch. Thrown by the returned Task.
FailedPatchException	Applying the patch failed. This will occur if the topic's present value is invalid CBOR (ValidateValues). Thrown by the returned Task.
NoSuchTopicException	There is no topic bound to path. Thrown by the returned Task.
IncompatibleTopicException	patch cannot be applied to the topic, for example if the topic type is not JSON. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

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.

Remarks

Caution

Deprecated since 6.9. Use NewUpdateStreamBuilder(). This method will be removed in a future release.

See Also

CreateUpdateStream<TValue>(String, IUpdateConstraint)

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.

Caution

Deprecated since 6.9. Use NewUpdateStreamBuilder(). This method will be removed in a future release.

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.

Caution

Deprecated since 6.9. Use NewUpdateStreamBuilder(). This method will be removed in a future release.

See Also

CreateUpdateStream<TValue>(String, ITopicSpecification, IUpdateConstraint)

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.

Caution

Deprecated since 6.9. Use NewUpdateStreamBuilder(). This method will be removed in a future release.

NewUpdateStreamBuilder()

Creates an update stream builder to use for creating update streams.

Declaration

IUpdateStreamBuilder NewUpdateStreamBuilder()

Returns

Type	Description
IUpdateStreamBuilder	An update stream builder.

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 Task representing the current operation.

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 path. Thrown by the returned Task.
IncompatibleTopicException	Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)

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 Task representing the current operation.

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 path. Thrown by the returned Task.
IncompatibleTopicException	Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)

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 Task representing the current operation.

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 path. Thrown by the returned Task.
IncompatibleTopicException	Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned Task.
UnsatisfiedConstraintException	The constraint is not satisfied by the topic path. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)

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 Task representing the current operation.

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 path. Thrown by the returned Task.
IncompatibleTopicException	Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned Task.
UnsatisfiedConstraintException	The constraint is not satisfied by the topic path. Thrown by the returned Task.
IncompatibleTopicStateException	The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the returned Task.
ClusterRoutingException	A transient cluster error occurred. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the UPDATE_TOPIC permission for path. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.