Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TopicSelectors

Create TopicSelector instances for use with other API methods.

Selectors are evaluated against topic paths. A topic path is a '/' separated string of parts, which map to the topic tree. Each part is formed of one or more UTF characters, except '/'. Topic paths are absolute, and evaluated from the root of the topic tree.

Example:

// Create a topic selector
var selector = diffusion.selectors.parse('?foo/bar/.*');

Hierarchy

  • TopicSelectors

Index

Properties

Methods

Properties

Prefix

Prefix: Prefix = Prefix

The Prefix enum

Type

Type: Type = Type

The Type enum

Methods

parse

  • Parse an expression to create a selector.

    The following types of expression are supported. The type is determined by the first character of the expression.

    Path
    Path expressions begin with the character >. The remainder of the expression must be a valid topic path. A topic path is a '/' separated string of parts. Each part is formed of one or more UTF characters, except '/'.

    A PATH selector is returned that only selects the topic with the given path.

    The initial > can be omitted if the path begins with a character other than one of #, ?, >, *, $, %, &, or <. This abbreviated syntax allows most topic paths to be used directly as selector expressions which appears more natural. Abbreviated path expressions are converted to standard path expressions by prepending the > character. Thus a/b is interpreted as >a/b.

    Diffusion.topicSelectors().parse("a/b").getExpression() will return ">a/b".

    Split-path pattern
    Split-path pattern expressions begin with the character ?. The remainder of the expression is split into a list of regular expressions using the / character as a separator.

    A SPLIT_PATH_PATTERN selector is returned that selects topics for which each regular expression matches each part of the topic path at the corresponding level.

    Full-path pattern
    Full-path pattern expressions begin with the character *. The remainder of the pattern is a regular expression.

    A FULL_PATH_PATTERN selector is returned that selects topics for which the regular expression matches the complete topic path.

    Full-path patterns provide a lot of expressive power but should be used sparingly since the server can evaluate split-path patterns more efficiently.

    Selector sets are the preferred way to combine expressions. anyOf("a", "b") is equivalent to the full-path expression " * /a|/b", but can be evaluated more efficiently by the server.

    Selector set
    Selector set expressions begin with the character #. The remainder of the expression is a list of contained selectors, formatted as described below.

    A SELECTOR_SET selector is returned that selects topics that match any of the contained selectors.

    The contained selectors are formatted as follows. First, any selector sets are expanded to produce a full list of non-selector set expressions. Then the selector expressions are concatenated, separated by the separator ////. This separator has been chosen as it is not valid in a path, and is not a useful sequence in a pattern.

    Descendant pattern qualifiers

    Split-path and full-path pattern expressions can be further modified by appending / or //. These control the behavior of the selector with respect to the descendants of the topics that match the pattern.

    • If the expression does not end with / or //, it selects only the topics that match the pattern.
    • If the expression ends with /, it selects only the descendants of the matching topics, excluding the matching topics.
    • If the expression ends with //, it selects the matching topics and all of their descendants.

    Regular expressions

    Any Java-style regular expression can be used in split-path and full-path patterns, with the following restrictions:

    • A regular expression may not be empty.
    • A regular expression used in split-path patterns may not contain the path separator /.
    • A regular expression used in full-path patterns may not contain the selector set separator //// .

    Regular expressions that break any of these restrictions would never match a topic path, so they make no practical difference.

    Examples

    Path expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    >alpha/beta yes no
    alpha/beta yes no
    >alpha/beta/gamma no yes
    alpha/beta/gamma no yes
    >beta no no
    beta no no
    >.*`/.*` no no
    >/alpha/beta/ yes no
    /alpha/beta/ yes no

    Split-path pattern expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    ?alpha/beta yes no
    ?alpha/beta/gamma no yes
    ?beta no no
    ?.* no no
    ?.*`/.*` yes no
    ?alpha/beta/ no yes
    ?alpha/beta// yes yes
    ?alpha/.*`//` yes yes

    Full-path pattern expressions

    Path Matches alpha/beta? Matches alpha/beta/gamma?
    *alpha/beta yes no
    *alpha/beta/gamma no yes
    *beta no no
    *.*beta yes no
    *.* yes yes
    *alpha/beta/ no yes
    *alpha/beta// yes yes

    Example:

    // Simple selector
    var selector = diffusion.selectors.parse(">a/b");

    Example:

    // Creating a selector set
    var selectorSet = diffusion.selectors.parse(">a", ">b");

    Parameters

    • expression: string | TopicSelector | Array<string | TopicSelector>

      the pattern expression(s). At least one valid selector has to be specified.

    • Rest ...args: Array<string | TopicSelector>

      additional pattern expressions

    Returns TopicSelector

    the topic selector. If multiple expressions are provided, this will return a SELECTOR_SET that will match if any of the * provided selectors match.