Solace Message Format (SMF) is the Solace Messaging Platform’s underlying messaging protocol.
Topics consist of NULL-terminated UTF-8 strings composed of one or more levels, in the format of “a/b/c”. The “/” character is used as a separator between “levels” (also called elements) of the string. A maximum of 128 topic levels are supported.
The maximum length of the string, excluding the NULL terminator, is 250 bytes.
Characters in topic strings are case-sensitive. Therefore, for example, a topic subscription of “animals/domestic/cats” is not equal to “Animals/Domestic/Cats”.
All UTF-8 characters are supported. However, the following characters have special meaning:
- “/” is a level separator for both publish and subscribe topics.
- <NULL> is an invalid character within a string for both publish and subscribe topics.
- “*” is a single-level wildcard for subscribe topics only. For publish topics, “*” is treated as a literal character.
- “>” is a multi-level wildcard when used at the last level of a topic subscription. “>” can only be used as a wildcard for subscribe topics only—for publish topics, “>” is treated as a literal character.
To allow compatibility with MQTT topics, which permit empty topic levels (for example, “/a/b”, “a//b”, or “a/b/”), Solace routers Version 7.1.1 or greater also allow empty topic levels in SMF topics. However, there are some limitations to using empty topic levels with SMF topics:
- Client applications using Solace messaging APIs can publish to topics with empty levels, but they cannot use topic subscriptions with empty levels.
- ACL profiles do not allow SMF publishing or subscribing topic exceptions that have empty topic levels.
When the “*” and “>” characters are used in topic subscriptions, they function as wildcards, which affect the topic matches that may occur.
Note: The “*” and “>” characters do not have any special meaning when they are used in topics that messages are published to. They are treated as literal characters—not as wildcards—and will not affect topic matches.
The use of the “*” and “>” wildcard characters in topic subscriptions may affect the topic matches in the following ways:
- The “*” character, when it appears by itself at a level within a subscription topic (for example, “animals/*/cats”, or “animals/domestic/*”), indicates a wildcard match at that level. A “*” wildcard at the end of the subscription topic only performs a wildcard match at that level. For example, “animals/domestic/*” matches the topics “animals/domestic/cats” and “animals/domestic/dogs”, but it does not match the topic “animals/domestic/dogs/beagles”.
- The “*” wildcard character is allowed in conjunction with topic prefixes at a level within a subscription. For example, “animals/red*/wild”. In this case, the “*” wildcard provides a “0 or more” match—the topics “animals/red/wild” and “animals/reddish/wild” are both matches.
Further, use of the “*” wildcard character within a level supports prefix matching, but not general sub-string matching. For example, while “animals/*/brown” and “animals/domestic/white*” are allowed, but “animals/*bro” and “animals/br*wn” are invalid as wildcard subscriptions and the subscription topic is not permitted.
- The “*” wildcard may be used at multiple levels within a subscription topic, with or without topic prefixes. For example, “animals/*/cats/*” is valid and matches the topics “animals/domestic/cats/persian” and “animals/wild/cats/leopard”, but does not match the topic “animals/domestic/cats/persian/grey”, nor does it match the topic “animals/domestic/dogs/beagles”.
- The “>” character, when it appears by itself at the last level of a subscription topic (for example, “animals/domestic/>”), provides a “one or more” wildcard match for any topics with an identical prefix to the subscription. For example, “animals/domestic/>” does not 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”.
- A “>” character 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. For example, “animals>” and “animals/domestic>” are literal subscriptions and do not match "animals/domestic/dogs/beagles".
- The “>” and “*” characters may be used together within a subscription topic. For example, “animals/*/cats/>” matches the topics “animals/domestic/cats/persian”, “animals/wild/cats/leopard”, and “animals/domestic/cats/persian/grey”, but it does not match the topic “animals/domestic/dogs/beagles”.
There are some restrictions on wildcard behavior:
- A Solace router 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 are not included in topic subscriptions for which they were not 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:|