Prerequisites

In FioranoMQ Hierarchical Topics support, the user can create a subtopic in a hierarchy on a server that is running. For dynamic topic creation support, Events should be turned when the server is running.

Events to be turned on for dynamic topic creation support

If a topic is created on a running server instance and its name matches any subscription expressions (if they exist) then this topic becomes a member of the maintained hierarchy for subscription on Hierarchical topics.

Example

• Subscription expression: ABC.*

• Topics existing on the system: ABC, ABC.1, ABC.2, ABC.1.1

A subscriber looks up a topic with the expression ABC.* and receives messages from matching topics. At runtime a new topic named 'ABC.3' (which does not exist in the created hierarchy) is created. This new topic becomes part of the hierarchy and published messages on ABC.3 are also received by the Subscriber created on ABC.*.

Creating a Hierarchical Topic

Admin API

The User can create Hierarchical Topics with the help of AdminAPIs. The code snippet below demonstrates the process of the creation of topics in Hierarchical namespaces.

To create a Topic, it is necessary that the parent to the topic exists:

eStudio

The User can create Hierarchical Topics with admin eStudio. To create hierarchical topics with eStudio, follow the steps below:

1. Launch Fiorano eStudio and connect eStudio to the FioranoMQ Server.
2. To create a topic, navigate to the Topics sub-node under the Destinations node of the tree
3. Right-click the Topics node and select Add Topic

The below window gets displayed.

4. Enter the Destination parameter and other relevant parameters necessary for the creation of the topic. In this example, the Topic name is ABC.1

 

 

5. In the same manner, the user can create the topics hierarchy

After a hierarchy is created, all the topics are displayed in the Topic List.

Deleting a Hierarchical Topic

Deletion of a topic/subtopic from the hierarchical namespace depends on the value of the parameter AllowDeletionOfSubTopics, which can be configured through Fiorano eStudio. If this value is set to 'true', then deletion of a topic/subtopic deletes all the children of this topic/subtopic. However, if it is set to 'False', the following exception is raised, indicating that the user needs to first delete the children of the topic/subtopic before deleting the topic itself.

By default, this variable is set to 'False'. Follow the steps given below to delete a hierarchical topic\subtopic.

1. Start Fiorano eeStudio/eStudio and login to FMQ-JMX
2. Select the Topic config from JMX Connection > Fiorano > mq > PubSub > Topic > $(TopicName) > config
3. Enable the value of the parameter named AllowDeletionOfSubtopics (GeneralPropeties) by setting it up to 'True' from the drop-down list.

Setting up Security on a HT

FioranoMQ supports ACL settings for Hierarchical topics. An ACL can be set for any topic, irrespective of the level at which the topic exists. These ACLs are checked at the time of creating a publisher as well as at the time of creating a subscriber. While creating a subscriber on multiple topics (a topic that involves a template character in its name), the ACLs of all subtopics are also checked. In addition, the subscriber is modified so that it does not receive messages from subtopics that have a negative permission set for that particular User.

Looking Up a HT

A client application can look up a topic in the FioranoMQ Server using either JNDI APIs or a bound object of type FioranoInitialContext. Criteria for looking up Hierarchical topics are given below:

Wild Characters * or #

The topic being looked up contains a wildcard character '*' or '#' with any number of delimiters. A delimiter (.) can not be the last character of a topic name that is looked up.

The look up call succeeds only if the root topic has been created by the administrator at an earlier stage. If the topic being looked up contains a '' or '#' then this call is successful only when there is at least one topic existing in the server whose name matches the criterion.

Example: If the user tries to look up "primarytopic.a." or "primarytopic.a.#" then the lookup call is successful only if "primarytopic.a" exists.

HT Limitations

Topic names cannot contain a wildcard character. For subscription expressions, no other template character ('*' 'or' # with any number of dots ".") is used. Usage of any other template character throws an exception in the look up call. All attempts to delete hierarchical topics are successful whether or not the topic has active publishers/subscribers present. It is, therefore, important to be careful so as not to delete hierarchical topics while they contain any active publishers or active subscribers.

A publisher cannot publish on multiple topics. A publisher has to specify the complete name of the hierarchical topic on which it wants to publish data. Creation of a publisher on a topic, which contains an asterisk '', throws an exception. Similarly, an exception is thrown if a publisher tries to publish on a topic which contains an asterisk ''. If a subscriber subscribes on hierarchical topics with a subscription expression and, while receiving messages, the administrator changes the ACL of one of the children of the hierarchy, then the subscriber will not be affected by this change. However, all new subscribers with a subscription expression will be affected.

There is a performance degradation associated with hierarchical topics. Users are, therefore, advised not to use hierarchical topics for applications where performance is a major requirement.

1. A Hierarchical Topic is not supported by the following flags:
   • UseOptimizedTCPReceive = true
   • This implies that the Hierarchical Topic is not supported by the 7.2 runtime Layer.
2. Un-subscription for Hierarchical topics does not work. The User has to unsubscribe the subscribers created on behalf of hierarchical support manually, through eStudio