Wildcards

Three characters have special meaning in publish/subscribe. These characters are the forward slash (/), the number sign (#), and the plus sign (+). For more information about the forward slash (/), see Topic Strings.

In JMS topics, these characters are allowed anywhere in a topic string, but use them with caution.

In MQTT topics, the number sign (#), and the plus sign (+) cannot be used in publish topics. In subscribe topics, the number sign (#) can only be used as the last character in the topic string, and must be the only character in that level.

The number sign (#)

Used in combination with '/' to construct a multilevel wildcard in subscriptions. Take care using '#' next to '/' in topic strings that are used to name published JMS topics.

The plus sign (+)

Used in combination with '/' to construct a single-level wildcard in subscriptions.

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

There are two types of wildcard:

Multilevel wildcard

• The multilevel wildcard is used in subscriptions.
• The multilevel wildcard character '#' is used to match any number of levels within a topic. For example, using the example topic tree, if you subscribe to 'Sport/Tennis/#', you receive messages on topics 'Sport/Tennis', and 'Sport/Tennis/Finals'.
• The multilevel wildcard can represent zero or more levels. Therefore, 'Sport/#' can also match the singular 'Sport', where '#' represents zero levels. The topic level separator is meaningless in this context, because there are no levels to separate.
• The multilevel wildcard is only effective when specified on its own or next to the topic level separator character. Therefore, '#' and 'Sport/#' are valid topics where the '#' character is treated as a wildcard. For JMS topics, although 'Sport#' is also a valid topic string, the '#' character is not regarded as a wildcard and does not have any special meaning. See When topic-based wildcards are not wild for more information. For MQTT topics, the multilevel wildcard can only be used as the last character in the topic string, and must be the only character in that level.

Single level wildcard

• The single wildcard is used in subscriptions.
• The single-level wildcard character '+' matches one, and only one, topic level. For example, 'Sport/+' matches 'Sport/Tennis', but not 'Sport/Tennis/Finals'. Because the single-level wildcard matches only a single level, 'Sport/+' does not match 'Sport'.
• For JMS and MQTT topics, the single-level wildcard can be used at any level in the topic tree. The single-level wildcard must be specified next to the topic level separator, except when it is specified on its own. Therefore, '+' and 'Sport/+' are valid topics where the '+' character is treated as a wildcard. For JMS topics, although 'Sport+' is a valid topic string, the '+' character is not regarded as a wildcard and does not have any special meaning. For more information, see the section When topic-based wildcards are not wild.

When topic-based wildcards are not wild

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

For JMS topics, this means that topics that contain '+' or '#' together with other characters in a topic level can be published.

Consider the following two JMS topics:

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

In the first example, the characters '+' and '#' are treated as wildcards and are therefore not valid in a topic string that is to be published to but are valid in a subscription.

In the second example, the characters '+' and '#' are not treated as wildcards, and therefore the topic string can be both published and subscribed to.

For MQTT topics, consider the following examples:

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

In the first example, the characters '+' and '#' are treated as a wildcards and are therefore not valid in a topic string that is to be published to, but is valid in a subscription.

In the second example, the character '+' is not the only character in a topic level. The character '#' is not the last character in the topic string. Therefore the topic string cannot be published or subscribed to.