Shared subscriptions

Eclipse Amlen supports JMS version 1.1, MQTT version 3.1.1, and MQTT version 5.0. JMS version 1.1 and MQTT version 3.1.1 are extended to support shared subscriptions. MQTT version 5.0 supports shared subscriptions as part of the design.

Shared subscriptions allow messages to be processed at a faster rate than a single client can accommodate. Messages on a shared subscription are processed even if a client application fails. There are four types of shared subscriptions:
  • Global-shared non-durable subscriptions
  • Global-shared durable subscriptions
  • Private-shared non-durable subscriptions
  • Private-shared durable subscriptions
Note: The order of delivery of messages on shared subscriptions cannot be guaranteed. If you need to preserve message order, either include message order information for use by the client in the content of the message or do not use shared subscriptions.
For more information about the types of subscriptions that are supported in Eclipse Amlen, see Subscribers and Subscriptions.

To enable client applications to receive messages from shared subscriptions, you must ensure that the appropriate messaging policies are configured. All types of shared subscriptions require a topic policy. For information about how to configure topic policies, see Topic policy. To enable client applications to receive messages from a global-shared durable subscription, a subscription policy must also be configured. For information about how to configure subscription messaging policies, see Subscription policy.

When you use Eclipse Amlen administering and monitoring, global-shared durable subscriptions in the shared namespace are shown with the client ID of __Shared (two leading underscores). Global-shared non-durable subscriptions in the shared namespace are shown with the client ID of __SharedND.

You can use global-shared subscriptions with JMS and MQTT. However, do not allow clients that use different protocols to share global-shared subscriptions.

JMS shared subscriptions

Factors to consider when you use JMS shared subscriptions:
  • The default value for the ClientMessageCache property of a shared subscription is set to 0. A value of 0 maximizes the fairness of message distribution, but does not maximize throughput. If you change the setting of the ClientMessageCache property to a higher value, you can increase throughput. However, a higher setting results in uneven message distribution.
  • When a shared subscription is created, all consumers must use the same value for topic and selector. The noLocal setting is ignored for shared subscriptions.
  • Shared non-durable subscriptions with a specified client ID can exist within the same connection with the same name as a shared durable subscription. To allow this, shared non-durable subscriptions with a specified client ID have an underscore added at the start of the subscription name within the Eclipse Amlen server. Therefore, avoid naming shared durable subscriptions with an underscore to prevent conflicts.

JMS client applications must use the Eclipse Amlen ImaSubscription interface if they are to use shared subscriptions. The methods in this interface allow a topic and a subscription name to be specified when creating or joining a shared subscription. To enable JMS clients to receive messages from a shared subscription, there must exist a topic policy that has a Topic parameter that allows access to the topic that is specified on the subscription. To enable JMS clients to receive messages from a global-shared durable subscription, there must also exist a subscription policy that has a Subscription parameter that matches that matches the DurableName value that was used to create the subscription.

Unshared durable subscriptions must have a client ID specified. The client ID specifies the namespace for the subscription name. Unshared non-durable subscriptions do not require a client ID to be specified.

For details about developing JMS shared subscription applications for use with Eclipse Amlen, see Shared subscriptions in JMS.

MQTT shared subscriptions

For MQTT, Eclipse Amlen provides support only for global-shared subscriptions. To enable MQTT client applications to use global-shared subscriptions, a particular Eclipse Amlen topic filter is required. This topic filter signals to Eclipse Amlen that the subscription is a global-shared subscription. It has the following form:
$SharedSubscription/subName/topicFilter
where:
$SharedSubscription
Indicates that the target of the SUBSCRIBE request is a global-shared subscription. This literal string is case-sensitive.
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.
subName
Is the name of the 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. For information about wildcards in subscriptions, see Wildcards.

To enable MQTT clients to receive messages from a global-shared durable subscription, two messaging policies are required: a topic policy with a Topic parameter that allows access to the topic specified on the subscription and a subscription policy with a Subscription parameter that matches the subName.

For details about developing MQTT shared subscription applications for use with Eclipse Amlen, see Global-shared subscriptions in MQTT.