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

Diffusion JavaScript client

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

/**
 * A constraint to be applied to an update operation or the creation of an
 * update stream.
 * <p>
 * Constraints describe a condition that must be satisfied for an operation to
 * succeed. Constraints can be applied to the setting of a value or creation
 * of an update stream. Constraints are only evaluated on the server.
 * <p>
 * The constraints are evaluated using the:
 * <ul>
 * <li>active session locks
 * <li>existence of the topic
 * <li>current value of the topic
 * </ul>
 * <p>
 * The value of a topic can be described in several ways. The value can be
 * described as an exact value, a partial value or an unset value.
 * <p>
 * Constraints can be composed with one another. It is only possible to
 * construct logical ANDs of constraints. Constraints can only be composed if
 * the resulting constraint is satisfiable. Multiple session locks can be held
 * but a topic can only have a single value. Constraints specifying multiple
 * topic values cannot be constructed.
 * <p>
 * Constraints can be created using a
 * {@link diffusion.topicUpdate.UpdateConstraintFactory}, an
 * instance of which can be obtained using
 * {@link diffusion#updateConstraints update constraints}.
 * For example:
 * <pre>
 * <code>
 * var factory = diffusion.updateConstraints();
 * var constraint = factory.locked(lock).and(factory.value(expectedValue));
 * </code>
 * </pre>
 *
 * @memberOf diffusion.topicUpdate
 * @class UpdateConstraint
 * @since 6.2
 */
var UpdateConstraint = _interface('UpdateConstraint', [

    /**
     * Returns a composed constraint that represents a logical AND of this
     * constraint and another.
     * <p>
     * If the composed constraint would be unsatisfiable, an <code>Error</code>
     * is thrown.
     *
     * @function diffusion.topicUpdate.UpdateConstraint#and
     * @param {diffusion.topicUpdate.UpdateConstraint} other a constraint that
     *        will be logically-ANDed with this constraint
     * @return {diffusion.topicUpdate.UpdateConstraint} a composed constraint
     *         that represents a logical AND of this constraint and the
     *         <code>other</code> constraint
     */
    'and',
]);


/**
 * A constraint requiring the current value of the
 * {@link TopicType#JSON JSON} topic to match the partially described value.
 * <p>
 * The code:
 * <pre>
 * <code>
 * var factory = diffusion.updateConstraints();
 * var constraint = factory.jsonValue().with("/id", idValue).without("/cancellation");
 * </code>
 * </pre>
 * creates a constraint for a JSON object with a specific ID value and no
 * value for a "cancellation" property.
 *
 * @memberOf diffusion.topicUpdate
 * @class PartialJSON
 * @extends UpdateConstraint
 * @since 6.2
 */
var PartialJSON = _interface('PartialJSON', UpdateConstraint, [
    /**
     * Require a value at a specific position in the JSON object.
     * <p>
     * The <code>pointer</code> is a
     * <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a>
     * syntax reference locating the <code>value</code> in the JSON object. If
     * the <code>pointer</code> parameter cannot be parsed as a JSON pointer an
     * <code>Error</code> is thrown.
     *
     * The function returns a new {@link diffusion.topicUpdate.PartialJSON PartialJSON}
     * object. The original object remains unmodified.
     *
     * @function diffusion.topicUpdate.PartialJSON#with
     * @param {String} pointer the pointer expression
     * @param {diffusion.datatypes.DataType} dataType the optional type of the value
     * @param {any} value the value
     * @return {diffusion.topicUpdate.UpdateConstraint} a new constraint
     */
    'with',

    /**
     * Require a specific position in the JSON object to be empty.
     * <p>
     * The <code>pointer</code> is a
     * <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> syntax
     * reference that should have no value in the JSON object. If the
     * <code>pointer</code> parameter cannot be parsed as a JSON pointer an
     * <code>Error</code> is thrown.
     *
     * The function returns a new {@link diffusion.topicUpdate.PartialJSON PartialJSON}
     * object. The original object remains unmodified.
     *
     * @function diffusion.topicUpdate.PartialJSON#without
     * @param {String} pointer the pointer expression
     * @return {diffusion.topicUpdate.UpdateConstraint} a new constraint
     */
    'without'
]);

/**
 * Factory for the constraint types.
 * <p>
 * An instance can be obtained by calling
 * {@link diffusion#updateConstraints diffusion.updateConstraints()}.
 *
 * @memberOf diffusion.topicUpdate
 * @class UpdateConstraintFactory
 * @since 6.2
 */
var UpdateConstraintFactory = _interface('UpdateConstraintFactory', [
    /**
     * Create a constraint requiring a lock to be held by the session.
     * <p>
     * This can be used to coordinate operations between multiple
     * sessions.
     *
     * @function diffusion.topicUpdate.UpdateConstraintFactory#locked
     * @param {SessionLock} lock the lock
     * @return {diffusion.topicUpdate.UpdateConstraint} the constraint
     */
    'locked',

    /**
     * Create a constraint requiring the current value of the topic to match
     * the supplied value.
     * <p>
     * Create a constraint requiring the current value of the topic to match
     * the supplied value.
     * <p>
     * If <code>dataType</code> is not specified, the data type is inferred
     * from the <code>value</code> parameter.
     * <p>
     * This method is useful when changing the value of a topic. This constraint
     * is unsatisfied if no topic is present at the path, making it unsuitable
     * for operations that try to add topics.
     * <p>
     * When a {@link diffusion.topics.TopicType#STRING string},
     * {@link diffusion.topics.TopicType#INT64 int64} or
     * {@link diffusion.topics.TopicType#DOUBLE double} topic is updated to a
     * {@code null} value, the topic is set to have no value. Use the
     * {@link #noValue()} constraint to check if the topic has no value.
     *
     * @function diffusion.topicUpdate.UpdateConstraintFactory#value
     * @param {any} value the value
     * @param {diffusion.datatypes.DataType} dataType the optional type of the
              values
     * @return {diffusion.topicUpdate.UpdateConstraint} the constraint
     */
    'value',

    /**
     * Create a constraint requiring the topic to have no value.
     * <p>
     * This is useful when setting the first value of a topic. This
     * constraint is unsatisfied if no topic is present at the path, making
     * it unsuitable for operations that try to add topics.
     *
     * @function diffusion.topicUpdate.UpdateConstraintFactory#noValue
     * @return {diffusion.topicUpdate.UpdateConstraint} the constraint
     */
    'noValue',

    /**
     * Create a constraint requiring the path to have no topic.
     * <p>
     * This is useful when setting the first value of a topic being added using
     * {@link Session.topicUpdate#addAndSet addAndSet} without changing the
     * value if the topic already exists. This constraint is unsatisfied if a
     * topic is present at the path, making it unsuitable for operations that
     * try to set topics without adding them.
     *
     * @function diffusion.topicUpdate.UpdateConstraintFactory#noTopic
     * @return {diffusion.topicUpdate.UpdateConstraint} the constraint
     */
    'noTopic',

    /**
     * Create a constraint that partially matches the current topic value.
     * <p>
     * The topic must be a {@link TopicType#JSON JSON} topic. The
     * {@link diffusion.topicUpdate.PartialJSON} partially describes the
     * structure of a {@link JSON} value.
     *
     * @function diffusion.topicUpdate.UpdateConstraintFactory#jsonValue
     * @return {diffusion.topicUpdate.PartialJSON} the constraint
     */
    'jsonValue'
]);

module.exports.UpdateConstraint = UpdateConstraint;
module.exports.PartialJSON = PartialJSON;
module.exports.UpdateConstraintFactory = UpdateConstraintFactory;