Applies a JSON Patch to a JSON topic.
The patch argument should be formatted according to the JSON
Patch standard (RFC 6902).
Patches are a sequence of JSON Patch operations contained in an array. The following patch will insert a number at a specific key and then test that it was added:
[{"op":"add", "path":"/price", "value" : 41},
{"op":"test", "path":"/price", "value": 41}]The available operations are:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }{ "op": "remove", "path": "/a/b/c" }{ "op": "replace", "path": "/a/b/c", "value": 43 }{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" }{ "op": "copy", "from": "/a/b/c", "path": "/a/b/e" }{ "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 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 fail with an error. 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.
the path of the topic to patch
the JSON Patch
optional constraint that must be satisfied for the patch to be applied
a Result that resolves when a response is received from the server.
If the task fails, the Result will reject with an error. Common reasons for failure include:
path;
path;
Creates an update stream to use for updating a specific topic.
The type of the topic being updated must match the type derived from the
dataType parameter.
Update streams send a sequence of updates for a specific topic. They can result in more efficient use of the network as only the differences between the current value and the updated value are transmitted. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.
Streams are validated lazily when the first set or validate operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.
Example:
const stream = session.topicUpdate.createUpdateStream('my_topic', diffusion.datatypes.string());
stream.set('hello');the path of the topic
the type of the values expected by the update stream
optional options object
an update stream
Creates an update stream builder to use for creating update streams.
an update stream builder
Sets the topic to a specified value.
null or undefined can only be passed to the
value parameter when updating
STRING,
INT64 or
DOUBLE topics.
When a topic of type STRING,
INT64 or
DOUBLE is set
to null or undefined , 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 undefined . New
subscribers will not receive a value notification.
Example:
session.topicUpdate.set('my_topic', diffusion.datatypes.string(), 'hello');the path of the topic
the type of the values
the value. String, int64, and double topics accept
null or undefined , as described above.
Using null or undefined with other
topic types is an error and will throw an Error .
optional options object
a Result that resolves when a response is received from the server. If a topic specification is provided in the options, the Result will resolve with a TopicCreationResult that contains the specification of the topic that was created.
If the task fails, the Result will resolve with an
Error.
This feature provides a client session with the ability to update topics.
Topics can be set to new values using stateless set operations or an UpdateStream. Both ensure that new values are applied safely to appropriate topics.
Additionally, JSON topics can be updated with a JSON Patch. 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
setto provide the complete value.Update streams
An update stream is created for a specific topic. An UpdateStreamBuilder can be obtained using TopicUpdate.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 error.
Applications can choose to use collaborative locking to coordinate exclusive access to a topic. To follow this pattern acquire a session lock, and use it with a lock constraint. 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 string, int64, or double topic 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 isnull. New subscribers will not receive a value notification. Attempting to set any other type of topic tonullwill cause an error 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 by providing a topic specification when calling set or 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 TopicUpdate.applyJsonPatch. The TimeSeries 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 path. Requests that combine adding a topic and setting the value require both permissions.
Accessing the feature
This feature may be obtained from a session as follows:
var topicUpdate = session.topicUpdate;6.2