diffusion/src/features/topic-notifications.js

Diffusion JavaScript client

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

/**
 * Topic notifications feature.
 * <P>
 * <br />
 * Allows a client session to receive notifications about changes to selected topics.
 *
 * @namespace Session.notifications
 */

module.exports.TopicNotifications = _interface('TopicNotifications', [
    /**
     * Register a {@link TopicNotificationListener} to receive topic notifications.
     *
     * @param {TopicNotificationListener} listener - the listener to receive topic notifications
     * @returns {Result<TopicNotificationRegistration>} A {@link Result<TopicNotificationRegistration>}
     * for this operation
     * @function Session.notifications#addListener
     */
    'addListener'
]);

/**
 * Listener for topic notifications.
 *
 * @class TopicNotificationListener
 */
module.exports.TopicNotificationListener = _interface('TopicNotificationListener', [
    /**
     * Notification for an immediate descendant of a selected topic path. This notifies the presence or absence of
     * a descendant topic that may subsequently be explicitly selected.
     *
     * @param {String} topicPath - the path of the selected immediate descendant
     * @param {Session.notifications.TopicNotificationType} type - the type of notification
     * @function TopicNotificationListener#onDescendantNotification
     */
    'onDescendantNotification',

    /**
     * A notification for a selected topic.
     *
     * @param {String} topicPath - the path of the selected topic
     * @param {diffusion.topics.TopicSpecification} specification - the specification of the topic that this
     * notification is for
     * @param {Session.notifications.TopicNotificationType} type - the type of notification
     * @function TopicNotificationListener#onTopicNotification
     */
    'onTopicNotification',

    /**
     * Called when the listener is closed. The listener will be closed if the session is closed, or if the listener is
     * closed by the {@link TopicNotificationRegistration}
     * <P>
     * Once closed, no further calls will be made to the listener.
     *
     * @function TopicNotificationListener#onClose
     */
    'onClose',

    /**
     * Notification of a contextual error related to this listener. This is
     * analogous to an Error being thrown. Situations in which
     * <code>onError</code> is called include the session being closed before the
     * listener is registered, a communication timeout, or a problem with the
     * provided parameters. No further calls will be made to this listener.
     *
     * @param {Object} error - The error
     *
     * @function TopicNotificationListener#onError
     */
    'onError'
]);

/**
 * The TopicNotificationRegistration represents the registration state of the associated listener on the server.
 * <p>
 * The TopicNotificationRegistration provides operations to control which topic paths the listener will receive
 * notifications for. It can also close the listener and remove it from the server.
 *
 * @class TopicNotificationRegistration
 */
module.exports.TopicNotificationRegistration = _interface('TopicNotificationRegistration', [
    /**
     * Request to receive notifications for all topics matched by the provided topic selector.
     * <P>
     * This function can take any number of arguments. Each argument can be a string
     * or a {@link TopicSelector}. Alternatively, an array of strings and
     * {@link TopicSelector}s can be passed as a single argument.
     *
     * @param {...String | TopicSelector | String[] }
     *        topicSelector - the selector to register
     * @returns {Result<undefined>} A {@link Result<undefined>} for this operation
     * @function TopicNotificationRegistration#select
     */
    'select',

    /**
     * Request to stop receiving notifications for all topics matched by the given selector.
     * <P>
     * This function can take any number of arguments. Each argument can be a string
     * or a {@link TopicSelector}. Alternatively, an array of strings and
     * {@link TopicSelector}s can be passed as a single argument.
     *
     * @param {...String | TopicSelector | String[] }
     *        topicSelector - the selector to register
     * @returns {Result<undefined>} A {@link Result<undefined>} for this operation
     * @function TopicNotificationRegistration#deselect
     */
    'deselect',

    /**
     * Request that the listener is unregistered from the server.
     * @function TopicNotificationRegistration#close
     */
    'close'
]);

function TopicNotificationType(id) {
    this.id = id;
}

/**
 * The type of topic notification that has been received.
 *
 * @readonly
 * @enum TopicNotificationType
 * @memberof Session.notifications
 * @alias TopicNotificationType
 */
module.exports.TopicNotificationType = {
    /**
     * The topic was added.
     */
    ADDED : new TopicNotificationType(0),

    /**
     * The topic existed at the time of the selector registration.
     */
    SELECTED : new TopicNotificationType(1),

    /**
     * The topic was removed.
     */
    REMOVED : new TopicNotificationType(2),

    /**
     * The topic was deselected.
     */
    DESELECTED : new TopicNotificationType(3)
};