Topic filters for MQTT global-shared subscriptions

You can configure global-shared durable and global-shared non-durable topic subscriptions to be shared by Eclipse Amlen MQTT client applications. You must configure a subscription policy and a corresponding topic policy if your MQTT applications are to use global-shared durable subscriptions. You must ensure that the Subscription and Topic parameters are correctly configured.

When you create a subscription policy, you authorize clients to use the global-shared durable subscription, but not the associated topic. Therefore, you must create a separate topic policy to authorize clients to use the associated topic.

The MQTT SUBSCRIBE request

The SUBSCRIBE request in MQTT specifies one of the following strings:

$SharedSubscription/subName/topicFilter

$share/subName/topicFilter

where:

$SharedSubscription: Indicates that the target of the SUBSCRIBE request is a global-shared subscription.; Clients that connect with the clean session flag set to false in MQTTv3, or with the clean session flag set to true , cannot share a subscription. Trying to share a subscription results in the creation of two subscriptions with the same subName.

$share: Indicates that the target of the SUBSCRIBE request is a global-shared subscription.; All MQTT clients that use $share to subscribe can connect to the same shared subscription.

subName: Is the name of the global-shared subscription.; This value must not include any forward slashes ( / ).

topicFilter: Is a standard MQTT topic filter for any type of topic subscription. It can contain a single topic name, or it can contain a topic filter that includes wildcards.

Setting the Subscription and Topic parameter in the susbcription policy and topic policy

If you are using an MQTT global-shared durable subscriptions, you must configure a subscription policy and a corresponding topic policy. In the subscription policy, the value of the Subscription parameter must be the same as the SubName element in the MQTT SUBSCRIBE request. This value must not contain any forward slashes ( / ). In the topic policy, the value of the Topic parameter must be the same as the topicFilter element in the MQTT SUBSCRIBE request. To make the subscription durable, set cleanSession=0.

If you are using an MQTT global-shared non-durable subscription, you need only configure a topic policy. The value of the Topic parameter in the topic policy must grant access to the topicFilter on the MQTT SUBSCRIBE request.

For more information about configuring messaging policies, see Configuring message hubs.

Examples

For example, an MQTT client specifies the following Eclipse Amlen topic filter for a global-shared subscription (in this case, a global-shared durable subscription):
```
$SharedSubscription/ProGolfSub//Golf/Professional
```
The subscription policy must specify the following value for the Subscription parameter:
```
ProGolfSub
```
Then the topic policy must specify the following value for the Topic parameter:
```
/Golf/Professional
```
However, if an MQTT client specifies the following topic string:
```
$SharedSubscription/ProBaseballSub/Baseball/Professional
```
The subscription policy must specify the following value for the Subscription parameter:
```
Subscription=ProBaseballSub
```
Then the topic messaging policy must specify the following value for the Topic parameter:
```
Topic=Baseball/Professional
```
For a global-shared non-durable subscription, your topic string must look like the following example:
```
$SharedSubscription/SubName/topicFilter
```
- The $SharedSubscription/ segment must be present.
- The SubName must be the name of the subscription.
- The topicFilter must match the topic on the topic policy. The topicFilter must include a leading forward slash ( / ) if the topic has one.
For example, an MQTT client specifies the following topic string:
```
$SharedSubscription/ProHockeySub//Hockey/Professional
```
Then the topic policy must specify the following value for the Topic parameter:
```
/Hockey/Professional
```
A subscription policy is not necessary.
All subscribers to the global-shared non-durable subscription must use the same subscription name.