Supported in: JavaScript^® Classic API, Java™ Classic API, .NET Classic API, C Classic API, iOS^® Classic API, Android™ Classic API, Flash^® Classic API, Silverlight^® Classic API

Including subordinate topics

When specifying a topic name you can also indicate that all of its subordinate topics are to be included by suffixing the name with a slash character (/).

For example, to select all of the subordinate topics of a topic named MyTopic use a selector of the format MyTopic/.

This notation can also be used with topic paths. So to select all topics subordinate to the topic named A/B, use a selector of the following format:

A/B/

Specifying a suffix of "/" does not include the topic named prior to the final "/". To include the specified topic and all of its subordinates, use "//".

For example, to select the topic A/B and all of its subordinates, specify the following selector:

A/B//

Fuzzy matching

A number of topics can be selected using a single topic selector which uses regular expressions to match against topic names.

Regular expressions provide a powerful mechanism for String pattern matching which is not discussed here. A Java tutorial is available for those familiar with Java or a more generic tutorial can be consulted for other language users. The regular expression syntax supported by Diffusion™ is defined by the Java Pattern class.

The important point to note about the use of regular expressions in topic selectors is that they have multiple parts (separated by /) and that each part of a selector can be a regular expression pattern. A multi-part selector is evaluated part by part starting from the top level of the topic tree in an attempt to find a matching topic in the tree.

If there is no "/" in the selector string but there are regex characters then the whole string is applied as a regex against the full topic name. This can be useful in some circumstances, for example when you do not know how many topic levels exist but it is far less efficient than per-level matching.

Example of selector regular expression processing

Consider the following topic selector:

A.*/B/.*X

As the above selector has three specifications it only matches with topic names with three parts.

The first check is to select any topics at the top-level of the topic tree whose name matches the pattern "A.*". In regular expression notation this pattern matches with any String that starts with "A" and is followed by zero or more other characters. So if there are no top-level topics that start with an "A" then this selector matches with no topics at all. However, for any top-level topic that does match, processing goes to the next part which is a simple String "B" and only matches with a subordinate topic called "B". So if any topics called "B" are found under the top-level topics starting with "A", processing goes onto the final pattern ".*X" which in regex notation indicates any String with any number of characters before a final "X" (a String ending with "X").

So to summarize, the above selector matches only with topic paths with 3 elements where the first element starts with an "A", the second element is "B" and the third element ends with an "X".

The following are matches:

Accounts/B/TAX

A/B/X

Admin/B/ProjectX

But the following are not:

Accounts/TAX

Admin/B/ProjectYHR/B/TAX

If you do not know how many levels you are dealing with but want to select topics where the lowest level topic name is ABC, you must use a whole topic name selector as follows:

.*\x2FABC

The use of "\x2F" is necessary to represent a "/" as otherwise the selector evaluates per level.

So this selector matches with:

A/B/ABCX/Y/ZZZ/wwwwww/ABC

but not with:

A/B/CABC

Mixed Mode selectors

It is permitted to mix regex pattern handling and subordinate topic suffixes in the same topic selector pattern.

So it is permitted to use a selector of the form A.*/Address/ which has the effect of selecting all of the topics subordinate to the topic named Address within any top level topic starting with "A".

Selector examples

When is a topic string a selector?

In certain parts of the APIs only topic names can be specified (for example, when adding a topic) but in other areas selectors are allowed (for example, in subscription).

A topic string is considered to be a selector if it is terminated by a "/" or it contains any one of the regular expression metacharacters which are defined as the following characters: []\^$.|?*+()