A topic is a character string that describes the data that is published in a publish and subscribe system.
Topics are created in the broker when a client sends a request to subscribe to or publish a message to a given topic. For example, when a client subscribes to a topic, that topic is registered within the broker simply because a client is subscribed to it and will thus receive any future matching publications. It is not necessary for a client to create topics as a specific step independent of a subscription request.
Topics are key to the successful delivery of messages in a publish and subscribe system. Rather than specifying destination addresses for each message, a publisher assigns a topic to the message. The message broker then matches the topic against a list of clients (subscribers) who have subscribed to that topic, and delivers the message to each of those clients where a successful match is made.
Note that a publisher can control which subscribers can receive a publication by choosing carefully the topic that is specified in the message.
Only single byte (non-extended) characters are supported. However, there are three characters that have special meanings. These characters ("/", "#", and "+") are described in Special topic characters .
What is a topic tree
Although you can use any name for a topic, it is best to choose a name that fits into a hierarchical tree structure. Thoughtfully designing topic names and topic trees facilitates these tasks:
- Subscribing to multiple topics
- Reacting automatically to messages about a specific topic, for example, by sending an alert to a manager’s pager
Although you can construct a topic namespace as a flat, linear structure, it is better to build a topic tree as a hierarchical structure with one or more root topics. The following figure shows an example of a topic tree with one root topic:
Figure 1. Hierarchical topic tree
Each character string in the figure represents a node in the topic tree. A complete topic name is created by concatenating the character strings from multiple levels of the tree. Use a forward slash (/) to separate each part of a hierarchical name. For example, these are the topics from the tree shown in Figure 1:
When you design a topic tree, remember that the broker cannot interpret or derive meaning from the topic name. The broker uses the topic name to identify which messages to send (those that match the subscription).
Special topic characters
A topic string can only include single byte (non-extended) characters, but three specific characters have special meanings. These characters ("/", '#", and "+") allow solution designers flexibility in controlling message flow by choosing carefully the topics that are specified for each message.
The topic level separator ("/") introduces hierarchical structure into the overall topic namespace, while the multi-level wildcard and single-level wildcard can be used for subscriptions. Note, however, that the wildcards cannot be used within a topic by the publisher of a message.
Topic level separator
The forward slash ("/") is used to separate each level within a topic tree and provide a hierarchical structure to the topic space. The use of the topic level separator is significant when the two wildcard characters are encountered in topics specified by subscribers. Multi-level wildcard
The number sign ("#") is a wildcard character that matches any number of levels within a topic. For example, a subscription to finance/stock/ibm/#
receives messages published to all of these topics:
The multi-level wildcard can represent zero or more levels. Therefore, finance/#
matches the singular finance
, where #
represents zero levels, as well as all topics further down the hierarchy. The topic level separator is meaningless in this context, because there are no levels to separate.
The multi-level wildcard can be specified only on its own or immediately following the topic level separator character. Therefore, #
are both valid, but finance#
is not valid. The multi-level wildcard must also be the last character used within the topic tree. For example, finance/#
is valid but finance/#/closingprice
is not valid.
The plus sign ("+") is a wildcard character that matches a single topic level. For example, finance/stock/+ matches finance/stock/ibm and finance/stock/xyz, but not finance/stock/ibm/closingprice. Also, because the single-level wildcard matches only a single level, finance/+ does not match finance.
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 follow the topic level separator, except when it is specified on its own. Therefore, + and finance/+ are both valid, but finance+ is not valid. The single-level wildcard may be used anywhere within the topic tree. For example, finance/+ and finance/+/ibm are both valid. It cannot be used as part of a name. As a result, finance/stock/ibm/+price is not valid.
Topic semantics and usage
When you build an application, the design of the topic tree should take into account the following principles of topic name syntax and semantics:
- A topic must be at least one character long.
- Topic names are case sensitive. For example, ACCOUNTS and Accounts are two different topics.
- Topic names can include the space character. For example, Accounts payable is a valid topic.
- A leading "/" creates a distinct topic. For example, /finance is different from finance. /finance matches both "+/+" and "/+", but not “+”.
- Do not include the null character (Unicode \\x0000) in any topic.
- Only single-byte (non-extended) characters are supported in topic names.
The following principles apply to the construction and content of a topic tree:
- The length is limited to 64 KB but within that there are no limits to the number of levels in a topic tree.
- There can be any number of root nodes; that is, there can be any number of topic trees.
Parent topic: Publish and subscribe messaging: XPD622