About Shared Topic Subscriptions for Clustered Containers

The Message Queue JMS Resource Adapter provides a special feature called shared subscriptions for containers that support clustering, such as GlassFish Server. This feature enables clustered containers to share the load of processing messages for topic subscriptions across the instances of a cluster.

When this feature is enabled, the following behaviors apply:

• Attempts by multiple connections to use the same client id do not result in an exception, provided that the connections are from different instances in the cluster.

• Two or more subscriptions on the same topic with the same client id and (if the subscription is durable) the same durable subscription name are considered "shared"; that is, they are treated as a single subscription, with each message being sent to only one of the participating subscriptions.

The sharing of subscriptions relies on client id being set, not only for durable subscriptions (which always require client id) but for non-durable subscriptions (which do not normally require client id). If the subscription is being created by the resource adapter for use by a message-driven bean (MDB), and client id is not set, then the resource adapter will set the client id to the name of the MDB. However if the subscription is being created programmatically using the JMS API, and client id is not set, then an exception will be thrown.

Note that, in the EJB or web container, applications that create a connection using a connection factory are not permitted to set client id on the newly created connection, but must set it on the connection factory instead. This restriction is imposed by the EJB specification, though it applies to web components as well. There is no such restrictions in the application client container.

Disabling Shared Subscriptions

By default, the shared subscriptions feature is enabled. In some applications that use non-durable subscriptions, however, the shared behavior is not desired. In such cases, disable the shared subscriptions feature by setting the useSharedSubscriptionInClusteredContainer property to false on either the ActivationSpec or ManagedConnectionFactory, as appropriate:

• For an MDB, set the ActivationSpec property useSharedSubscriptionInClusteredContainer to false. Do this in exactly the same way as with other ActivationSpec properties, using annotations in the MDB itself or in the deployment descriptor ejb-jar.xml or glassfish-ejb-jar.xml. Alternatively, if the glassfish-ejb-jar.xml deployment descriptor specifies a connection factory using the <mdb-connection-factory> element, then the property can be configured on the connection factory instead, as described in the next item.

• For GlassFish applications creating a non-durable subscription using the JMS API rather than using an MDB, set the connection factory property useSharedSubscriptionInClusteredContainer to false using the GlassFish Administration Console, the GlassFish asadmin command or the resource descriptor glassfish-resources.xml.

Only set useSharedSubscriptionInClusteredContainer to false for non-durable subscriptions.

Consumer Flow Control When Shared Subscriptions Are Used

When shared subscriptions are being used, then consumer flow control operates slightly differently than is described in Client Runtime Message Flow Adjustments.

With a normal topic subscription, the maximum number of messages that can be held pending for any single subscriber, waiting to be consumed, is defined by the broker property imq.autocreate.topic.consumerFlowLimit for auto-created topics, or the destination property consumerFlowLimit for administratively-created topics. Both properties have a default value of 1000. This can be overridden on a per-connection basis by setting the connection factory property imqConsumerFlowLimit to a lower value than that defined for the topic.

When the subscription is shared, however, different logic applies. In this case, the limit is defined by the broker property imq.autocreate.topic.sharedConsumerFlowLimit for auto-created topics or the broker property imq.admincreate.topic.sharedConsumerFlowLimit for all administratively-created topics. It is not possible to set this limit on individual administratively-created topics. Both properties have a default value of 5. This can be overridden on a per-connection basis by setting the connection factory property imqConsumerFlowLimit to a lower value than that defined for the topic. Note that, as with all connection factory properties, this is specified using the options property of the managed connection factory.