Topic selectors
A topic selector defines a set of topics paths that identify topics. You can create a topic selector from a topic selector expression.
Topic selector expressions
Topic selector type | Initial character | Description |
---|---|---|
Path | > | A path expression must contain a valid topic path. A valid topic path comprises path segments separated by path separators (/). A path segment comprises one or more UTF characters except for slash (/). A path selector returns only the topic with the given path. See Path expression examplesIf the first character is not one of #, ?, >, *, $, %, & or <, the initial '>' can be omitted. |
Split-path | ? | A split-path pattern expression contains a list of regular expressions separated by the / character. Each regular expression describes a part of the topic path. The selector returns topics for which each regular expression matches the part of the topic path at the corresponding level. See Split-path pattern expression examples |
Full-path | * | A full-path pattern expression contains a regular expression. A full-path pattern topic selector returns topics for which the regular expression matches the full topic path. See Full-path pattern expression examples |
Selector set | # | A selector set expression contains a list of selectors separated by
the separator ////. A selector set topic selector returns
topics that match any of the selectors. Note: Use the
anyOf() method for a simpler method of constructing
selector set topic selectors.
See Selector set expression examples |
Topic path prefixes
The topic selector capabilities in the Diffusion™ API provide methods that enable you to get the topic path prefix from a topic selector.
A topic path prefix is a concrete topic path to the most specific part of the topic tree that contains all topics that the selector can specify. For example, for the topic selector ?foo/bar/baz/.*/bing, the topic path prefix is foo/bar/baz.
The topic path prefix of a selector set is the topic path prefix that is common to all topic selectors in the selector set.
Regular expressions in pattern expressions
- A regular expression cannot be empty
- In split-path pattern expressions, a regular expression cannot contain the path separator (/)
- In full-path pattern expressions, a regular expression cannot contain the selector set separator (////)
Depending on what the topic selector is used for, regular expressions in topic selectors can be evaluated on the client or on Diffusion Cloud. For more information, see Regular expressions.
Descendant pattern qualifiers in pattern expressions
Qualifier | Behavior |
---|---|
None | Select only those topics that match the selector. |
/ | Select only the descendants of the matching topics and exclude the matching topics. |
// | Select both the matching topics and their descendants. |
Path expression examples
Expression | Matches alpha/beta? | Matches alpha/beta/gamma? | Notes |
---|---|---|---|
>alpha/beta | yes | no | |
alpha/beta | yes | no | |
>/alpha/beta/ | yes | no |
This path expression is equivalent to the path expression in the preceding row. In an absolute topic path, single leading or trailing slash characters (/) are removed because the topic path is converted to canonical form. A path expression can match a maximum of one topic. The trailing slash in this example is not treated as a descendant qualifier and is removed. |
>alpha/beta/gamma | no | yes | |
alpha/beta/gamma | no | yes | |
>beta | no | no | The full topic path must be specified for a path expression to match a topic. |
>.*/.* | no | no | The period (.) and asterisk (*) characters are valid in path segments. In a path expression these characters match themselves and are not evaluated as part of a regular expression. |
.*/.* | no | no | |
>$topic$ | no | no | This expression matches a single topic path $topic. The leading > is required because the first character is $. |
Split-path pattern expression examples
Expression | Matches alpha/beta? | Matches alpha/beta/gamma? | Notes |
---|---|---|---|
?alpha/beta | yes | no | |
?alpha/beta/ | no | yes | The trailing slash character (/) is treated as a descendant pattern qualifier in split-path pattern expressions. It returns descendants of the matching topics, but not the matching topics themselves. |
?alpha/beta// | yes | yes | Two trailing slash characters (//) is treated as a descendant pattern qualifier in split-path pattern expressions. It returns matching topics and their descendants. |
?alpha/beta/gamma | no | yes | |
?beta | no | no | |
?.* | no | no | Each level of a topic path must have a regular expression specified for it for a split-path pattern expression to match a topic. |
?.*/.* | yes | no | |
?alpha/.*// | yes | yes | In this pattern expression, "alpha/.*" matches all topics in the alpha branch of the topic tree. The descendant pattern qualifier (//) indicates that the matching topics and their descendants are to be returned. |
Full-path pattern expression examples
Expression | Matches alpha/beta? | Matches alpha/beta/gamma? | Notes |
---|---|---|---|
*alpha/beta | yes | no | |
*alpha/beta/gamma | no | yes | |
*alpha/beta/ | no | yes | The trailing slash character (/) is treated as a descendant pattern qualifier in full-path pattern expressions. It returns descendants of the matching topics, but not the matching topics themselves. |
*alpha/beta// | yes | yes | Two trailing slash characters (//) is treated as a descendant pattern qualifier in full-path pattern expressions. It returns matching topics and their descendants. |
*beta | no | no | In a full-path pattern selector the regular expression must match the full topic path for a topic to be matched. |
*.*beta | yes | no | The regular expression matches the whole topic path including topic separators (/). |
Selector set expression examples
Use the anyOf methods to create a selector set TopicSelector object.
// Use your session to create a TopicSelectors instance TopicSelectors selectors = Diffusion.topicSelectors(); // Create topic selectors for the individual topic selector expressions TopicSelector pathSelector = selectors.parse(">foo/bar"); TopicSelector splitPathSelector = selectors.parse("?f.*/bar\d+"); TopicSelector fullPathSelector = selectors.parse("*f.*\d+"); // Use the individual topic selectors to create the selector set topic selector TopicSelector selector = selectors.anyOf(pathSelector, splitPathSelector, fullPathSelector); // Use the topic selector as a parameter to methods that perform actions on topics or groups of topics
// Use your session to create a TopicSelectors instance TopicSelectors selectors = Diffusion.topicSelectors(); // Create the selector set topic selector by passing in a list of // pattern expressions TopicSelector selector = selectors.anyOf(">foo/bar", "?f.*/bar\d+", "*f.*\d+"); // Use the topic selector as a parameter to methods that perform actions on topics or groups of topics
This page last modified: 2020/06/25