Topic-based wildcard scheme

Topic-based wildcards allow subscribers to subscribe to more than one topic at a time.

Topic-based wildcards are a powerful feature of the topic system in IBM MQ publish/subscribe. 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.

The topic-based wildcard scheme allows you to select publications grouped by topic level. We can choose, for each level in the topic hierarchy, whether the string in the subscription for that topic level must exactly match the string in the publication or not. For example, the subscription IBM/+/Results selects all the topics, 
IBM/Software/Results
IBM/Services/Results
IBM/Hardware/Results
There are two types of wildcard.

    Multilevel wildcard

    • The multilevel wildcard is used in subscriptions. When used in a publication it is treated as a literal.
    • 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 'USA/Alaska/#', you receive messages on topics 'USA/Alaska' and 'USA/Alaska/Juneau'.
    • The multilevel wildcard 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 wildcard is only effective when specified on its own or next to the topic level separator character. Therefore, '#' and 'USA/#' are valid topics where the '#' character is treated as a wildcard. However, although 'USA#' 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.

    Single level wildcard

    • The single wildcard is used in subscriptions. When used in a publication it is treated as a literal.
    • The single-level wildcard character '+' matches one, and only one, topic level. For example, 'USA/+' matches 'USA/Alabama', but not 'USA/Alabama/Auburn'. Because the single-level wildcard matches only a single level, 'USA/+' does not match 'USA'.
    • The single-level wildcard can be used at any level in the topic tree, and in conjunction with the multilevel wildcard. The single-level wildcard 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 wildcard. However, although 'USA+' 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.

The syntax for the topic-based wildcard scheme has no escape characters. Whether '#' and '+' are treated as wildcards or not depends on their context. See When topic-based wildcards are not wild for more information. Note: The beginning and end of a topic string is treated in a special way. Using '$' to denote the end of the string, then '$#/...' is a multilevel wildcard, and '$/#/..'. is an empty node at the root, followed by a multilevel wildcard.


Topic-based wildcard string

1Left delimiterBodyRight delimiterOnly delimitersBody Topic level name Body delimiter Topic level nameAny Unicode character except / 2Only delimiters3#+4/5#+#+Notes:

  • 1 A null or zero length topic string is invalid
  • 2 You are advised not to use any of *, ?, % in level name strings for compatibility between char based and topic-based wildcard schemes.
  • 3 These cases are equivalent to the left delimiter pattern.
  • 4 / with no wildcards matches a single empty topic.
  • 5 These cases are equivalent to the right delimiter pattern.
  • 6 Match every topic.
  • 7 Match every topic where there is only one level.

Left delimiter /1#/2+/3 Body delimiter/4#//#/2+//+/3Right delimiter /5/#2/+3 Notes:

  • 1 The topic string starts with an empty topic
  • 2 Matches zero or more levels. Multiple multi-level match strings have the same effect as one multi-level match string.
  • 3 Matches exactly one level.
  • 4 // is an empty topic - a topic object with no topic string.
  • 5 The topic string ends with an empty topic


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.

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


Examples

IBM/+/Results
#/Results
IBM/Software/Results
Parent topic: Wildcard schemes