Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface TopicUpdate

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

A session does not have to be subscribed to a topic to update it.

Constraints can be applied to the setting of a value and creation of an update stream. Constraints describe a condition that must be satisfied for the operation to succeed. The constraints are evaluated on the server. The available constraints are: an active session lock, the current value of the topic being updated and a part of the current value of the topic being updated.

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. Attempting to set any other type of topic to null or undefined will cause an Error to be thrown.

Access control

To update any topic a session needs update topic permission covering the topic. To create any topic a session needs modify topic permission covering the topic. Requests that combine adding a topic and setting the value will require both permissions for either action to happen. An UpdateStream cannot be used to add a topic successfully but fail to set its value because the update topic is missing.

Accessing the feature

This feature may be obtained from a session as follows:

var topicUpdate = session.topicUpdate;
since

6.2

Hierarchy

  • TopicUpdate

Implemented by

Index

Methods

applyJsonPatch

  • 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:

    • 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 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.

    see
    JavaScript Object Notation (JSON) Patch
    since

    6.4

    Parameters

    • path: string

      the path of the topic to patch

    • patch: string | Array<object>

      the JSON Patch

    • Optional constraint: UpdateConstraint

      optional constraint that must be satisfied for the patch to be applied

    Returns Result<JsonPatchResult>

    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:

    • the patch is not a valid JSON Patch;
    • applying the patch fails;
    • there is no topic bound to {@code path};
    • the patch cannot be applied to the topic, for example if the topic type is not {@link DataTypes.JSON}.
    • updates cannot be applied to the topic because an exclusive update source is registered for its path;
    • the topic is managed by a component (such as fan-out) that prohibits updates from the caller;
    • the cluster was repartitioning;
    • the calling session does not have the UPDATE_TOPIC permission for path;
    • the session is closed.

createUpdateStream

  • 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');

    Parameters

    • path: string

      the path of the topic

    • dataType: DataType<any, any, any>

      the type of the values expected by the update stream

    • Optional options: TopicUpdateOptions

      optional options object

    Returns UpdateStream

    an update stream

set

  • 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');

    Parameters

    • path: string

      the path of the topic

    • dataType: DataType<any, any, any>

      the type of the values

    • value: any

      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: TopicUpdateOptions

      optional options object

    Returns Result<void>

    a Result that resolves when a response is received from the server.

    If the task fails, the Result will resolve with an Error .