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:
- When
*
appears by itself at a level within a subscription topic (as in,animals/*/cats
, oranimals/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. - 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. - The
*
may be used at multiple levels within a subscription topic, with or without topic prefixes. - Use of
*
in an arbitrary location within a level, and not covered by the previous rules, supports general sub-string matching.
Example: animals/domestic/*
matches the topics animals/domestic/cats
and animals/domestic/dogs
, but it doesn't match the topic animals/domestic/dogs/beagles
.
Example: animals/red*/wild
matches both the topics animals/red/wild
and animals/reddish/wild
.
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
.
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:
- 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. - 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. - The
>
and*
characters may be used together within a subscription topic.
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
.
Example: animals>
and animals/domestic>
are literal subscriptions and don't match animals/domestic/dogs/beagles
.
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.
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/domestic/cats/persian/grey
|
animals/domestic/dog*
|
animals/domestic/dog
|
animals/domestic/dog/beagle
|
animals/domestic/>
|
animals/domestic/cats
|
animals
|
animals/*/cats/>
|
animals/domestic/cats/tabby/grey
|
animals/domestic/dogs/beagles
|
my/test/*
|
my/test/topic
|
My/Test/Topic
|