diffusion/src/diffusion.js

Diffusion JavaScript client

var InternalSessionFactory = require('client/internal-session-factory');
var SessionImpl = require('session/session-impl');

var DataTypes = require('data/datatypes');
var Topics = require('./topics/topics');
var TopicUpdate = require('./topic-update/topic-update');
var TopicSelectors = require('./selectors/topic-selectors');
var ErrorReason = require('./errors/error-reason');
var ErrorReport = require('services/error-report');
var ClientControlOptions = require('./features/client-control-options');
var SessionLockOptions = require('./features/session-lock-options');
var updateConstraintFactory = require('topic-update/update-constraint-factory');

var DiffusionGlobals = require('diffusion/diffusion-globals');

var log = require('util/logger');
log.setLevel('SILENT');

/**
 * The top-level Diffusion API.
 * <P>
 * Provides access to Session connections and global namespaces.
 *
 * @namespace diffusion
 *
 * @property {String} version - The version of this client library in the form major.minor.patch
 * @property {diffusion.topics} topics - Access to the topics namespace.
 * @property {diffusion.topicUpdate} topicUpdate - Access to the topicUpdate namespace.
 * @property {diffusion.clients} clients - Access to PropertyKeys.
 * @property {diffusion.selectors} selectors - Access to the selectors namespace.
 * @property {diffusion.datatypes} datatypes - Access to the datatypes namespace.
 * @property {diffusion.locks} locks - Access to the locks namespace.
 * @property {ErrorReport} errorReport - Access to the ErrorReport class.
 */
var diffusion = {
    /*
     * The version of this client library in the form major.minor.patch
     */
    version: '6.2.6',

    build: '6_01#62945',

    /**
     * Set the level of logging used by Diffusion. This will default to silent. Log levels are strings that represent
     * different degrees of information to be logged. Available options are:
     * <ul>
     * <li>silent</li>
     * <li>error</li>
     * <li>warn</li>
     * <li>info</li>
     * <li>debug</li>
     * </ul>
     *
     * @function diffusion#log
     * @param {String} level - The log level to use.
     */
    log: function (level) {
        log.setLevel(level);
    },

    /**
     * Connect to a specified Diffusion server. This will return a {@link Result} that will complete succesfully
     * if a session can be connected, or fail if an error was encountered.
     * <P>
     * If the result is succesful, the fulfilled handler will be called with a {@link Session} instance. This
     * session will be in a connected state and may be used for subsequent API calls.
     * <P>
     * If the result fails, the rejected handler will be called with an error reason.
     *
     * @example
     * diffusion.connect('example.server.com').then(function(session) {
     *     // Connected with a session
     *     console.log('Connected!', session);
     * }, function(error) {
     *     // Connection failed
     *     console.log('Failed to connect', error);
     * });
     *
     *
     * @function diffusion#connect
     *
     * @param {Session.Options|String} [options] - The options to construct the session with.
     * @returns {Result<Session>} A {@link Result<Session>} for this operation
     */
    connect: function (options) {
        return SessionImpl.create(InternalSessionFactory, options);
    },

    /**
     * Escapes special characters in a string that is to be used within a topic
     * property or a session filter.
     * <P>
     * This is a convenience method which inserts an escape character '\' before
     * any of the special characters ' " or \.
     *
     * @param {String} string - the string to be escaped
     * @returns {String} the string value with escape characters inserted as appropriate
     * @since 6.1
     */
    escape: function(string) {
        return DiffusionGlobals.escape(string);
    },

    /**
     * Utility method which converts a string of the format required by the
     * {@link Session#ROLES $Roles} session property into a mutable set of
     * strings.
     *
     * @param {String} string the string with quoted roles separated by whitespace or
     *        commas
     *
     * @return {Set<String>} set of roles
     *
     * @since 6.2
     */
    stringToRoles: function(string) {
        return DiffusionGlobals.stringToRoles(string);
    },

    /**
     * Utility method which converts a set of authorisation roles to the string
     * format required by the {@link Session#ROLES $Roles} session property.
     *
     * @param {Set<String>|Array<String>} roles a set of roles
     *
     * @return {String} a string representing the supplied roles, formatted as required
     *         by the {@link Session#ROLES $Roles} session property
     *
     * @since 6.2
     */
    rolesToString: function(roles) {
        return DiffusionGlobals.rolesToString(roles);
    },

    /**
     * Returns an update constraint factory.
     *
     * @function diffusion#updateConstraints
     * @return {diffusion.topicUpdate.UpdateConstraintFactory} update constraint
     *         factory
     * @since 6.2
     */
    updateConstraints: function() {
        return updateConstraintFactory;
    },

    datatypes: DataTypes,

    selectors: TopicSelectors,

    topics: Topics,

    topicUpdate: TopicUpdate,

    errors: ErrorReason,

    errorReport: ErrorReport,

    clients: ClientControlOptions,

    locks: SessionLockOptions
};

module.exports = diffusion;