Topic selectors | Documentation

Topic selector expressions

Use topic selector expressions to create a topic selector of one of the types described in the following table. The type of the topic selector is indicated by the first character of the expression.

Table 1. Types of topic selector
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 examples If 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

Split-path pattern and full-path pattern expressions can contain any regular expression, with the following restrictions:

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.

Note: Regular expressions have a moderate cost in terms of CPU usage. More complex regular expressions, using features such as back tracking, have a higher cost. However, the principal performance determinant is the number of topic paths a pattern expression is applied to. Topic selector expressions are evaluated hierarchically against the topic tree. Expressions that have longer topic path prefixes select less of the tree and are less costly. Similarly, split path patterns can be used to rapidly hone in on the interesting sub-set of the topic tree, so are usually preferable to full path patterns. If you are using very general pattern expressions or complex regular expressions, be sure to test the performance impact under realistic conditions.

Descendant pattern qualifiers in pattern expressions

You can modify split-path or full-path pattern expressions by appending a descendant pattern qualifier. These are described in the following table:

Table 2. 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.

Path expression examples

The following table contains examples of path expressions:

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

The following table contains examples of split-path pattern expressions:

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

The following table contains examples of full-path pattern expressions:

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.

The following example code shows how to use the anyOf(TopicSelector... selectors) method to create a selector set topic selector:

// 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

The following example code shows how to use the anyOf(String... selectors) method to create the same topic selector as in the previous code example, but in fewer steps:

// 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