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 usingspecification
. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail with anError
.Returns:
an update stream
-
set(path, dataType, value, options)
-
Sets the topic to a specified value.
null
orundefined
can only be passed to thevalue
parameter when updating STRING, INT64 or DOUBLE topics.When a topic of type STRING, INT64 or DOUBLE is set to
null
orundefined
, the topic will be updated to have no value. If a previous value was present subscribers will receive a notification that the new value isundefined
. 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
orundefined
, as described above. Usingnull
orundefined
with other topic types is an error and will throw anError
.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 usingspecification
. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail with anError
.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