diffusion/src/features/client-control.js

Diffusion JavaScript client

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

/**
 * Client control feature.
 * <p>
 * <br/>
 * Provides the ability for a client session to control other client sessions.
 * @example
 * var clients = session.clients;
 *
 * @namespace {ClientControl} Session.clients
 *
 * @property {Session.clients.SessionEventType} SessionEventType - Event types used within
 * {@link Session.clients.SessionPropertiesListener#onSessionEvent}.
 */
var ClientControl = _interface('ClientControl', [
    /**
     * Close a client session.
     *
     * @param {String|SessionId} sessionId - identifies the client session to close
     * @return {Result<Void>} - A {@link Result} for this operation.
     *
     * @example
     * session.clients.close(otherSessionID).then(function() {
     *     // Other session has been closed
     * }, function(err) {
     *     // There was an error when trying to close the other session
     * });
     * @function Session.clients#close
     */
    'close',

    /**
     * Subscribe one or more client sessions to topics.
     * <P>
     * To subscribe a single known session, a session id may be provided; alternatively, a Session Filter may be
     * used, in which case all sessions that satisfy the filter will be subscribed.
     * <P>
     * The second argument of this function can be a string, a {@link TopicSelector}, or an array of strings and
     * {@link TopicSelector}s.
     *
     * @param {String} session - The Session ID or Session Filter
     * @param {String | TopicSelector | String[]} selector - The Topic Selector to subscribe to
     * @return {Result<Number>} - A {@link Result<Number>} for this operation. If subscribing with a session
     * filter, the success
     * callback will be given the number of sessions selected by the filter
     *
     * @example
     * // Subscribe a single session via SessionID
     * session.clients.subscribe(otherSessionID, ">foo").then(function() {
     *     // Subscribed 'otherSession' to topic "foo"
     * }, function(err) {
     *     // Subscription failed
     *     console.log("Failed to subscribe session", err);
     * });
     *
     * @example
     * // Subscribe multiple sesssions via a Session Filter
     * session.clients.subscribe("$ClientType IS 'JAVA'", ">foo").then(function(selected) {
     *     console.log("Subscribed " + selected + " sessions to topic 'foo'");
     * }, function(err) {
     *     // Subscription failed
     *     console.log("Failed to subscribe sessions", err);
     * });
     * @function Session.clients#subscribe
     */
    'subscribe',

    /**
     * Unsubscribe one or more client sessions from topics.
     * <P>
     * To unsubscribe a single known session, a session id may be provided; alternatively, a Session Filter may be
     * used, in which case all sessions that satisfy the filter will be unsubscribed.
     * <P>
     * The second argument of this function can be a string, a {@link TopicSelector}, or an array of strings and
     * {@link TopicSelector}s.
     *
     * @param {String} session - The Session ID or Session Filter
     * @param {String | TopicSelector | String[]} selector - The Topic Selector to unsubscribe from
     * @return {Result<Number>} - A {@link Result<Number>} for this operation. If unsubscribing with a session
     * filter, the success
     * callback will be given the number of sessions selected by the filter
     *
     * @example
     * // Unsubscribe a single session via SessionID
     * session.clients.unsubscribe(otherSessionID, ">foo").then(function() {
     *     // Unsubscribed 'otherSession' from topic "foo"
     * }, function(err) {
     *     // Unsubscription failed
     *     console.log("Failed to unsubscribe session", err);
     * });
     *
     * @example
     * // Unsubscribe multiple sesssions via a Session Filter
     * session.clients.unsubscribe("$ClientType IS 'JAVA'", ">foo").then(function(selected) {
     *     console.log("Unsubscribed " + selected + " sessions from topic 'foo'");
     * }, function(err) {
     *     // Unsubscription failed
     *     console.log("Failed to unsubscribe sessions", err);
     * });
     * @function Session.clients#unsubscribe
     */
    'unsubscribe',

    /**
     * Query the server for property values of a specified client session.
     * <p>
     * <br />
     * See {@link Session.clients.PropertyKeys} for a list of the available
     * fixed property keys.
     * <p>
     * To request all fixed properties {@link
     * diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES ALL_FIXED_PROPERTIES} may be
     * included as the key.
     * <p>
     * To request all user properties {@link
     * diffusion.clients.PropertyKeys.ALL_USER_PROPERTIES ALL_USER_PROPERTIES} may be
     * included as the key.
     *
     * @example
     * // Get values of all fixed properties for client whose session id is 'id'.
     * session.clients.getSessionProperties(id, diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES);
     *
     * @example
     * // Get values of the 'FOO' and 'BAR' properties for client whose session id is 'id'.
     * session.clients.getSessionProperties(id, ['FOO', 'BAR']).then(function(properties) {
     *     console.log('Received properties for session', properties);
     * }, function(err) {
     *     console.log('Unable to receive properties: ', err);
     * });
     *
     *
     * @param {String} sessionID - Identifies the client session.
     * @param {Array} [requiredProperties] - Specifies the keys of the property values required.
     * @returns {Result} A {@link Result} for this operation.
     * @function Session.clients#getSessionProperties
     */
    'getSessionProperties',

    /**
     * Send a request to the server to change the user-defined session
     * properties for a session.
     *
     * @example
     * // Add a new session property for client whose session id is 'id'.
     * session.clients.setSessionProperties(id, { 'foo': 'bar' });
     *
     * // Remove a session property for client whose session id is 'id'.
     * session.clients.setSessionProperties(id, { 'foo': null }).then(function(properties) {
     *     console.log('Properties changed ', properties);
     * }, function(err) {
     *     console.log('Unable to change properties: ', err);
     * });
     *
     * @param {String} sessionID - identifies the client session
     * @param {Map<String, String>} properties - the properties to change. Each entry in the map is a
     *        property name and the new value. If the value is <code>null</code>, any
     *        existing property with that name will be removed. Otherwise if the
     *        property name does not match any existing property, that entry will
     *        be added as a new property.
     * @returns {Result<Map>} A {@link Result} for this operation. If the session properties were updated,
     *         the result type is a map of
     *         properties that changed with their previous values. If no
     *         properties were changed, the map will be empty. If any new properties
     *         were added, the values in the map will be <code>null</code> to
     *         indicate that they do not have an old value.
     *         <p>
     *         Otherwise, an error wil be returned. Common reasons for failure include:
     *         <ul>
     *         <li>
     *         {@link diffusion.errors.ACCESS_DENIED} if the calling session does not have sufficient permission.</li>
     *
     *         <li>
     *         {@link diffusion.errors.NO_SUCH_SESSION} if the calling session
     *         is closed before the response was delivered.</li>
     *
     *         <li>
     *         {@link diffusion.errors.SESSION_CLOSED} if the calling session is closed.</li>
     *         </ul>
     *
     * @function Session.clients#setSessionProperties
     */
    'setSessionProperties',

    /**
     * Send a request to the server to set all sessions that satisfy a session
     * filter with the new user-defined session properties.
     *
     * @example
     * // Remove session property {job=employee}
     * session.clients.setSessionPropertiesByFilter("job is 'employee'", { 'job': null }).then(function () {
     *     // All sessions satisfied the filter have updated their properties
     * }, function (err) {
     *     console.log("Failed to update properties ", err);
     * });
     *
     * @param {String} filter - session filter
     * @param {Map<String, String>} properties - the properties to change. Each entry in the map is a
     *        property name and the new value. If the value is <code>null</code>, any
     *        existing property with that name will be removed. Otherwise if the
     *        property name does not match any existing property, that entry will
     *        be added as a new property.
     *
     * @returns {Result<Void>} A {@link Result} for this operation. The operation can fail,
     *         common reasons for failure include:
     *         <ul>
     *         <li>
     *         {@link diffusion.errors.ACCESS_DENIED} if the calling session does not have sufficient permission.</li>
     *
     *         <li>
     *         {@link diffusion.errors.NO_SUCH_SESSION} if the calling session is closed
     *         before the response was delivered.</li>
     *
     *         <li>
     *         {@link diffusion.errors.SESSION_CLOSED} if the calling session is closed.</li>
     *         </ul>
     * @function Session.clients#setSessionPropertiesByFilter
     */
    'setSessionPropertiesByFilter',

    /**
     * Register a listener that will be notified when client sessions are
     * opened, disconnected, reconnected, closed or when selected session
     * property values are updated.
     * <p>
     * When a listener is first set, it will be called with the required
     * properties of all currently open client sessions. The amount of data
     * transferred from the server is proportional to the number of connected
     * clients and is potentially large. The amount of data can be reduced
     * using the requiredProperties parameter.
     * <p>
     * The requested property set controls the level of detail provided and
     * whether the listener is called for updates to sessions. If no
     * properties are requested then the listener is not called when session
     * properties are updated.
     * <p>
     * To request all fixed properties {@link diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES ALL_FIXED_PROPERTIES}
     * should be included as a key and any other fixed property keys would be ignored.
     * To request all user properties {@link diffusion.clients.PropertyKeys.ALL_USER_PROPERTIES ALL_USER_PROPERTIES}
     * should be included as a key and any other user property keys supplied would be ignored.
     *
     * @example
     * // Specify desired properties to listen to
     * var props = diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES;
     *
     * // Create the listener
     * var listener = {
     *     onActive : function(deregister) {
     *         // Listener is active
     *     },
     *     onSessionOpen : function(sessionID, properties) {
     *         // A session has been opened
     *     },
     *     onSessionEvent : function(sessionID, event, properties, previous) {
     *         // A session's properties have changed (specified by 'event')
     *     },
     *     onSessionClose : function(sessionID, properties, reason) {
     *         // A session has closed
     *     },
     *     onClose : function() {
     *         // Listener is closed
     *     }
     * }
     * session.clients.setSessionPropertiesListener(props, listener).then(function() {
     *     // Registration was succesful
     * }, function(err) {
     *     // There was an error registering the session listener
     * });
     *
     * @param {Array} requiredProperties - A set of required property keys.
     * @param {Session.clients.SessionPropertiesListener} listener - The listener to register
     * @returns {Result<undefined>} A {@link Result<undefined>} for this operation.
     * @function Session.clients#setSessionPropertiesListener
     */
    'setSessionPropertiesListener'
]);

/**
 * The Session Properties Listener interface for receiving session property events. This interface must be implemented
 * by the user, to be registered via {@link Session.clients#setSessionPropertiesListener}.
 * <P>
 * <br />
 * A session properties listener has a lifecycle that reflects the registration state on the server. This is expressed
 * through the callback methods. Once {@link Session.clients.SessionPropertiesListener#onClose onClose} has been
 * called, no further interactions will occur.
 *
 * @class Session.clients.SessionPropertiesListener
 */
ClientControl.SessionPropertiesListener = _interface('SessionPropertiesListener', [
    /**
     * Called when the listener has been registered at the server and is now active.
     * @param {Function} deregister - A function to call that will deregister and close this handler.
     * @function Session.clients.SessionPropertiesListener#onActive
     */
    'onActive',

    /**
     * Called when the listener is deregistered, or the session is closed.
     *
     * @function Session.clients.SessionPropertiesListener#onClose
     */
    'onClose',

    /**
     * Notification of a contextual error related to this handler. This is
     * analogous to an unchecked exception being raised. Situations in which
     * onError is called include the session being closed before the
     * handler is registered, a communication timeout, or a problem with the
     * provided parameters. No further calls will be made to this handler.
     *
     * @param {Error} error - The error
     * @function Session.clients.SessionPropertiesListener#onError
     *
     * @since 5.9
     */
    'onError',

    /**
     * Notification that a new client session has been opened.
     * <P>
     * <br />
     * When the listener is registered, this will be called for all existing sessions. It will then be
     * called for every client session that opens whilst the listener is registered.
     * <P>
     * This will be called for client session regardless of requested session properties.
     *
     * @param {Object} session - The session identifier
     * @param {Object} properties - The map of requested session property values.
     * @function Session.clients.SessionPropertiesListener#onSessionOpen
     */
    'onSessionOpen',

    /**
     * Notification of a session event that can result in a change of properties.
     *
     * @param {Object} session - The session identifier
     * @param {Session.clients.SessionEventType} type - The type of event
     * @param {Object} properties - The map of requested property values
     * @param {Object} previous - A map of previous values for keys that have changed. This will only contain changed
     * values and not the whole required property set.
     * @function Session.clients.SessionPropertiesListener#onSessionEvent
     */
    'onSessionEvent',

    /**
     * Notification that a client session has closed.
     * <P>
     * <br />
     * This will be called for every client that closes whilst the listener is registered, regardless of
     * requested session properties.
     *
     * @param {Object} session - The session identifier
     * @param {Object} properties - The map of requested property values
     * @param {Object} reason - The reason why the session was closed
     * @function Session.clients.SessionPropertiesListener#onSessionClose
     */
    'onSessionClose'
]);



/**
 * Event types used within {@link Session.clients.SessionPropertiesListener#onSessionEvent}.
 *
 * @example
 * session.clients.setSessionPropertiesListener(props, {
 *     // ...
 *
 *     onSessionEvent : function(sessionID, event, properties, previous) {
 *          switch (event) {
 *              case session.clients.SessionEventType.DISCONNECTED :
 *                  console.log(sessionID + " has disconnected");
 *                  break;
 *              case session.clients.SessionEventType.RECONNECTED :
 *                  console.log(sessionID + " has reconnected");
 *                  break;
 *          }
 *     }
 *
 *     // ...
 * });
 *
 * @readonly
 * @enum SessionEventType
 * @memberof Session.clients
 * @alias SessionEventType
 */
ClientControl.SessionEventType = {
    /** One or more relevant session properties have been updated. */
    UPDATED: 0,
    /** A session has reconnected. */
    RECONNECTED: 1,
    /** A session has failed over from one server to another in a cluster. */
    FAILED_OVER: 2,
    /** A session has disconnected. */
    DISCONNECTED: 3
};

module.exports = ClientControl;