Hierarchical Topics

Many publish/subscribe message systems support a tree-organized topic arrangement, many of which predate JMS. For example, suppose the server in question supports topic hierarchies, and it is managing the topic "Games" and the subtopics "Cricket" and "FootBall". In this case, the characteristics of the server's publish/subscribe model and/or configuration parameters determine whether a subscription to "Games" would also constitute a subscription to all subtopics of "Games", so that a message published to "Cricket" and a message published to "FootBall" would be distributed to subscribers of "Games".

Although the JMS specification does not require support for topic hierarchies, they can be a powerful tool, and WSO2 Message Broker supports them. Following is an example configuration demonstrating hierarchical topics.

Note that subtopics can also have sub-topics repeating recursively.

When subscribing to a topic, you configure how to handle hierarchical topics with the Subscription Mode setting:

Topic Only - subscribes you to the topic but not its sub-topics. For example, if you subscribe to the "Cricket" topic using this option, you will get messages specifically published to "Cricket" only. You will not get messages published to "Sri Lanka" or "India" topics or the "Games" topic.
```
String topicName_parent = "Games";
String topicName_child = "Games.Cricket";
 
Topic childTtopic = (Topic) ctx.lookup(topicName_child);
TopicSubscriber topicSubscriber = topicSession.createSubscriber(childTtopic);
```

Immediate Children - subscribes you to the first level of sub-topics but not to the topic itself. For example, if you subscribe to the "Games" topic using this option, you will get messages published to "FootBall" or "Cricket" but not messages published to "Games", "Sri Lanka", or "India".
```
String topicName_parent = "Games";
String topicName_child = "Games.*";
Topic childTtopic = (Topic) ctx.lookup(topicName_child);
TopicSubscriber topicSubscriber = topicSession.createSubscriber(childTtopic);
```

Topic and Children - subscribes you to the topic and all its children. For example, if you subscribe to the "Cricket" topic using this option, you will get messages published to "Cricket", "Sri Lanka", and "India".
```
String topicName_parent = "Games";
String topicName_child = "Games.Cricket.#";
Topic childTtopic = (Topic) ctx.lookup(topicName_child);
TopicSubscriber topicSubscriber = topicSession.createSubscriber(childTtopic);
```
The Immediate Children and Topic and Children options ensure that a user is automatically subscribed to immediate or all child topics of the parent topic, even if a given child topic restricts subscribe permission to the user's role.

For a sample of using hierarchical topics, see Hierarchical Topics Subscriptions Sample.