Topic selectors in the Unified API

Supported in: JavaScript^® Unified API, Java™ Unified API, .NET Unified API, Apple^® Unified API, Android™ Unified API, C Unified API

Pattern expressions

Use pattern 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 pattern expression.

Table 1. Types of topic selector
Topic selector type	Initial character	Description
Path	>	A path pattern expression must contain a valid topic path. A valid topic path comprises topic names separated by path separators (/). A topic name 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: Hash symbol (#) Question mark (?) Greater than symbol (>) Asterisk (*) Dollar sign ($) Percentage symbol (%) Ampersand (&) Less than symbol (<)	An abbreviated path pattern expression is an alternative syntax for a path pattern selector. It must be a valid topic path. A valid topic path comprises topic names separated by path separators (/). A topic name 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

Diffusion™ topic selectors use regular expressions. Any regular expression can be used in split-path and full-path patterns, with the following restrictions:

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 the Diffusion server. For more information, see Regular expressions.

Descendant pattern qualifiers

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.

Topic path prefixes

The topic selector capabilities in the Unified 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

The following table contains examples of path pattern expressions:

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	For clients using the Unified API, the period (.) and asterisk (*) characters are valid in topic names. In a path pattern expression these characters match themselves and are not evaluated as part of a regular expression.

Abbreviated path examples

The following table contains examples of abbreviated path pattern expressions:

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

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

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

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

Diffusion 5.9.24 User Manual