diffusion/src/features/topics.js

Diffusion JavaScript client

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

var Topics = _interface('Topics', [
    /**
     * Unsubscribe the client from a given topic selector.
     * <P>
     * No more updates will be received from the server for any topics matched
     * by the selector. If no topics exist that match the selector, the server will do nothing.
     * <P>
     * Each topic that this session is unsubscribed from will cause an <code>unsubscribe</code>
     * event. Any {@link Subscription} objects produced from {@link Session#subscribe}
     * or {@link Session#stream} will remain open, and will continue to emit
     * updates for topics that the session has not been unsubscribed from.
     * <P>
     * The returned result will complete normally if the session has been unsubscribed. It will fail if the session is
     * unable to unsubscribe, for instance due to security constraints.
     * <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.
     *
     * @example
     * // Unsubscribe from a single topic
     * session.unsubscribe('foo');
     *
     * @example
     * // Unsubscribe from multiple topics
     * session.unsubscribe('?foo/.*');
     *
     * @param {...String | TopicSelector | String[] }
     *        selector - The topic selector to unsubscribe from.
     * @returns {Result<undefined>} A {@link Result<undefined>} for this operation
     * @function Session#unsubscribe
     */
    'unsubscribe',

    /**
     * Fetch the current state of one or more topics.
     * <P>
     * Fetching a topic will provide its current value without subscribing this client to that topic. The returned
     * {@link FetchStream} will emit <code>value</code> events for each topic that is matched for which a fetch request
     * can be satisfied. Once complete, the {@link FetchStream} will be closed.
     * <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.
     *
     * @example
     * // Fetch a topic's value
     * session.fetch("foo").on('value', function(value, path) {
     *     console.log("Value for topic '" + path + "' is: " + value);
     * });
     *
     * @example
     * // Fetch multiple topics, handling possible errors
     * session.fetch("?foo/bar.*").on({
     *     value : function(value, path) { ... },
     *     error : function(error) { ... },
     *     close : function() { ... }
     * });
     *
     * @deprecated since 6.2
     *             <p>
     *             Prefer the use of {@link #fetchRequest()} instead. Unlike
     *             this method fetchRequest supports additional query
     *             constraints, returns type-safe values, and optionally allows
     *             topic properties to be retrieved. This will be removed in a
     *             future release.
     *
     * @param {...String | TopicSelector | String[] }
     *        selector - The topic selector to fetch
     * @returns {FetchStream} A {@link FetchStream} that will emit the fetched values.
     * @function Session#fetch
     */
    'fetch',


    /**
     * Creates an unconfigured fetch request.
     * <P>
     * If the request is invoked by calling {@link FetchRequest#fetch fetch},
     * the fetch result will provide the paths and types of all of the topics
     * which the session has permission to read.
     * <p>
     * Usually the query should be restricted to a subset of the topic tree, and
     * should retrieve the topic values and/or properties. This is achieved by
     * applying one or more of the fluent builder methods to produce more
     * refined requests.
     * <p>
     *
     * @example
     * // Create and send a fetch request. Then pass the results to a resultHandler
     * session.fetchRequest()
     *        .withValues(diffusion.datatypes.StringDataType)
     *        .fetch("*A/B//")
     *        .then(resultHandler);
     *
     * @see diffusion.topics.FetchRequest
     *
     * @returns {diffusion.topics.FetchRequest} a new unconfigured fetch request
     * @function Session#fetchRequest
     *
     * @since 6.2
     */
    'fetchRequest',

    /**
     * Subscribe the session to a topic selector in order to receive updates and
     * subscription events.
     * <P>
     * Subscription causes the server to establish a subscription for this
     * session to any topic that matches the specified selector, including topics
     * that are added after the initial call to {@link Session#select}.
     * <P>
     * If the provided selector string does not begin with one of the prefixes
     * defined by {@link TopicSelectors}, it will be treated as a direct topic
     * path.
     * <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.
     *
     * @example
     * // Subscribe to a topic foo
     * session.select("foo").then(function() {
     *     // Successfully subscribed
     * }, function(err) {
     *     // There was an error with subscribing to topic "foo"
     * });
     *
     * @param {...String | TopicSelector | String[] }
     *        selector - The topic selector to subscribe to.
     * @returns {Result} for this operation
     * @function Session#select
     */
    'select',

    /**
     * Create a {@link ValueStream} to receive updates from topics that match the provided topic selector.
     * <P>
     * This method will not cause the server to send any topic updates unless already subscribed. This allows the
     * registration of listeners prior to subscribing via {@link Session.topics#select}, or to add/remove listeners
     * independently of subscriptions on the server.
     * <P>
     * The values as specific types, use the
     * Streams will only receive values from topics for which the specified {@link diffusion.datatypes Data Type}
     * is compatible.
     * <P>
     * The first argument of this function can be a string, a {@link TopicSelector}, or an array of strings and
     * {@link TopicSelector}s.
     *
     * @example
     * // Produce a value stream for receiving JSON values.
     * var json = diffusion.datatypes.json();
     *
     * session.addStream(topic, json).on('value', function(topic, specification, newValue, oldValue) {
     *   	console.log('New value ', newValue.get());
     * });
     *
     * @param {String | TopicSelector | String[]} selector
     *        - The topic selector to receive updates for
     * @param {DataType} datatype - The data type to produce a stream for.
     * @returns {ValueStream} A new {@link ValueStream} for the provided data type
     * @function Session#addStream
     */
    'addStream',

    /**
     * This adds a value stream for a given {@link diffusion.datatypes Data Type} without a selector which
     * will be a fallback stream to receive all events that do not have a stream registered.
     *
     * @example
     * // Produce a fallback value stream for receiving JSON values.
     * var json = diffusion.datatypes.json();
     *
     * session.addFallbackStream(json).on('value', function(topic, specification, newValue, oldValue) {
     *   	console.log('New value ', newValue.get());
     * });
     *
     * @param {DataType} datatype - The data type to produce a stream for.
     * @returns {FallbackStream} - a fallback stream
     * @function Session#addFallbackStream
     */
    'addFallbackStream'
]);

module.exports = Topics;