diffusion/src/events/value-stream.js

Diffusion JavaScript client

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

/**
 * Provides a stream of topic events, specific to the topic selector that this ValueStream was created for, with
 * topic values provided as instances of the associated {@link DataType}.
 * <P>
 * ValueStream inherits all functions defined on {@link Stream}.
 * <P>
 *
 * @example
 * // Create a value stream for topic 'foo'
 * session.addStream('foo', datatype).on('value', function(topic, specification, newValue, oldValue) {
 *     // Receive updates for the topic 'foo'
 * });
 *
 * // Then subscribe to topic 'foo'
 * session.select('foo');
 *
 *
 * @example
 * // Attach multiple listeners for events
 * session.addStream('foo', datatype).on({
 *     subscribe : function(topic, specification) {
 *         // Subscribed to a particular topic
 *     },
 *     unsubscribe : function(topic, specification, reason) {
 *         // Unsubscribed from a particular topic
 *     },
 *     value : function(topic, specification, newValue, oldValue) {
 *         // Value from a topic
 *     }
 * });
 *
 *
 * @class ValueStream
 *
 * @fires ValueStream#open
 * @fires ValueStream#close
 * @fires ValueStream#value
 * @fires ValueStream#subscribe
 * @fires ValueStream#unsubscribe
 * @fires ValueStream#error
 *
 * @augments Stream
 *
 * @property {String} selector The selector this subscription was created for
 */
module.exports = _interface('ValueStream', Stream, [
    /**
     * A static reference to the selector this Subscription was created for.
     *
     * @property {String} ValueStream.selector
     */
    'selector',

    /**
     * Close the stream. No further events will be emitted.
     *
     * This does not unsubscribe the topic. Other streams may still recieve
     * updates for the same topic selector. To unsubscribe, use {@link
     * Session#unsubscribe}
     *
     * @function ValueStream#close
     */
    'close'
    /**
     * Emitted when the subscription is initially opened, passing a reference to the subscription itself. This will
     * only be fired once.
     * @event ValueStream#open
     */

    /**
     * Emitted when a topic that is selected by this ValueStream's topic selector is subscribed
     * to by this session.
     * Once subscribed, <code>value</code> update events may be received for this topic. The specification is a
     * {@link TopicSpecification} instance that contains details about the topic.
     *
     * @event ValueStream#subscribe
     * @property {String} topic - the topic to which the subscription applies
     * @property {diffusion.topics.TopicSpecification} specification - instance that contains details about the topic
     */

    /**
     * Emitted when a topic that was previously subscribed, has been unsubscribed. No further update events will be
     * received from this topic until subscribed again. Unsubscriptions may occur due to the topic being removed, or
     * through calling {@link Session#unsubscribe} - an object containing the reason is provided.
     *
     * @event ValueStream#unsubscribe
     * @property {String} topic - the topic to which the unsubscription applies
     * @property {diffusion.topics.TopicSpecification} specification - instance that contains details about the topic
     * @property {diffusion.topics.UnsubscribeReason} reason - the reason for the unsubscription
     */

    /**
     * Emitted when an update has been received for a topic's value. Values will be provided as instances appropriate
     * for the associated {@link DataType} this subscription was created for. Both the previous value and
     * the new value are provided.
     *
     * @event ValueStream#value
     * @property {String} topic - the topic to which the update applies
     * @property {diffusion.topics.TopicSpecification} specification - instance that contains details about the topic
     * @property {object} newValue - the new value of the topic
     * @property {object} oldValue - the old value of the topic
     */

    /**
     * Emitted when the subscription has been closed using {@link ValueStream#close}.
     *
     * @event ValueStream#close
     */

    /**
     * Emitted when the subscription request fails. No further events will be emitted after this.
     *
     * @event ValueStream#error
     * @property {ErrorReason} error - the error the subscription request failed with
     */
]);