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 update streams.

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

Delta streaming can optionally be disabled. Disabling delta compression can reduce the CPU workload at the client at the cost of increased bandwidth and possible additional CPU load on the server (if the topic publishes deltas). This may be particularly useful for topics that have PUBLISH_VALUES_ONLY set.

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™ Cloud 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 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.

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

Updating a topic with an update stream

Required permissions: update_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.