IBM Support

Using WebSphere MQ with Unmanaged Subscription

Technote (troubleshooting)


Is there a way to force WebSphere MQ V7 and higher to use predefined queue for subscription without manually creating a subscription with new MQ verbs or MQExplorer?

Resolving the problem

When the publish/subscribe API was added to the WebSphere MQ server code in V7, the concept of managed and unmanaged subscriptions was intended to be transparent to the JMS code, as this is a concept that does not exist in the JMS specification; it was intended that JMS applications would generally use managed subscriptions automatically. As a result, it seems that extending the use of the WebSphere MQ JMS client code to make use of unmanaged subscriptions was not covered in the documentation.
Here is a summary on the use of unmanaged subscription in JMS. It is possible to administratively create an unmanaged subscription using the WebSphere MQ tooling and then access this pre-existing subscription from within a JMS application, but it is not possible to directly create an unmanaged subscriptions from within the JMS application itself.

The BrokerDurSubQueue property available on the MQTopic object was used in V6 of the WebSphere MQ classes for JMS and earlier to define the queue to which messages for a subscriber to that topic would be sent. There was a restriction on the naming of such a queue that it had to have the prefix "SYSTEM.JMS.D..." in order to provide a scope for possible names that could be used by the internal clean-up code in the JMS client.

With the release of WebSphere MQ V7 and higher, new publish/subscribe verbs were
added to the MQI, and the queue manager became able to internally hold a subscription's messages. This removed the need for an externally controlled subscriber queue and made administration of the queue manager simpler. However, it also removed the option for an application to perform work directly on a subscriber queue, outside the strict publish/subscribe operation defined by the JMS specification. WebSphere MQ therefore introduced the concept of managed and unmanaged subscriptions. In the default, managed, case, a subscription is created and the storage and distribution of messages sent to that subscription is controlled internally by the queue manager itself. In the unmanaged case, messages are sent to an externally visible, named, message queue, and can therefore be viewed and operated upon by application code. The JMS specification contains no such concept; creating a subscriber results in the opening or creation of a subscription that is internally controlled, that is, the equivalent of a managed subscription. The JMS specification distinguishes between queues and topics as completely separate and independent destination types. It is not possible to programmatically create an unmanaged subscription from within a JMS application.

It is possible, however, to use an existing unmanaged subscription from within a JMS application. To do so requires the subscription to be created outside the JMS application itself, and so this process is only usefully applicable to durable subscribers. If a durable subscription is created administratively, such as through the WebSphere MQ Explorer, then this subscription can be re-opened when a durable TopicSubscriber is created.

Creating an unmanaged subscription for use in JMS In order to use an unmanaged subscription from a JMS application using the WebSphere MQ classes for JMS:

1. Create the subscriber queue, that is, the local WebSphere MQ queue to which the subscriptions messages will be sent. Note that the JMS client code will still apply the same restriction to the queue name as in V6, that is, this queue's name must begin with "SYSTEM.JMS.D..."

2. Create the subscription using the WebSphere MQ Explorer (or
runmqsc). Enter the details of the subscriptions as:
* Subscription Name
the full subscription name as used by the JMS client code.
This is constructed according to the following rule:
"JMS:" + <queue manager name> + ":" + <Client ID> + ":" + <JMS
subscription name as passed to the createDurableSubscriber call in the

* Topic name
"SYSTEM.BROKER.DEFAULT.STREAM" or the name of the stream on which
the subscriber will be subscribed.

* Topic string
the name value for the Topic destination on which the subscriber
will be subscribed.

* Destination class provided.

* Destination queue manager
the name of the queue manager on which the subscription is to be created. This is the same as <queue manager name> in the Subscription name

* Destination name
the name of the subscriber queue created in the previous step.

3. Configure the JMS ConnectionFactory object, either in JNDI or
programmatically within the JMS application:

the same value as used for the Topic name when creating the

the same value as used for <client ID> in the full subscription

4. Configure the JMS Topic object, either in JNDI or programmatically
within the JMS application:


the name of the local subscription queue as defined in step 1.

the same value as used for <queue manager name> in the full subscription name, and for Destination queue manager.

5. Within the JMS application itself, in the createDurableSubscriber() call, use the same name as used for the JMS subscription name when constructing the full subscription name in the Explorer Now, when the JMS application runs, the createDurableSubscriber() call will cause the existing, unmanaged, subscription to be opened.

Updating unmanaged subscriptions:

A consequence of using an unmanaged subscription from JMS is that the maintenance of the subscriber queue is no longer performed automatically by the queue manager. This is of particular relevance
if a durable subscriber is updated. According to the JMS specification, "changing a durable subscriber is equivalent to
unsubscribing (deleting) the old one and creating a new one." For a managed subscription, this would include deleting any previously published messages that had not been received by the subscriber
before it was changed. For an unmanaged subscription, changing the subscriber results in a change to the correlationID used by the JMS client code to identify the subscriber's messages, but previously
published messages are not deleted from the queue. These previously published messages will therefore not be received by the changed subscriber, but will remain on the queue until explicitly removed.

Subscriptions created using the WebSphere MQ classes for JMS are always created as managed subscriptions. The JMS specification defines Queues and Topics as independent destination types, and the internals of how the messages for a subscription are stored is not defined in the specification. The management and storage of these messages is therefore delegated to be performed by the queue manager on a managed queue.

JMS durable subscriptions will persist between instances of a particular application, and so it is possible, when using durable subscriptions, to re-open an existing subscription on the queue manager. When the JMS createDurableSubscriber() call is made, the WebSphere MQ classes for JMS will request access to a named subscription from the queue manager and, if this subscription already exists, it will be reopened. This means that if an unmanaged subscription has previously been created on the queue manager with the appropriate name, then the WebSphere MQ classes for JMS will open that subscription and use the unmanaged queue to retrieve subscription messages. However, because the WebSphere MQ classes for JMS is only aware of managed subscriptions, any attempt to update the subscription (such as changing the Topic or selector) will cause the unmanaged subscription to be deleted and replaced by a new managed subscription.

The full subscription name used by the WebSphere MQ classes for JMS is
constructed from a number of different pieces. The full name of the
subscription that is created in the queue manager will be of the form:

QMName is the name of the queue manager on which the subscription has
been created.

clientID is the client ID set on the ConnectionFactory in the JMS

subscriptionName is the subscription name provided as a parameter in the
createDurableSubscriber() call

StreamName is the value of the BrokerPubQueue property on the Connection
Factory, but only if this has been set to a non-default value, otherwise this part is not present.

Each part of the full subscription name uses unicode escape values to
replace any instances of the following characters:
; : " \

This means that it is possible to use JMS to access unmanaged subscriptions, and therefore to send subscription messages to a named queue. However, to do this would be to use the WebSphere MQ classes for JMS in a manner for which it was not originally designed and it would not be possible to change details of such a subscription from within a JMS application. Full JMS support for unmanaged subscriptions is outside the scope of a service fix and would constitute new function.

Product Alias/Synonym


Document information

More support for: WebSphere MQ

Software version: 7.0, 7.0.1, 7.1, 7.5, 8.0

Operating system(s): AIX, Windows

Software edition: All Editions

Reference #: 1472911

Modified date: 06 June 2011