Topic selectors
A topic selector identifies one or more topics. You can create a topic selector object from a pattern expression.
Pattern expressions
Topic selector type | Initial character | Description |
---|---|---|
Path | > | A path pattern 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 examples |
Abbreviated path | Any character except the following:
|
An abbreviated path pattern expression is an alternative syntax for a path
pattern selector. It must be a valid topic path. A path pattern 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 (/). Abbreviated path pattern expressions are converted into PATHselectors and return only the topic with the given path. See Abbreviated path examples |
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. A SPLIT_PATH_PATTERN selector returns topics for which each regular expression matches the part of the topic path at the corresponding level. See Split-path examples |
Full-path | * | A full-path pattern expression contains a regular expression. A
FULL_PATH_PATTERN selector returns topics for which the
regular expression matches the full topic path. See Full-path examples
Note: Full-path pattern topic selectors are more powerful than
split-path pattern topic selectors, but are evaluated less efficiently at the
server. If you are combining expressions, use selector sets
instead.
|
Selector set | # | A selector set pattern 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 examples |
Regular expressions
- It cannot be empty
- In split-path patterns, it cannot contain the path separator (/)
- In full-path patterns, it 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
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. |
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.
Path examples
Expression | Matches alpha/beta? | Matches alpha/beta/gamma? | Notes |
---|---|---|---|
>alpha/beta | yes | no | |
>/alpha/beta/ | yes | no |
This pattern expression is equivalent to the pattern 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 pattern expression can return 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 | |
>beta | no | no | The full topic path must be specified for a path pattern expression to match a topic. |
>.*/.* | no | no | The period (.) and asterisk (*) characters are valid in path segments. In a path pattern expression these characters match themselves and are not evaluated as part of a regular expression. |
Abbreviated path examples
Expression | Matches alpha/beta? | Matches alpha/beta/gamma? | Notes |
---|---|---|---|
alpha/beta | yes | no | |
/alpha/beta/ | yes | no |
This pattern expression is equivalent to the pattern expression in the preceding row. In an absolute topic path, single leading and trailing slash characters (/) are removed because the topic path is converted to canonical form. A path pattern expression can return 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 | |
beta | no | no | The full topic path must be specified for a path pattern expression to match a topic. |
Split-path 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 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 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. |
*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 examples
Use the anyOf methods to create a SELECTOR_SET TopicSelector object.
// Use your session to create a TopicSelectors instance TopicSelectors selectors = session.topicSelectors(); // Create topic selectors for the individual pattern 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 = session.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: 2018/04/06