diffusion/src/events/stream.js

Diffusion JavaScript client

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

/**
 * A {@link Stream} provides a series of events that may be consumed by arbitrary listeners. The events emitted by a
 * stream are defined by the operation that created the stream and can carry event-specific arguments.
 * <P>
 * <br />
 * A stream is created in an open state, and may immediately emit events. When a Stream is closed it will emit a 
 * <code>close</code>. A closed stream will not emit any further events, and will remain closed permanently.
 * <P>
 * It is possible for a stream to encounter an error. In this case, an <code>error</code> event will be emitted, and
 * then the stream will be closed.
 * <P>
 * This is a primitive class that is used to provide common event binding methods to other API components.
 *
 * @fires Stream#error
 * @fires Stream#close
 *
 * @class Stream
 */
module.exports = _interface('Stream', [
    /**
     * Register listeners against events.
     * <P>
     * A single listener may be bound to an event by passing the event name and
     * listener function.
     * <P>
     * Multiple listeners may be bound by passing in an object, mapping event names
     * to listener functions.
     *
     * @example
     * // Bind a single listener to the 'foo' event
     * stream.on('foo', function(arg1, arg2) {
     *     console.log("Called for 'foo' event", arg1, arg2);
     * });
     *
     * @example
     * // Bind multiple listeners
     * stream.on({
     *     foo : function() { ... },
     *     bar : function() { ... },
     *     baz : function() { ... }
     * });
     *
     * @param {(String|Object)} events - The event name or object mapping event names to listeners
     * @param {Function} [listener] - The listener to bind to the event, if passed as string.
     * @returns {Stream} This stream.
     *
     * @function Stream#on
     */
    'on',

    /**
     * Remove a listener from a specified event.
     *
     * @example
     * // Bind a single listener to the 'foo' event and then deregister it
     * var listener = function() {};
     * stream.on('foo', listener);
     * stream.off('foo', listener);
     *
     * @example
     * // Bind a listener to the 'foo' event and deregister all listeners
     * var listener = function() {};
     * stream.on('foo', listener);
     * stream.off('foo');
     *
     * @param {String} event - The event to remove listeners from
     * @param {Function} [listener] - The listener to remove.
     * All listeners for the event are removed if this is not specified
     *
     * @returns {Stream} This stream.
     * @function Stream#off
     */
    'off',

    /**
     * Close the stream. This will emit a 'close' event to any assigned listeners. No further events will be emitted.
     *
     * @function Stream#close
     */
    'close'

    /**
     * Emitted when an error occurs in the {@link Stream} or in any of its listeners.
     * No further events will be emitted after this.
     *
     * @event Stream#error
     * @property {Error} error - the error that occurred
     */

    /**
     * Emitted when the {@link Stream} has been closed through completion or the underlying session has been closed.
     * No further events will be emitted after this.
     *
     * @event Stream#close
     */
]);