diffusion
Version:
Diffusion JavaScript client
129 lines (124 loc) • 6.5 kB
JavaScript
var _interface = require('util/interface')._interface;
/**
* This feature provides a client session with the ability to update topics.
* <p>
* A session does not have to be subscribed to a topic to update it.
* <p>
* 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.
* <p>
* When a topic of type {@link diffusion.topics.TopicType#STRING STRING},
* {@link diffusion.topics.TopicType#INT64 INT64} or
* {@link diffusion.topics.TopicType#DOUBLE DOUBLE} is set to <code>null</code>
* or <code>undefined</code>, 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 <code>undefined</code>. New subscribers will not receive a value
* notification. Attempting to set any other type of topic to <code>null</code>
* or <code>undefined</code> will cause an <code>Error</code> to be thrown.
* <H3>Access control</H3>
* <p>
* To update any topic a session needs
* {@link Session.security.TopicPermission#UPDATE_TOPIC update topic}
* permission covering the topic. To create any topic a session needs
* {@link Session.security.TopicPermission#MODIFY_TOPIC 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 {@link Session.topicUpdate#addAndSet addAndSet} method cannot be used to
* add a topic successfully but fail to set its value because the
* {@link Session.security.TopicPermission#UPDATE_TOPIC update topic}
* is missing.
* <H3>Accessing the feature</H3>
* <p>
* This feature may be obtained from a {@link Session session} as follows:
*
* <pre>
* var topicUpdate = session.topicUpdate;
* </pre>
*
* @namespace Session.topicUpdate
* @since 6.2
*/
module.exports.TopicUpdate = _interface('TopicUpdate', [
/**
* Sets the topic to a specified value.
* <p>
* <code>null</code> or <code>undefined</code> can only be passed to the
* <code>value</code> parameter when updating
* {@link diffusion.topics.TopicType#STRING STRING},
* {@link diffusion.topics.TopicType#INT64 INT64} or
* {@link diffusion.topics.TopicType#DOUBLE DOUBLE} topics.
* <p>
* When a topic of type {@link diffusion.topics.TopicType#STRING STRING},
* {@link diffusion.topics.TopicType#INT64 INT64} or
* {@link diffusion.topics.TopicType#DOUBLE DOUBLE} is set
* to <code>null</code> or <code>undefined</code>, 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 <code>undefined</code>. New
* subscribers will not receive a value notification.
*
* @function Session.topicUpdate#set
* @param {String} path the path of the topic
* @param {diffusion.datatypes.DataType} dataType the type of the values
* @param {any} value the value. String, int64, and double topics accept
* <code>null</code> or <code>undefined</code>, as described above.
* Using <code>null</code> or <code>undefined</code> with other
* topic types is an error and will throw an <code>Error</code>.
* @param {Object} options Optional options object
* @param {diffusion.topicUpdate.UpdateConstraint} options.constraint an
* optional constraint that must be satisfied for the topic to be
* updated.
* @param {diffusion.topics.TopicSpecification} options.specification an
* optional specification of the topic. If this is specified and the
* topic does not exist at the <code>path</code>, one will be created
* using <code>specification</code>. If a topic does exist, its
* specification must match <code>specification</code>, otherwise the
* operation will fail with an <code>Error</code>.
* @return {Result} a Result that resolves when a response is received
* from the server.
* <p>
* If the task fails, the Result will resolve with an
* <code>Error</code>.
*/
'set',
/**
* Creates an {@link diffusion.topicUpdate.UpdateStream update stream} to
* use for updating a specific topic.
* <p>
* The type of the topic being updated must match the type derived from the
* <code>valueClass</code> parameter.
* <p>
* 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 {@link SessionLock session
* locks} as constraints.
* <p>
* Streams are validated lazily when the first
* {@link diffusion.topicUpdate.UpdateStream#set set} or
* {@link diffusion.topicUpdate.UpdateStream#validate validate} operation is
* completed. Once validated a stream can be invalidated, after which it
* rejects future updates.
*
* @function Session.topicUpdate#createUpdateStream
* @param {String} path the path of the topic
* @param {diffusion.datatypes.DataType} dataType the type of the values
* expected by the update stream
* @param {Object} options Optional options object
* @param {diffusion.topicUpdate.UpdateConstraint} options.constraint an
* optional constraint that must be satisfied for the topic to be
* updated.
* @param {diffusion.topics.TopicSpecification} options.specification an
* optional specification of the topic. If this is specified and the
* topic does not exist at the <code>path</code>, one will be created
* using <code>specification</code>. If a topic does exist, its
* specification must match <code>specification</code>, otherwise the
* operation will fail with an <code>Error</code>.
* @return {diffusion.topicUpdate.UpdateStream} an update stream
*/
'createUpdateStream'
]);