Wildcard Characters in 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. However, to avoid confusion, SAP does not recommend using * and > as literal characters in published topics.

Using the * Wildcard

The * wildcard functions in the following ways:

  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 performs a wildcard match only at that level.

    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.

    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.

    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.

    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.

Using the > Wildcard

The > wildcard functions in the following ways:

  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.

    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 other than by itself at the last level of a subscription topic in the string is treated as the > character rather than a wildcard.

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

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

    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

Wildcards have the following restrictions:

  • Event brokers automatically create topic subscriptions 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 ensures that system and event log messages beginning with a $ character aren't included in topic subscriptions for which they weren't intended.

Wildcard Examples

The following table provides 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/*/cats/* animals/domestic/cats/persian
animals/domestic/dog* animals/domestic/dog
animals/domestic/> animals/domestic/cats
animals/*/cats/> animals/domestic/cats/tabby/grey
my/test/* my/test/topic My/Test/Topic