Table of Contents

Interface ITopicUpdate

Namespace
PushTechnology.ClientInterface.Client.Features
Assembly
Diffusion.Client.dll

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

public interface ITopicUpdate : IFeature
Inherited Members

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.

Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

value TValue

The value.

Returns

Task<TopicCreationResult>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, specification, value is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and value have different data types.

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

Adds the topic if it does not exist and sets it to a specified value.

Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, IUpdateConstraint constraint)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

value TValue

The value.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

Returns

Task<TopicCreationResult>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, specification, value, or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and value have different data types.

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)

Adds the topic if it does not exist and sets it to a specified value.

Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, IUpdateConstraint constraint, CancellationToken cancellationToken)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

value TValue

The value.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<TopicCreationResult>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, specification, value, or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and value have different data types.

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.

AddAndSetAsync<TValue>(string, ITopicSpecification, TValue, CancellationToken)

Adds the topic if it does not exist and sets it to a specified value.

Task<TopicCreationResult> AddAndSetAsync<TValue>(string path, ITopicSpecification specification, TValue value, CancellationToken cancellationToken)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

value TValue

The value.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<TopicCreationResult>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, specification, value is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and value have different data types.

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

ApplyJSONPatchAsync(string, string)

Applies a JSON Patch to a JSON topic.

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

Parameters

path string

The path of the topic to patch.

patch string

The JSON patch.

Returns

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

ArgumentNullException

The path, or patch is null.

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)

Applies a JSON Patch to a JSON topic.

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

Parameters

path string

The path of the topic to patch.

patch string

The JSON patch.

constraint IUpdateConstraint

The constraint that must be satisfied for the patch to be applied.

Returns

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

ArgumentNullException

The path, patch, or constraint is null.

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)

Applies a JSON Patch to a JSON topic.

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

Parameters

path string

The path of the topic to patch.

patch string

The JSON patch.

constraint IUpdateConstraint

The constraint that must be satisfied for the patch to be applied.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException

The path, patch, or constraint is null.

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.

ApplyJSONPatchAsync(string, string, CancellationToken)

Applies a JSON Patch to a JSON topic.

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

Parameters

path string

The path of the topic to patch.

patch string

The JSON patch.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException

The path, or patch is null.

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

CreateUpdateStream<TValue>(string)

Creates an IUpdateStream<TValue> to use for updating a specific topic.

[Obsolete("Deprecated since 6.9. Use NewUpdateSreamBuilder().")]
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path)

Parameters

path string

The path of the topic.

Returns

IUpdateStream<TValue>

The new IUpdateStream<TValue> instance.

Type Parameters

TValue

The value type.

Remarks

Caution

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

Exceptions

ArgumentNullException

The path is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

See Also

CreateUpdateStream<TValue>(string, IUpdateConstraint)

Creates an IUpdateStream<TValue> to use for updating a specific topic.

[Obsolete("Deprecated since 6.9. Use NewUpdateSreamBuilder().")]
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, IUpdateConstraint constraint)

Parameters

path string

The path of the topic.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

Returns

IUpdateStream<TValue>

The new IUpdateStream<TValue> instance.

Type Parameters

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.

Exceptions

ArgumentNullException

The path or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

CreateUpdateStream<TValue>(string, ITopicSpecification)

Creates an IUpdateStream<TValue> to use for updating a specific topic.

[Obsolete("Deprecated since 6.9. Use NewUpdateSreamBuilder().")]
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, ITopicSpecification specification)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

Returns

IUpdateStream<TValue>

The new IUpdateStream<TValue> instance.

Type Parameters

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.

Exceptions

ArgumentNullException

The path or specification is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and TValue have different data types.

See Also

CreateUpdateStream<TValue>(string, ITopicSpecification, IUpdateConstraint)

Creates an IUpdateStream<TValue> to use for updating a specific topic.

[Obsolete("Deprecated since 6.9. Use NewUpdateSreamBuilder().")]
IUpdateStream<TValue> CreateUpdateStream<TValue>(string path, ITopicSpecification specification, IUpdateConstraint constraint)

Parameters

path string

The path of the topic.

specification ITopicSpecification

The required specification of the topic.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

Returns

IUpdateStream<TValue>

The new IUpdateStream<TValue> instance.

Type Parameters

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.

Exceptions

ArgumentNullException

The path, specification, or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation, or the specification and TValue have different data types.

NewUpdateStreamBuilder()

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

IUpdateStreamBuilder NewUpdateStreamBuilder()

Returns

IUpdateStreamBuilder

An update stream builder.

SetAsync<TValue>(string, TValue)

Sets the topic to a specified value.

Task<object> SetAsync<TValue>(string path, TValue value)

Parameters

path string

The path of the topic.

value TValue

The value.

Returns

Task<object>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path or value is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

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)

Sets the topic to a specified value.

Task<object> SetAsync<TValue>(string path, TValue value, IUpdateConstraint constraint)

Parameters

path string

The path of the topic.

value TValue

The value.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

Returns

Task<object>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, value, or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

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)

Sets the topic to a specified value.

Task<object> SetAsync<TValue>(string path, TValue value, IUpdateConstraint constraint, CancellationToken cancellationToken)

Parameters

path string

The path of the topic.

value TValue

The value.

constraint IUpdateConstraint

The constraint that must be satisfied for the topic to be updated.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<object>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path, value, or constraint is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

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.

SetAsync<TValue>(string, TValue, CancellationToken)

Sets the topic to a specified value.

Task<object> SetAsync<TValue>(string path, TValue value, CancellationToken cancellationToken)

Parameters

path string

The path of the topic.

value TValue

The value.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<object>

The Task representing the current operation.

Type Parameters

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

ArgumentNullException

The path or value is null.

ArgumentException

TValue has no backing IDataType<TValue> implementation.

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