Wildcard Characters in SMF Topic Subscriptions

When the * and > characters are used in topic subscriptions, they function as wildcards, which affect the topic matches that may occur.

The * and > characters don't have any special meaning when they are used in published topics. They are treated as literal characters - not as wildcards - and don't affect topic matches.

Use of the * wildcard

Rules governing the use of the * wildcard:

  1. When * appears by itself at a level within a subscription topic (as in, animals/*/cats, or animals/domestic/*) indicates a wildcard match at that level. A * wildcard at the end of a subscription topic only performs a wildcard match at that level.

    2. Example: animals/domestic/* matches the topics animals/domestic/cats and animals/domestic/dogs, but it doesn't match the topic animals/domestic/dogs/beagles.

  2. When * is preceded by a topic prefix at a level within a subscription topic (as in, animals/red*/wild) indicates a "prefix and 0 or more” match at that level.

    3. Example: animals/red*/wild matches both the topics animals/red/wild and animals/reddish/wild.

  3. The * may be used at multiple levels within a subscription topic, with or without topic prefixes.

    4. Example: animals/*/cats/* is valid and matches the topics animals/domestic/cats/persian and animals/wild/cats/leopard, but doesn't match the topic animals/domestic/cats/persian/grey, nor does it match the topic animals/domestic/dogs/beagles.

  4. Use of * in an arbitrary location within a level, and not covered by the previous rules, supports general sub-string matching.

    5. Example: The * in these topics, animals/*/brown and animals/domestic/white*, is interpreted as a wildcard, but in topics like these, animals/*bro and animals/br*wn, the * is interpreted as a literal to be matched.

Use of the > wildcard

Rules governing the use of the > wildcard:

  1. When > appears by itself at the last level of a subscription topic (as in, animals/domestic/>) provides a “one or more” wildcard match for any topics with an identical prefix to the subscription.

    2. Example: animals/domestic/> doesn't match the topic animals/domestic, but it does match the topics animals/domestic/cats, animals/domestic/dogs, animals/domestic/dogs/beagles, and animals/domestic/dogs/beagles/long-eared.

  2. A > that appears anywhere else other than by itself at the last level of a subscription topic in the string is treated as the > character rather than a wildcard.

    3. Example: animals> and animals/domestic> are literal subscriptions and don't match animals/domestic/dogs/beagles.

  3. The > and * characters may be used together within a subscription topic.

    4. Example: animals/*/cats/> matches the topics animals/domestic/cats/persian, animals/wild/cats/leopard, and animals/domestic/cats/persian/grey, but it doesn't match the topic animals/domestic/dogs/beagles.

Wildcard restrictions

There are some restrictions on wildcard behavior:

  • An event broker automatically creates a topic subscription beginning with the prefix #P2P for each client, which enables messages to be sent directly to that client (for example, in request/reply scenarios). Therefore, to ensure that wildcards cannot be used to receive messages that are intended for the inboxes of other clients, the * or > wildcards will never match the string #P2P, regardless of where the wildcard or #P2P string is located within the topic subscription string.
  • Messages published to topics that begin with a $ character will never be matched by standalone wildcards (*/... or >) at the first level of a topic subscription. This is to ensure that system and event log messages beginning with a $ character aren't included in topic subscriptions for which they weren't intended.

Wildcard usage examples

The following table provides some examples of topic subscription matches when using wildcards.

Topic Subject Matches for Subscriptions Using * and > Wildcards
Wildcard Subject Matches Messages With Subjects Like: Does Not Match Messages With Subjects Like:
animals/domestic/* animals/domestic/cats
animals/domestic/dogs 		animals/domestic/dogs/beagles
animals/*/cats/* animals/domestic/cats/persian
animals/wild/cats/leopard 		animals/domestic/cats/persian/grey
animals/domestic/dogs/beagles
animals/domestic/dog* animals/domestic/dog
animals/domestic/doggy 		animals/domestic/dog/beagle
animals/domestic/cat
animals/domestic/> animals/domestic/cats
animals/domestic/dogs/beagles 		animals
animals/domestic
animals/Domestic
animals/*/cats/> animals/domestic/cats/tabby/grey
animals/wild/cats/leopard 		animals/domestic/dogs/beagles
my/test/* my/test/topic My/Test/Topic
my/test