Developers need to organize their data based on its content. JMS accomplishes this by funneling messages to various destinations. These destinations can not have any logical correlation with each other.

FioranoMQ provides a way of correlating various destinations. FioranoMQ destinations can have a parent-child relationship. A topic can be created within a topic. This results in a hierarchical tree, where each leaf represents a unique topic.

This section covers the following topics:

Need For Hierarchical Name-Spaces

Topicname spacesoffer the ability to organize various destinations in a hierarchical manner. An enterprise can choose to define various levels of hierarchy, depending on the organization of the data that needs to flow on these destinations. Hierarchical topics are easier for solution architects to visualize and design. Given there is a well-defined relationship within such hierarchies, it results in efficient handling of destinations by the provider as well. Even when a topic hierarchy is flat (linear), it is, typically, built from one or more root topics. This entails adding other topics in levels of parent-child relationships to create a hierarchical naming structure.

---

 

Name Space Notation

Hierarchical name-spaces of FioranoMQ use the same notation as qualified packages and classes. Various levels in the hierarchy are distinguished by period-delimited strings. For example, a topic name fiorano.sales.fmq results in the following hierarchy:

The hierarchy gets automatically defined at the time of creating the topic. The process of creating a topic is successful only when the parent topic exists. This ensures that nodes are added to the hierarchy tree in an orderly manner. FioranoMQ allows the hierarchy to have unlimited number of levels and unlimited number of nodes on a particular level.

---

Creating Hierarchical Topics

Hierarchical topics can be created like any other topic. A topic at a particular level can be created only if its parent exists in the hierarchy. The first node of a hierarchical topic is called the root node of the hierarchy. Some important features with respect to hierarchical topic names are noted below:

 Case Insensitive

Topic names are not case sensitive in FioranoMQ. "ACCOUNTS" and "Accounts" are considered the same topic.

 Spaces in Names

Topic names can include a 'space' as a character. For example, "company.fiorano.comment.FioranoMQ is fast" is a valid topic name. Topic names are trimmed before creation. As such, even though spaces are allowed in topic-names, topics that differ only in the number of spaces they incorporate shall be considered to be duplicates. It is therefore recommended that spaces in topic names be used with appropriate caution.

 Empty String

No level in the topic hierarchy can include an empty string. A topic name cannot have two simultaneous dots. For example, "company.GE..dept" is an invalid topic name.

 Unlimited Length of Topic Names

Topic names can be arbitrary in length. A node in the topic hierarchy can have any number of characters.

 Unlimited Depth of Topic Hierarchy

FioranoMQ supports an unlimited depth in the hierarchy tree of a topic. An unlimited number of nodes within a topic can be created.

 Wild Card Support

Wildcard characters such as an asterisk * or # cannot be used in topic names for creating hierarchical topics.

---

 

Dynamic Creation of Topics in Hierarchy

If a topic matching certain topics in a hierarchy is created on a running server instance and its name matches any subscription expression, then this topic becomes the member of the hierarchy.
Example: Subscription expression: ABC.*

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

A subscriber looks up topics with expression ABC.* and it receives messages from all matched topics. If at runtime a new topic named ABC.3 is created, thenABC.3 becomes a part of the hierarchy. Published messages on ABC.3 are received by the Subscriber created on ABC.*.

 

---

 

Looking up Hierarchical Topics

Client applications can lookup a topic in the FioranoMQ Server using either JNDI APIs or a bound object of type FioranoInitialContext. 
Criteria for looking up hierarchical topics are:

The topic being looked up contains a wild-card character, either * or #, along with any number of delimiters (.). The lookup call succeeds only if the root topic is created by the administrator earlier. If the topic being looked up contains a * or #, the call is successful only when there is at least one topic in the server whose name matches the named looked up.

Example: If the user tries to lookup "primarytopic.a.*" or "primarytopic.a.#", then the lookup is successful only if "primarytopic.a" exists on the server.

---

 

Publishing on Node(s) in Topic Hierarchy

A Publisher can publish only on fully specified topic names. Publishing on a topic that contains an asterisk * or a pound character # throws an exception.

---

 

Subscribing to Node(s) in Topic Hierarchy

Subscriptions are created as defined by JMS using TopicSessions. The normal createSubscriber APIs, provided by JMS, can be used to create subscriptions on hierarchical topics.

A subscriber can subscribe to multiple topics using a wild-card character. Subscribing to a topic containing a valid wild-card character effectively creates subscribers on all the topics in the hierarchy that match that expression.

Template Characters Used in Subscription

Wild-card characters are special characters used in the creation of topic hierarchies. In the topics hierarchy, these characters are referred to as Template Characters. The period (.) delimiter is used together with the asterisk * and the pound # template characters to fulfill subscriptions. Using these characters avoids having to subscribe to multiple topics on the server. Client applications can use template characters when subscribing to a set of topics or while binding a set of topics. 

There are two FioranoMQ template characters used in subscription-creation; the asterisk * and the pound #:

• Asterisk *: FioranoMQ uses two types of conventions for this template character An asterisk * must be the last template character in subscription expression. Subscriptions are made for the root node and all matching subordinate nodes in the hierarchy.

For Example: If the expression for subscription is ABC.*, then ABC and all its subordinate topics will be matched.

An asterisk * is the intermediate character within a subscription expression. Where a root topic is not selected an * is taken as "one or more occurrence of a character ". Example: If the topic for subscription is ABC.*.1 then ABC will not be selected but all topics that match this pattern will be selected and used to subscription. Example: ABC.1.1, ABC.1.1.1, and ABC.2.1.

• Pound (#): The pound (#) selects all topics one level down the hierarchy. If the (#) character is present in the pattern, then all the topics one level down the hierarchy are used for subscription. Example: If the subscription topic name is ABC.# then all the topics a level below ABC will be matched. Example: ABC.1, ABC.2 will match ABC.#, but ABC.1.1 and ABC.1.2 do not match the pattern and will not be used.
• Template characters exist to allow a set of managed topics to exist in a message server. This, in turn, allows the subscriber to choose broad subscription parameters that include preferred topics and avoid irrelevant topics.

The constraints in using template characters are

• At the node level, a template character precludes using other template characters. Example: Qualifying the selection against the pattern A.B*.1 is not allowed where as A.B.*.1 is allowed. In the patterns used, each character must be separated with a delimiter (.).
• Template characters used as replacement are not allowed. 
• Other than the wild-card characters *, #, (.), no other wild-card character is used for subscription to multiple topics.

 

Conventions used in Hierarchical topics

Only two template characters are used in Fiorano hierarchical topics. These characters are the pound # and the asterisk * with a delimiter (.). 

Using the asterisk * character

Subscription Expression ABC.*

Convention used: If * is the last character in a subscription expression with no other template character used, then the root topic and all other topics (where * is replaced with one or more occurrences of any character) will be selected for subscription on Hierarchical topics. 

Example:
If the following Topics exist on the MQ Server: ABC, ABC.1, ABC.2, ABC.1.1, and ABC.1.2

And the expression used for subscription is: 
ABC.*

Then the matched topics are: 
ABC, ABC.1, ABC.2, ABC.1.1, ABC.1.2

Subscription topic name format: 
ABC.*.1

Convention used: If * is the intermediate character in a subscription expression then all other topics (where * is replaced with one or more occurrences of any character in name) will be selected for that subscription. The root topic is not included in such a selection. 

Example: 
The Topics existing in MQ Server are: 
ABC, ABC.1, ABC.2, ABC.1.1, and ABC.1.1.1

And the expression used for subscription is: 
ABC.*.1

Then the Matched topics are: 
ABC.1.1, ABC.1.1.1

Using the pound # character 

Subscription topic name format: 
ABC. #

Convention used: If (#) is the only wild-character present in the expression then all topics (where (#) is replaced with only one occurrence of any character in name) would be used for subscription.

Example
If the Topics existing on the MQ Server are: 
ABC, ABC.1, ABC.2, ABC.1.1, ABC.1.1.1

And the expression used for subscription is: 
ABC. #

Then the Matched topics are: 
ABC.1, ABC.2 

If the Subscription topic name is ABC#.1, 

Then the Matched topics are:
ABC.1.1, ABC.2.1, ABC.3.1

Using a combination of template characters: Both template characters can be used in a subscription expression, as explained below.

Subscription topic name format: 
ABC.*.#

Convention used: The above topic name is invalid. The pound (#) character after the asterisk * character has no function in an expression. 

Subscription topic name format: 
ABC.#.*

Convention used: In this expression all the topics (where (#) is replaced with one occurrence of a character and * is replaced with one or more occurrence of a character) will be used for subscription.

Example: 
If the Topics existing on the MQ Server are: 
ABC, ABC.1, ABC.1.1, ABC.2, ABC.2.1

And the subscription expression is: 
ABC.#.*, 

Then the Matched topics are: 
ABC.1.1, ABC.2.1

---

 

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 Studio. If this value is set to true, then deletion of a topic/subtopic deletes all the children of this topic/subtopic. If it is set to false, an exception is thrown indicating that the user first needs to delete the children of the topic\subtopic before deleting the topic itself. By default, this variable is set to false.

---

 

Publish_Subscribe Across Servers

FioranoMQ supports hierarchical topics across servers. Hierarchical topics across servers can be used in exactly the same way as they are used on a single server.

---

 

Security Considerations on Hierarchical Topics

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

---

 

Limitations

Topic names cannot contain a wild-card character in topic creation. For subscription expression on the template characters (* or # with any number of delimiters (.)) can be used. Usage of any other template character throws an exception in 'lookup'. 

Deletion of a hierarchical topic that has active publishers/subscribers is disallowed. Care needs to be taken not to delete the hierarchical topics when any topic in the hierarchy contains active publishers or subscribers. 

A publisher cannot publish on multiple hierarchical topics concurrently. 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 that 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 the ACL of a 'child' in the hierarchy is changed by the administrator mid-way through receiving messages, the subscriber remains unaffected by this change. However, creating new subscribers with subscription expressions will get affected by this change.

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