net.sf.xenqtt.message
Class SubscribeMessage

java.lang.Object
  net.sf.xenqtt.message.MqttMessage
      net.sf.xenqtt.message.IdentifiableMqttMessage
          net.sf.xenqtt.message.SubscribeMessage

public final class SubscribeMessage
extends IdentifiableMqttMessage

The SUBSCRIBE message allows a client to register an interest in one or more topic names with the server. Messages published to these topics are delivered from the server to the client as PUBLISH messages. The SUBSCRIBE message also specifies the QoS level at which the subscriber wants to receive published messages.

Assuming that the requested QoS level is granted, the client receives PUBLISH messages at less than or equal to this level, depending on the QoS level of the original message from the publisher. For example, if a client has a QoS level 1 subscription to a particular topic, then a QoS level 0 PUBLISH message to that topic is delivered to the client at QoS level 0. A QoS level 2 PUBLISH message to the same topic is downgraded to QoS level 1 for delivery to the client.

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

This means a publisher is responsible for determining the maximum QoS a message can be delivered at, but a subscriber is able to downgrade the QoS to one more suitable for its usage. The QoS of a message is never upgraded.

When it receives a SUBSCRIBE message from a client, the server responds with a SUBACK message.

A server may start sending PUBLISH messages due to the subscription before the client receives the SUBACK message.

Note that if a server implementation does not authorize a SUBSCRIBE request to be made by a client, it has no way of informing that client. It must therefore make a positive acknowledgement with a SUBACK, and the client will not be informed that it was not authorized to subscribe.

A server may chose to grant a lower level of QoS than the client requested. This could happen if the server is not able to provide the higher levels of QoS. For example, if the server does not provider a reliable persistence mechanism it may chose to only grant subscriptions at QoS 0.

Constructor Summary

SubscribeMessage(ByteBuffer buffer, int remainingLength)
Used to construct a received message.

SubscribeMessage(int messageId, String[] topics, QoS[] requestedQoses)
Used to construct a message for sending

Method Summary

int	getMessageId() The message identifier is present in the variable header of the following MQTT messages: PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.
QoS[]	getRequestedQoSes() The requested QoS's for the topics subscribed to.
String[]	getTopics() The topics to subscribe to.
void	setMessageId(int messageId) Sets the message ID

Methods inherited from class net.sf.xenqtt.message.MqttMessage

byteBufferToHex, bytesToHex, equals, getMessageType, getQoS, getQoSLevel, getRemainingLength, hashCode, isAck, isAckable, isDuplicate, isRetain, setDuplicateFlag, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SubscribeMessage

public SubscribeMessage(ByteBuffer buffer,
                        int remainingLength)

Used to construct a received message.

SubscribeMessage

public SubscribeMessage(int messageId,
                        String[] topics,
                        QoS[] requestedQoses)

Used to construct a message for sending

Method Detail

getMessageId

public int getMessageId()

Description copied from class: IdentifiableMqttMessage

The message identifier is present in the variable header of the following MQTT messages: PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.

The Message Identifier (Message ID) field is only present in messages where the QoS bits in the fixed header indicate QoS levels 1 or 2. See section on Quality of Service levels and flows for more information.

The Message ID is a 16-bit unsigned integer that must be unique amongst the set of "in flight" messages in a particular direction of communication. It typically increases by exactly one from one message to the next, but is not required to do so.

A client will maintain its own list of Message IDs separate to the Message IDs used by the server it is connected to. It is possible for a client to send a PUBLISH with Message ID 1 at the same time as receiving a PUBLISH with Message ID 1.

Do not use Message ID 0. It is reserved as an invalid Message ID.

Override this implementation for messages where the message ID is not at offset 2 of a fixed length message

Overrides:

getMessageId in class IdentifiableMqttMessage

See Also:

IdentifiableMqttMessage.getMessageId()

setMessageId

public void setMessageId(int messageId)

Description copied from class: IdentifiableMqttMessage

Sets the message ID

Override this implementation for messages where the message ID is not at offset 2 of a fixed length message

Overrides:

setMessageId in class IdentifiableMqttMessage

See Also:

IdentifiableMqttMessage.setMessageId(int)

getTopics

public String[] getTopics()

The topics to subscribe to. The topic strings may contain special Topic wildcard characters to represent a set of topics.

getRequestedQoSes

public QoS[] getRequestedQoSes()

The requested QoS's for the topics subscribed to. Each entry in this array applies to the topic at the same index in the array returned by getTopics().