SUBSCRIBE

Subscribe to named Topics

The SUBSCRIBE message allows a client to register an interest, with the broker, in one or more Topic Names. Messages which are published to these Topics will be delivered from the broker to the client in the form of a PUBLISH message. The SUBSCRIBE message also specifies the Quality of Service at which the subscriber wishes to receive published messages.
 

Fixed Header

See the Fixed Header section for more information,
 
bit
7
6
5
4
3
2
1
0
byte 1 
Message Type (8)
DUP flag
QoS level
RETAIN
 
1
0
0
0
0
 0
1 
x
byte 2 
Remaining Length

This example shows the first transmission (DUP flag clear).
 

QoS level

SUBSCRIBE messages use a QoS of 1, to allow the acknowledgement of multiple subscription requests to be managed. The corresponding SUBACK can be identified by matching the Message ID. This also allows the handling of retries on SUBSCRIBE messages to be handled in exactly the same way as a PUBLISH message.
 

DUP flag

The DUP bit should be set if this is a message that is being retransmitted after the non-arrival of a SUBACK message after some specified timeout. This indicates to the broker that it may be a duplicate of a message already received. If this is the first sending of the message, the DUP bit should be clear.
 

RETAIN flag

The RETAIN flag is not used in the SUBSCRIBE message.
 

Remaining Length

The Remaining Length is the length of the Payload.
This may be a multi-byte field. See the Fixed Header section for more details.
 

Variable Header

The Variable Header portion of the SUBSCRIBE message contains the Message Identifier.

Message Identifier

SUBSCRIBE is treated as a QoS1 message, and so has a Message ID. See the QoS section for more details. It should be noted that typically the protocol library would take responsibility for generating this identifier, and passing it back to the publishing application, possibly as a return handle. This approach avoids the risk of duplicate Message Identifiers being generated by multiple applications, or multiple publishing threads, running on a single client.

The Message Identifer is a 16 bit unsigned integer, which will typically increase, but is not required to increase
by exactly one from one message to the next.
The ordering of the 2 bytes of the Message Identifier is MSB, then LSB (big-endian).

Message ID 0 (i.e. 0x0000) is reserved as an invalid Message ID, and must not be used.

See the Variable Header section for more information.
 

As an example, if the Message ID is 10, the format of the Variable Header would be:
 
  Description
7
6
5
4
3
2
1
0
Message Identifier
byte 1 Message ID MSB (0)
0
0
0
0
0
0
0
0
byte 2 Message ID LSB (10) 0 0 0 0 1 0 1 0

 
 

Payload

The Payload of a SUBSCRIBE message contains a list of Topic Names which the client wishes to subscribe to, and the Quality of Service level at which the client wishes them to be delivered. The strings are UTF-encoded, and the requested QoS occupies 2 bits of a single byte. These Topic/QoS pairs are packed contiguously, one after the other, as shown in the example below.

The Topic Names in a SUBSCRIBE message will not be compressed in any way.

Assuming that the requested Quality of Service is granted (see the SUBACK section for more information), then the client will receive PUBLISH messages at less than or equal to this quality of service, depending on the QoS of the original message from the publisher. For example, if a client has a QoS 1 subscription to a particular topic, then a QoS 0 publish to that topic will be delivered to this client at QoS 0. A QoS 2 publish to the same topic will be downgraded to QoS 1 for delivery to this client.
 

Note that a corollary to this is that subscribing to a Topic at QoS 2 is equivalent to saying "I would like to receive messages on this Topic at the QoS at which they are published".

The Requested Quality of Service field is encoded in the byte following each UTF-encoded Topic Name as follows:
 
bit
7
6
5
4
3
2
1
0
 
reserved
reserved
reserved
reserved
reserved
reserved
QoS level
 
x
x
x
x
x
x
    

The upper  6 bits of this byte are currently unused in this version of the protocol. They are, however reserved for future use.
 

Example:
 
Topic Name "a/b"
Requested QoS 1
Topic Name "c/d"
Requested QoS 2

The format of the Payload in this case would be:
 
  Description 7
6
5
4
3
2
1
0
Topic Name
byte 1 Length MSB (0) 0
0
0
0
0
0
0
0
byte 2 Length LSB (3) 0
0
0
0
0
0
1
1
byte 3
'a' (0x61)
 0
1
1
0
0
0
0
1
byte 4
'/' (0x2F)
 0
0
1
0
1
1
1
1
byte 5
'b' (0x62)
 0
1
1
0
0
0
1
0
Requested QoS
byte 6 Requested QoS (1) x
x
x
x
x
x
0
1
Topic Name
byte 7 Length MSB (0) 0
0
0
0
0
0
0
0
byte 8 Length LSB (3) 0
0
0
0
0
0
1
1
byte 9
'c' (0x63)
 0
1
1
0
0
0
1
1
byte 10
'/' (0x2F)
 0
0
1
0
1
1
1
1
byte 11
'd' (0x64)
 0
1
1
0
0
1
0
0
Requested QoS
byte 12 Requested QoS (2) x
x
x
x
x
x
1
0

 

Response

The response from the broker to a client SUBSCRIBE message is a SUBACK message from the broker.
 

Discussion

ASC on QoS in Topic Name list
The addition of a "requested" QoS level to each Topic Name in the SUBSCRIBE payload allows a client which knows that it is only interested in data on a "best can do" basis to make that known to the broker, so broker resources are not tied up trying to complete assured delivery of messages to a client which doesn't care very much about the messages. Also, by putting a "granted" QoS level in the SUBACK message, the administrator of the broker can exercise control over resources in the broker, by for example only allowing a certain Quality of Service to a particular client's subscription to a specific Topic.

 
ASC on Message ID
In order to be able to distinguish the SUBACKs from multiple SUBSCRIBEs, we are making SUBSCRIBE a QoS1 message, so that the the SUBACK will have a Message ID which can be matched against that of the SUBSCRIBE message.

 
ASC on wildcards
What syntax do we support for wildcards? Is it just '*' in the pattern, or do we support the full Argo set?
ASC comment
See the Topics section for an explanation of the wildcard and topic hierarchy system for MQ Series Integrator Version 2.

 
ASC on Content-based subscriptions
Is there any requirement for content-based subscriptions, and if so, what syntax would we use to specify the filters?
Comment
We should leave this for the future, and at that time, use the JMS filter syntax.
ASC on Durable subsriptions
Is there a need for Durable subscriptions (i.e. those which store messages while a subscriber is disconnected, and then delivers them upon reconnection)?
Comment
Although there has been no requirement for this to date, it is clear that it has potential use, and it should be included in a future version of the protocol.
ASC Comment
MQ Series Integrator Version 2 provided durable subscriptions by default. The client must explicitly UNSUBSCRIBE from Topics in which it no longer has an interest.
ASC on JMS
We should ensure that we are able to support JMS functionality in the future, by not limiting the protocol too much at this point.
Comment
Agreed.

 
ASC on duplicate SUBSCRIBE messages
Note that the benefit of the idempotency of SUBSCRIBE messages is that we do not have to get involved with Message Identifiers and DUP bits when submitting a subscription request.
ASC comment
Ah yes, but what if the client submits two SUBSCRIBEs to different Topics? How does it know which received SUBACK relates to which SUBSCRIBE? In Version 2 of the protocol, SUBSCRIBE becomes a QoS1 message.

TNH on SUBSCRIBE
The primary use of this protocol is intended to be for remote clients publishing information for consumption within an enterprise, using a "push" paradigm. The inclusion of the SUBSCRIBE message really represents a recasting of the traditional "command flow" from broker to client into the pub/sub paradigm. As such, it is not really symmetrical in terms of the nature of the information conveyed in each direction. This may mean that we may not feel obliged to maintain the purity of the pub/sub paradigm from broker to client, and perhaps introduce a "send" message for the broker to client segment of a message's routing.
ASC comment
Agreed, but for now, the client will see a PUBLISH from the broker when a message is published on a Topic to which it is subscribed, thus maintaining symmettry.
TNH on SUBSCRIBE
A client could conceivable subscribe to a Topic and wish to ensure that it receives subsequent messages in a realiable manner. Should we therefore consider putting QoS into the SUBSCRIBE message?
BACK to index 
Last Modified: 19-Oct-99