diffusion/src/topic-update/update-stream.js

Diffusion JavaScript client

var _interface = require('util/interface')._interface;


/**
 * An update stream provides a method for updating a specific topic.
 * <p>
 * An update stream is associated with a specific topic. The type of the
 * topic must match the type of values passed to the update stream. It can
 * be created with an optional
 * {@link diffusion.topicUpdate.UpdateConstraint constraint}.
 * The existence of the topic, its type and the constraint are validated lazily
 * by the first {@link diffusion.topicUpdate.UpdateStream#set set} or
 * {@link diffusion.topicUpdate.UpdateStream#validate validate} operation.
 * Subsequent operations issued before the first operation completes will be
 * deferred until the completion of the first operation.
 * <p>
 * An update stream can be used to send any number of updates. It sends a
 * sequence of updates for a specific topic to the server. If supported by the
 * data type, updates will be sent to the server as a stream of binary deltas.
 * An update stream does not prevent other sessions from updating the topic. If
 * exclusive access is required update streams should be used with
 * {@link SessionLock session locks} as constraints.
 * <p>
 * Once validated an update stream can be invalidated. An invalidated
 * update stream rejects the operations applied to it. The update stream
 * will be invalidated if:
 * <ul>
 *     <li>the topic is removed
 *     <li>another update stream is created for the same topic
 *     <li>the topic is updated to a new value by anything other than the stream
 *     <li>the session does not have the
 *     {@link Session.security.TopicPermission#UPDATE_TOPIC update permission}
 *     <li>an operation fails because of cluster repartitioning
 * </ul>
 *
 * @memberOf diffusion.topicUpdate
 * @class UpdateStream
 * @since 6.2
 */
module.exports.UpdateStream = _interface('UpdateStream', [
    /**
     * 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 TopicType#STRING string},
     * {@link TopicType#INT64 int64} or {@link TopicType#DOUBLE double} topics.
     * <p>
     * When a topic of type {@link TopicType#STRING string},
     * {@link TopicType#INT64 int64} or {@link 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 diffusion.topicUpdate.UpdateStream#set
     * @param {any} value the value. Update streams for string, int64, and double
     *        topics accept <code>null</code> or <code>undefined</code>, as
     *        described above. Using null with other topic types is an error and
     *        will result in an <code>Error</code>.
     * @return a Result that completes when a response is received from the
     *         server.
     *
     *         <p>
     *         If the task fails, the Result will resolve with an
     *         <code>Error</code>.
     */
    'set',

    /**
     * Return the latest value of the topic set using this update stream.
     * <p>
     * The returned value reflects the last value that has been set, before it
     * is sent to the server.
     * <p>
     * If the server rejects a set operation, the topic value will not change
     * and this update stream will be invalidated.
     * <p>
     * This method will throw an <code>Error</code> if called before the first
     * call to {@link #set}
     *
     * @function diffusion.topicUpdate.UpdateStream#get
     * @return {any} the cached value of the topic
     */
    'get',

    /**
     * Validates the update stream.
     * <p>
     * Update streams are validated lazily when
     * {@link #set setting the value}. This method allows the stream to be
     * validated before a value needs to be set.
     * <p>
     * If the update stream has not been validated yet, calling this method
     * checks the topic exists, the topic type is correct, the constraint is
     * satisfied and the session has permission to update the topic. Once
     * it has been validated calling this method checks the topic has not been
     * removed, no other stream has been created for the topic, the value
     * of the topic has not been changed by anything else and the session
     * still has permission to update the topic. If validation fails, the Result
     * will resolve with an <code>Error</code>.
     * <p>
     * If this method fails all subsequent calls to {@link #set} or
     * {@link #validate} will resolve with an <code>Error</code>.
     *
     * @function diffusion.topicUpdate.UpdateStream#validate
     * @return {Result<diffusion.topicUpdate.TopicCreationResult>} a Result that completes when a
     *         response is received from the server.
     */
    'validate'
]);