diffusion/src/topics/fetch-request.js

Diffusion JavaScript client

var _interface = require('util/interface')._interface;
var Set = require('core-js/library/fn/set');
var TopicType = require('./topic-type');

/**
 * A fetch request.
 * <p>
 * This defines a fetch request to be made to the server. A new request can be
 * created using the {@link Session#fetchRequest fetchRequest} method and
 * modified to specify a range of topics and/or various levels of detail.
 * <p>
 * The fetch request is issued to the server using the {@link FetchRequest#fetch
 * fetch} method supplying a topic selector which specifies the selection of
 * topics.
 * <p>
 * A range is defined as being between two points of the topic tree which is
 * ordered in full path name order. So an example tree order would be:-<br>
 * a<br>
 * a/b<br>
 * a/c<br>
 * a/c/x<br>
 * a/c/y<br>
 * a/d<br>
 * a/e<br>
 * b<br>
 * b/a/x<br>
 * b/b/x<br>
 * c
 * <p>
 * The start point of a range can be specified using {@link #from from} or
 * {@link #after after} and an end point using {@link #to to} or {@link #before
 * before}. {@link #from from} and {@link #to to} include any topic with the
 * specified path in the selection, whereas {@link #after after} and {@link
 * #before before} are non inclusive and useful for paging through a potentially
 * large range of topics. If no start point is specified, the start point is
 * assumed to be the logical beginning of the topic tree. Similarly, if no end
 * point is specified, the end point is the logical end of the topic tree.
 * Ranges should be within the scope indicated by the topic selector used when
 * issuing the fetch.
 * <p>
 * As a minimum, the path and type of each topic selected will be returned. It
 * is also possible to request that the topic values and/or properties are
 * returned.
 * <p>
 * If values are selected then the topic types selected are naturally
 * constrained by the value class indicated. So if
 * {diffusion.datatypes.DataType.string} is specified, only {@link
 * diffusion.topics.TopicType#STRING STRING} topics will be selected. However,
 * if {diffusion.datatypes.DataType.json} is specified, all types compatible
 * with {@link JSON} will be selected including {@link
 * diffusion.topics.TopicType#STRING STRING}, {@link
 * diffusion.topics.TopicType#INT64 INT64} and {@link
 * diffusion.topics.TopicType#DOUBLE DOUBLE}. See {@link
 * diffusion.datatypes.DataType#canReadAs} for the class hierarchy of types.
 * <p>
 * To select topic types when values are not required, or to further constrain
 * the selection when values are required, it is also possible to specify
 * exactly which topic types to select.
 * <p>
 * A limit on the number of results returned can be specified using {@link
 * #first first}. This is advisable when the result set could potentially be
 * large. When such a limit is used then the result will indicate whether more
 * results for the same selection would be available via the {@link
 * diffusion.topics.FetchResult#hasMore hasMore} method.
 * <p>
 * The request can be sent to the server using {@link #fetch fetch} and the
 * results are returned (via a {@link Result<FetchResult>}) in path order,
 * earliest path first, starting from the beginning of any range specified.
 * <p>
 * It is also possible to request results from the end of the range indicated by
 * specifying a limit to the number of results using {@link #last last}. This
 * returns up to the specified number of results from the end of the range, in
 * path order. This is useful for paging backwards through a range of topics.
 * <p>
 * {@link TopicType#SLAVE Slave} topics are supported, in that if the slave
 * topic itself is within the requested selector/range and it is currently
 * linked to a topic that should be selected then a result will be returned for
 * the slave topic with the type/value/properties of the source topic.
 * <p>
 * {@link TopicType#ROUTING Routing} topics are <b>not</b> supported, and if
 * encountered will be ignored (i.e. treated as if they did not exist).
 * <p>
 * FetchRequest instances are immutable and can be safely shared and reused.
 *
 * @memberOf diffusion.topics
 * @class FetchRequest
 * @since 6.2
 */
var FetchRequest = _interface('FetchRequest', [

    /**
     * Specifies a logical start point within the topic tree.
     * <p>
     * If specified, only results for topics with a path that is lexically equal
     * to or 'after' the specified path will be returned.
     * <p>
     * This is the inclusive equivalent of {@link #after after} and if used will
     * override any previous {@link #after after} or {@link #from from}
     * constraint.
     *
     * @param {String} topicPath the topic path from which results are to be
     *        returned
     *
     * @return a new fetch request derived from this fetch request but
     *         selecting only topics from the specified path onwards
     *         (inclusive)
     * @function diffusion.topics.FetchRequest#from
     */
    'from',

    /**
     * Specifies a logical start point within the topic tree.
     * <p>
     * If specified, only results for topics with a path that is lexically
     * 'after' the specified path will be returned.
     * <p>
     * This is the non inclusive equivalent of {@link #from from} and if used
     * will override any previous {@link #from from} or {@link #after after}
     * constraint.
     *
     * @param {String} topicPath the topic path after which results are to be
     *        returned
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but selecting only topics after the specified path (not
     *         inclusive)
     * @function diffusion.topics.FetchRequest#after
     */
    'after',

    /**
     * Specifies a logical end point within the topic tree.
     * <p>
     * If specified, only results for topics with a path that is lexically equal
     * to or 'before' the specified path will be returned.
     * <p>
     * This is the inclusive equivalent of {@link #before before} and if used
     * will override any previous {@link #before before} or {@link #to to}
     * constraint.
     *
     * @param {String} topicPath the topic path to which results are to be
     *        returned
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
*              request but
     *         selecting only topics including and before the specified path
     *         (inclusive)
     * @function diffusion.topics.FetchRequest#to
     */
    'to',

    /**
     * Specifies a logical end point within the topic tree.
     * <p>
     * If specified, only results for topics with a path that is lexically
     * 'before' the specified path will be returned.
     * <p>
     * This is the non inclusive equivalent of {@link #to to} and if used
     * will override any previous {@link #to to } or {@link #before before}
     * constraint.
     *
     * @param {String} topicPath the topic path before which results are to be
     *        returned
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but selecting only topics before the specified path (not
     *         inclusive)
     * @function diffusion.topics.FetchRequest#before
     */
    'before',

    /**
     * Specifies that only topics of the specified topic types should be
     * returned.
     * <p>
     * If this is not specified, {@link diffusion.topics.getAllFetchTypes all
     * types} will be returned (unless constrained by {@link #withValues
     * withValues}).
     * <p>
     * This may be used instead to further constrain the results when using
     * {@link #withValues withValues}. For example, you can specify
     * {diffusion.datatypes.DataType.json} to {@link #withValues withValues}
     * then specify {@link diffusion.topics.TopicType#JSON JSON} here to ensure
     * that only JSON topics are returned and not those topics that are
     * logically value subtypes of JSON (e.g. {@link
     * diffusion.topics.TopicType#STRING STRING}).
     * <p>
     * If {@link #withValues withValues} has been specified then the types
     * specified here must be compatible with the value class specified.
     * <p>
     * Neither {@link diffusion.topics.TopicType#SLAVE SLAVE} nor {@link
     * diffusion.topics.TopicType#ROUTING ROUTING} may be specified as only
     * target topic types may be selected.
     *
     * @param {Array<diffusion.topics.TopicType>} topicTypes topic types to be
     *        selected
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but specifying that only topics of the specified topic
     *         types should be returned.
     *
     * @throws {Error} if invalid topic types are specified
     * @function diffusion.topics.FetchRequest#topicTypes
     */
    'topicTypes',

    /**
     * Specifies that values should be returned for selected topics,
     * constraining the selection to only those topics with a data type
     * compatible with the specified {@link diffusion.datatypes.DataType
     * DataType}.
     * <p>
     * The specified value constrains the topic types. So, any topic types
     * specified in a previous call to {@link #topicTypes topicTypes} that
     * cannot be read as the specified class will be removed from the list
     * of topic types.
     *
     * @param {diffusion.datatypes.DataType} dataType the type of values.
     *        If no value is specified this will cancel any previous call
     *        (topic types will remain unchanged).
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but specifying that only topics compatible with the
     *         specified class should be returned with values.
     *
     * @throws {Error} if the class is not compatible with any topic types.
     * @function diffusion.topics.FetchRequest#withValues
     */
    'withValues',

    /**
     * Specifies that all properties associated with each topic's {@link
     * diffusion.topics.TopicSpecification specification} should be returned.
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but specifying that topic specification properties should
     *         be returned.
     * @function diffusion.topics.FetchRequest#withProperties
     */
    'withProperties',

    /**
     * Specifies a maximum number of topic results to be returned from the start
     * of the required range.
     * <p>
     * If this is not specified, the number of results returned will only be
     * limited by other constraints of the request.
     * <p>
     * This should be used to retrieve results in manageable batches and prevent
     * very large result sets.
     * <p>
     * If there are potentially more results that would satisfy the other
     * constraints then the fetch result will indicate so via the {@link
     * diffusion.topics.FetchResult#hasMore hasMore} method.
     * <p>
     * Either this or {@link #last last} may be specified. This will therefore
     * override any previous {@link #last last} or {@link #first first}
     * constraint.
     *
     * @param {Number} number the maximum number of results to return from the
     *        start of the range
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but selecting only the number of topics specified from
     *         the start of the range
     * @function diffusion.topics.FetchRequest#first
     */
    'first',

    /**
     * Specifies a maximum number of topic results to be returned from the end
     * of the required range.
     * <p>
     * This is similar to {@link #first first} except that the specified number
     * of results are returned from the end of the range. This is useful for
     * paging backwards through a range of topics. Results are always returned
     * in topic path order (not reverse order).
     * <p>
     * Either this or {@link #first first} may be specified. This will therefore
     * override any previous {@link #first first} or {@link #last last}
     * constraint.
     *
     * @param {Number} number the maximum number of results to return from the
     *        end of the range
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request but selecting only the number of topics specified from
     *         the end of the range
     * @function diffusion.topics.FetchRequest#last
     */
    'last',

    /**
     * Specifies the maximum data size of the result set.
     * <p>
     * This may be used to constrain the size of the result. If not specified
     * then by default the maximum message size for the session (as specified by
     * {@link Session.Options.maxMessageSize} is used.
     *
     * @param {Number} maximumSize the maximum size of the result set in bytes.
     *        If a value greater than the session's maximum message size is
     *        specified, the maximum message size will be used.
     *
     * @return {FetchRequest} a new fetch request derived from this fetch
     *         request butconstraining the size of the result to the specified
     *         maximum
     * @function diffusion.topics.FetchRequest#maximumResultSize
     */
    'maximumResultSize',

    /**
     * Sends a fetch request to the server.
     * <p>
     * Results are returned for all topics matching the selector that satisfy
     * the request constraints within any range defined by {@link #from
     * from}/{@link #after after} and/or {@link #to to}/{@link #before before}.
     * <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[] }
     *        topics specifies a topic selector which selects the topics to be
     *        fetched
     *
     * @return {Result<FetchResult>} a Result that resolves with a
     *         {@link diffusion.topics.FetchResult FetchResult} when a response
     *         is received from the server with the results of the fetch
     *         operation.
     *         <p>
     *         If the task completes successfully, the FetchResult returned by
     *         the Result will be an object encapsulating all of the results.
     *         <p>
     *         Otherwise, the Result will resolve with an Error.
     *         </ul>
     * @function diffusion.topics.FetchRequest#fetch
     */
    'fetch'
]);

/**
 * Encapsulates the results from a fetch operation issued to the server.
 * <p>
 * A fetch operation is issued using a {@link diffusion.topics.FetchRequest
 * fetch request} which will return a result of this type via a {@link Result}.
 *
 * @template V The result value type. This will be any type unless the request
 *           indicated that {@link diffusion.topics.FetchRequest#withValues
 *           values} are to be returned, in which case this will be the data
 *           type requested.
 *
 * @memberOf diffusion.topics
 * @class FetchResult
 * @since 6.2
 */
var FetchResult = _interface('FetchResult', [

    /**
     * Returns the results from the fetch operation.
     * <p>
     * Results are always returned in path order.
     *
     * @return {Array<diffusion.topics.TopicResult<V>>} a list of
     *         {@link diffusion.topics.TopicResult TopicResult}s,
     *         each representing a result single topic selected by the fetch
     *         operation.
     * @function diffusion.topics.FetchResult#results
     */
    'results',

    /**
     * Indicates whether the fetch could have returned more results if it had
     * not been constrained by the {@link diffusion.topics.FetchRequest#first
     * first}, {@link diffusion.topics.FetchRequest#last last} or {@link
     * diffusion.topics.FetchRequest#maximumResultSize maximumResultSize}
     * limits.
     *
     * @return {Boolean} true if more results could have been returned,
     *         otherwise false
     * @function diffusion.topics.FetchResult#hasMore
     */
    'hasMore'
]);

/**
 * Encapsulates the result of a {@link diffusion.topics.FetchRequest#fetch
 * fetch} invocation for a single selected topic.
 *
 * @template V The result value type. TThis will be any type unless the request
 *        indicated that {@link diffusion.topics.FetchRequest#withValues values}
 *        are to be returned, in which case this will be the data type
 *        requested.
 *
 * @memberOf diffusion.topics
 * @class TopicResult
 * @since 6.2
 */
var TopicResult = _interface('TopicResult', [

    /**
     * Returns the topic path.
     *
     * @return {String} the topic path
     * @function diffusion.topics.TopicResult#path
     */
    'path',

    /**
     * Returns the topic type.
     *
     * @return {diffusion.topics.TopicType} the topic type
     * @function diffusion.topics.TopicResult#type
     */
    'type',

    /**
     * Returns the topic value.
     * <p>
     * This will only return a value if the fetch request specified {@link
     * diffusion.topics.FetchRequest#withValues withValues} and the topic
     * actually had a value. For topics that have no value this will return
     * undefined.
     *
     * @return the topic value or undefined if none available
     * @function diffusion.topics.TopicResult#value
     */
    'value',

    /**
     * Returns the topic specification.
     * <p>
     * If the request specified {@link
     * diffusion.topics.FetchRequest#withProperties withProperties}, the result
     * reflect the topic's specification and can be used to create an identical
     * topic. If the request did not specify {@link
     * diffusion.topics.FetchRequest#withProperties withProperties}, the
     * specification's property map will be empty.
     *
     * @return {diffusion.topics.TopicSpecification} the topic specification
     * @function diffusion.topics.TopicResult#specification
     */
    'specification'
]);


/**
 * Return a set of all topic types that can be fetched.
 *
 * @returns {Array<diffusion.topics.TopicType>} the topic types that can be
 * fetched by a FetchRequest
 * @function getAllTypes
 * @memberOf diffusion.topics.FetchRequest
 */
function getAllTypes() {
    return new Set([
        TopicType.JSON,
        TopicType.BINARY,
        TopicType.RECORD_V2,
        TopicType.DOUBLE,
        TopicType.INT64,
        TopicType.STRING,
        TopicType.TIME_SERIES
    ]);
}

module.exports.FetchRequest = FetchRequest;
module.exports.FetchRequest.getAllTypes = getAllTypes;
module.exports.FetchResult = FetchResult;
module.exports.TopicResult = TopicResult;