Just a second...

Updating topics

A client can use the TopicUpdate feature to update topics.

A session can update a topic in one of the following ways:
Stateless set

Stateless set is a simple way to update the value of a topic.

The client does not retain any state information about the topic, meaning that delta streaming is not possible. If a session is expected to send frequent updates to a topic, consider using an update stream instead of stateless set.

Optimistic update streams

The TopicUpdate feature supports optimistic, non-exclusive update streams.

This stream type can use delta streaming like an exclusive updater, but does not prevent other sessions from updating the topic. It can detect when it no longer knows the latest value of the topic.

In addition, you can use the addAndSet method, which updates a specified topic if it is present, and creates and updates it if it is not present. This can be used statelessly or using an update stream.

JSON topics also support partial updates, a separate mechanism which enables you to update part of the topic value by applying a JSON Patch.

Conditional updates

Both stateless set and optimistic update streams support conditional updates.

Conditional updates enable a client to apply a constraint to a topic update. The topic is only updated if the constraint is satisfied (as evaluated on the Diffusion™ server).

Constraints can check the existence of the topic, the current value of the topic, or the existence of a session lock.

You can use conditional updates to enable coordination between sessions.

If your application requires that a particular session has exclusive access to a topic, you can achieve this by making updates conditional on having a session lock on the topic.

Partial updates

JSON topics support partial updating. This is carried out with an applyJsonPatch method, which works separately from stateless set and optimistic updates discussed below.

The advantage of making a partial update is that a client can change part of the value of the JSON topic without needing the full value. In addition, for a large or complex JSON value, partial updating can be faster than updating the whole value.

To make a partial update, you specify a patch using the JSON Patch standard (RFC 6902).

Patches are a sequence of JSON Patch operations contained in an array. The operations are applied as an atomic update to the previous value if the resulting update is successfully calculated.

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 following patch will check if the value at a specific key is equal to 22, and update it to 23 if the expected value is correct:

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

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, for example due to different key ordering, then the patch will return the index of the failed operation. For example, the values {"foo": "bar", "count": 43} and {"count": 43, "foo": "bar"} would not be considered equal, even though they have the same meaning.

A partial update can optionally take a constraint as with a conditional update. The patch will only be applied if the constraint is satisfied (this is evaluated prior to any JSON Patch test operations that might be specified within the patch).

Updating a topic with stateless set

Required permissions: update_topic

The set method replaces the current topic value with a new value.

Stateless set requires the following parameters:
Type

The type of the value.

Topic path

The path of the topic.

Value

The new value of the topic.

The primitive topic types (int64, double and string) support being set to null, but other types must be set to a value.
Note: From 6.2, if a primitive topic is set to null, new subscribers are not notified of the topic value until it changes to a non-null value.

The type of the topic being updated must match the type of value it is being set to.

Updating a topic with an optimistic non-exclusive updater

Required permissions: update_topic

To create an optimistic, non-exclusive update stream, a session must specify:
Type

The type of the value.

Topic path

The path of the topic.

The update stream is created immediately without interacting with the server.

  1. The stream can be updated with either set or addAndSet.
  2. On the first update operation, the stream is validated with the server. From then on, the stream can detect if there are any changes to the topic it is updating.
  3. If another session changes the topic, the update stream is invalidated and will stop accepting new values. Only one update stream at a time can be valid. Once a stream is invalidated, any attempt to use it results in an InvalidUpdateStreamException.
  4. The validate method validates the stream with the server without setting a new value.