Class TopicSelectors

parse

• parse(expression: string | TopicSelector | Array<string | TopicSelector>, ...args: Array<string | TopicSelector>): TopicSelector

• 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");

  throws

  an IllegalArgumentError if the expression could not be parsed

  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.