Special characters in topics

A topic can contain any character in the Unicode character set. However, the following three characters have a special meaning:
  • The topic level separator "/".
  • The multilevel wild card "#".
  • The single-level wild card "+".

The topic level separator is used to introduce structure into the topic, and can therefore be specified within the topic for that purpose.

The multilevel wild card and single-level wild card can be used for subscriptions, but they cannot be used within a topic by the publisher of a message.

However, if a publisher uses the characters "+" or "#" together with other characters in any topic level within a topic, these characters are not treated as wild cards, and they do not have any special meaning.

The topic level separator

The topic level separator character "/" is used to provide a hierarchical structure to the topic space. It must be used by applications to separate levels within a topic tree. The use of the topic level separator is significant when the two wildcard characters are encountered in topics specified by subscribers.

Topic hierarchy is important in the administration of access control.

The multilevel wild card

The multilevel wildcard character "#" is used to match any number of levels within a topic. For example, using the example topic tree shown above, if you subscribe to "USA/Alaska/#", you receive messages on topics "USA/Alaska" and "USA/Alaska/Juneau".

The multilevel wild card can represent zero or more levels. Therefore, "USA/#" can also match the singular "USA", where # represents zero levels. The topic level separator is meaningless in this context, because there are no levels to separate.

The multilevel wild card can be specified only on its own or next to the topic level separator character. Therefore, "#" and "USA/#" are valid topics where the "#" character is treated as a wild card. However, although "USA#" is also a valid topic, the "#" character is not regarded as a wild card and does not have any special meaning. See When wild cards are not wild for more information.

The single-level wild card

The single-level wildcard character "+" matches one, and only one, topic level. For example, "USA/+" matches "USA/Alabama", but not "USA/Alabama/Auburn". Also, because the single-level wild card matches only a single level, "USA/+" does not match "USA".

The single-level wild card can be used at any level in the topic tree, and in conjunction with the multilevel wild card. The single-level wild card must be specified next to the topic level separator, except when it is specified on its own. Therefore, "+" and "USA/+" are valid topics where the "+" character is treated as a wild card. However, although "USA+" is also a valid topic, the "+" character is not regarded as a wild card and does not have any special meaning. See When wild cards are not wild for more information.

When wild cards are not wild

The wildcard characters "+" and "#" have no special meaning when they are mixed with other characters (including themselves) in a topic level.

This means that topics that contain "+" or "#" together with other characters in a topic level can be published.

For example, consider the following two topics:

  1. level0/level1/+/level4/#
  2. level0/level1/#+/level4/level#

In the first example, the characters "+" and "#" are treated as wild cards and are therefore not valid in a topic that is to be published.

In the second example, the characters "+" and "#" are not treated as wild cards and therefore the topic can be both published and subscribed to.

Related concepts
Topics
Related reference
Topic semantics and usage