Subscribing to 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 topics in the above hierarchy, you have the following options:

Topic Only - Shown below is how the JMS client can subscribe to a specific topic only. For example, if you subscribe to the "Cricket", the client will receive messages that are published to "Cricket" only. The client will not receive messages published to the "Sri Lanka", "India" , "Football" or "Games" topics.
```
String topicName_parent = "Games";
String topicName_child = "Games.Cricket";
 
Topic childTtopic = (Topic) ctx.lookup(topicName_child);
TopicSubscriber topicSubscriber = topicSession.createSubscriber(childTtopic);
```

Immediate Children - Shown below is how the JMS client subscribes to the first level of sub-topics but not to the topic itself. For example, if you subscribe to the "Games" topic, 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 - Shown below is how the JMS client subscribes to the topic and all its sub topics. For example, if you subscribe to the "Cricket" topic using, the client will receive 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 explained above ensure that the client is automatically subscribed to the immediate child topic or all child topics of the parent topic, even if a given child topic restricts subscriber permission to the user's role.

When creating a JMS subscription in tenant mode, the username, topic name and subscription ID should be set in the following manner:

username =username!tenantdomain
Example: username =testuser!test.com;

topicName = tenantdomain/topicName;
Example: topicName = test.com/testTopic;

subscription Id=tenantdomain/subscription id
Example: subscription Id=test.com/K1;

For a sample of using hierarchical topics, see Creating Hierarchical Topic Subscriptions.