Interface TopicSelectors
TopicSelector
s.
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.
An instance of this may be obtained as follows:
TopicSelectors selectors = Diffusion.topicSelectors();
- Since:
- 5.0
- Author:
- DiffusionData Limited
-
Method Summary
Modifier and TypeMethodDescriptionanyOf
(TopicSelector... selectors) Create aSELECTOR_SET
selector that matches if any of the providedselectors
match.Convenient wrapper ofanyOf(TopicSelector...)
that first parses the supplied expressions to create selectors.Parse an expression to create a selector.
-
Method Details
-
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. Thusa/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 selector set expression format is complex, The
anyOf(String...)
convenience method should be preferred over calling this method with a selector set expression. 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
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
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
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 - Parameters:
expression
- The topic selector expression.- Returns:
- The topic selector.
- Throws:
IllegalArgumentException
- Ifexpression
is not valid.IllegalArgumentException
- Ifexpression
is not one of the supported types.
-
anyOf
Convenient wrapper ofanyOf(TopicSelector...)
that first parses the supplied expressions to create selectors.- Parameters:
expressions
- The expressions.- Returns:
- A selector which matches any of
expressions
. - Throws:
IllegalArgumentException
- If one ofexpressions
cannot beparsed
.
-
anyOf
Create aSELECTOR_SET
selector that matches if any of the providedselectors
match.- Parameters:
selectors
- The selectors.- Returns:
- A selector which matches if any of
selectors
do.
-