Diffusion JavaScript API 6.2.8

Namespace: topicUpdate

Session. 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. The addAndSet method 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

Methods

createUpdateStream(path, dataType, options)

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

Parameters:
Name Type Description
path String

the path of the topic
dataType diffusion.datatypes.DataType

the type of the values expected by the update stream
options Object

Optional options object

Properties
Name Type Description
constraint diffusion.topicUpdate.UpdateConstraint

an optional constraint that must be satisfied for the topic to be updated.
specification diffusion.topics.TopicSpecification

an optional specification of the topic. If this is specified and the topic does not exist at the path, one will be created using specification. If a topic does exist, its specification must match specification, otherwise the operation will fail with an Error.
Returns:

an update stream

Type
diffusion.topicUpdate.UpdateStream

set(path, dataType, value, options)

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.

Parameters:
Name Type Description
path String

the path of the topic
dataType diffusion.datatypes.DataType

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.
options Object

Optional options object

Properties
Name Type Description
constraint diffusion.topicUpdate.UpdateConstraint

an optional constraint that must be satisfied for the topic to be updated.
specification diffusion.topics.TopicSpecification

an optional specification of the topic. If this is specified and the topic does not exist at the path, one will be created using specification. If a topic does exist, its specification must match specification, otherwise the operation will fail with an Error.
Returns:

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

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

Type
Result