Topics

This section discusses the Topic Names, and the structure of Topic Name Spaces (or Information Spaces). Although the Topic Name Space is defined at the application level, it is useful to have an understanding of the notions of hierarchy and wildcards. The syntax described is that supported by a specific broker product: the IBM MQ Series Integrator Version 2.

Topic syntax

The topic of a message can contain any of the characters found in the Unicode character set. For example, "SOFTWARE" , "ICE CREAM" and "The Top 50 Cities" are all valid topics. However, special meaning is applied to three characters: the slash (/), the hash (#) and the plus (+). Each of these is explained in the following subsections.

The Slash ('/')

The slash character should be used by applications to denote partitions within a topic name. These partitions are interpreted as levels in a tree. For example, "employee/hire/development" is a topic name with three levels. The use of the slash is important in the presence of wildcards (the + and # symbols discussed below). It is also used more generally to define a hierarchy in the topic namespace.

The Hash (or "pound" in America) ('#')

The hash is one of the wildcard characters. The hash wildcard can match any number of partitions. It may only be used at either the beginning or the end of a topic. For example, one could subscribe to "employee/#" and receive messages with subjects "employee/hire" and "employee/hire/development" . Since the semantics of the # wildcard are that it can match zero or more partitions, "employee/#" can also match just "employee" . Note that, in this case, the # represents zero levels. Therefore, the slash, which is a partition separator, is meaningless since there is no partition to separate. Hence, messages with the Topic Name "employee" will be delivered to subscribers of "employee/#" . Because of how this wildcard works, we call the # wildcard the multi-level wildcard . Typically, the multi-level wildcard is used to match sub-tree of unknown depths.

The Plus ('+')

The plus is the second of the two wildcard characters. It is called the single-level wildcard since, unlike the # which will match any number of partitions, it will only match a single partition. For example, "employee/+" will match "employee/hire" but will not match "employee/hire/development". Note that the plus must match exactly one level, therefore, "employee/+" does not match "employee". This wildcard character should never be adjacent to a non-slash character. For example "employee+" , "emp+ee" , "employee/+ire/sales" are not valid topics. More formally, the plus wildcard matches one or more non-slash characters.

Topic semantics and usage

When building an application, the topic tree design plays a crucial role in the application's communication possibilities. This design should account for
the following principles of topic name syntax and semantics:

Topic names are case sensitive. For example, "ACCOUNTS" and "Accounts" are recognised as two different topic names.
Topic names can include the space character. One example might be "accounts payable". Spaces are treated just like any other character in the topic name.
Though not recommended, a topic level may be the empty string. For example, "a//c" is a three level topic name whose middle level is empty.
For portability reasons, it is recommended that topic names do not include the null character (Unicode \x0000).

The following conditions apply to the construction and content of a topic tree:

There is no effective limit to length of the overall Topic Name string. See the Remaining Length field in the Fixed Header section for more information.
There is no limit to the height or the levels of depth (number of slash-separated strings) in a topic tree.
There is no limit to the length of any particular level name in the tree.
There may be any number of "root" nodes (that is, any number of topic trees).
The IBM MQSeries Integrator Version 2 product reserves the topic trees rooted at "$SYS" and "$ISYS" .

Using wildcards with topics

Clearly, topic names without wildcards are straightforward to use. In this section, we discuss and show examples of using wildcards with topics. It is important to note that wildcards can exist at any level in the topic name string (subject to the restrictions given above). However, it is recommended that wildcards only be used at the end of a topic name. Topic name pattern matching in the broker is likely to be optimised for topics obeying this recommendation.

What this means is that a well-designed application will structure its topics into subject trees. This will allow applications to subscribe to sub-trees by placing the multi-level wildcard as the last level. What does it mean when the multi-level wildcard appears, for example, in the beginning of a topic name? For example, suppose we have the topic "#/employee". Then, topics such as "hire/employee" and "development/hire/employee" will match. If the topic were "outdoor/scuba/#", then matching topics would be those that were under the "scuba" sub-tree of the "outdoor" tree. For example, "outdoor/scuba/ocean" and "outdoor/scuba/ocean/pacific" both match. So does "outdoor/scuba" because the # represents zero or more partitions and, in this case, there is no partition. Note that the special case of the "#" topic will match all topic names. However, the single "+" topic will only match topics that do not contain a non-escaped slash (i.e., single-level names). Another example is "a/+/#" which will match all names with at least two levels whose first level is 'a'.

Client applications can only use wildcards when subscribing to a set of topics. Messages must be published on fully specified topic names.

The use of multiple wildcards is also valid. A topic expression can include several plus signs and hashes as long as the use conforms to the guidelines stated above. Examples of valid topics include using plus signs to specify a number of levels after a certain node such as "employee/+/+" , rather than using the "#" which would match zero or more levels.

Discussion

ASC on Topic Names: The processing of the special characters, '/', '#' and '+', is compatible with the IBM MQ Series Integator Version 2 message broker. This section is taken from Chapter 4.6 of Peter Lambros' Functional Specification for MQ Series Integator Version 2.

BACK to index

Last Modified: 28-Jun-99