Publications
Publications are instances of MqttMessage that are associated with a topic string. MQTT clients can create publications to send to IBM® MQ, and subscribe to topics on IBM MQ MQ to receive publications.
An MqttMessage has a byte array as its payload. Aim to keep messages as small as possible. The maximum length of message permitted by the MQTT protocol is 250 MB.
Typically, an MQTT client program uses java.lang.String or java.lang.StringBuffer to manipulate message contents. For convenience, the MqttMessage class has a toString method to convert its payload to a string. To create the byte array payload from a java.lang.String or java.lang.StringBuffer, use the getBytes method.
The getBytes method converts a string to the default character set for the platform. The default character set is generally UTF-8. MQTT publications that contain only text are usually encoded in UTF-8. Use the method getBytes("UTF8") to override the default character set.
In IBM MQ, an MQTT publication is received as a jms-bytes message. The message includes an MQRFH2 folder containing an <mqtt>, and an <mqps> folder. The <mqtt> folder contains the clientId and qos, but this content might change in the future.
An MqttMessage has three additional attributes: quality of service, whether it is retained, and whether it is a duplicate. The duplicate flag is only set if the quality of service is "at least once" or "exactly once". If the message was sent previously, and not acknowledged quickly enough by the MQTT client, the message is sent again, with the duplicate attribute set to true.
Publishing
To create a publication in an MQTT client application, create an MqttMessage. Set its payload, quality of service and whether it is retained, and call the MqttTopic.publish(MqttMessage message) method; MqttDeliveryToken is returned and the completion of the publication is asynchronous.
Alternatively, the MQTT client can create a temporary message object for you from the parameters on the MqttTopic.publish(byte [] payload, int qos, boolean retained) method when it creates a publication.
If the publication has an "at least once" or an "exactly once" quality of service, QoS=1 or QoS=2, the MQTT client calls the MqttClientPersistence interface. It calls MqttClientPersistence to store the message before returning a delivery token to the application.
The application can choose to block until the message is delivered to the server, using the MqttDeliveryToken.waitForCompletion method. Alternatively, the application can continue without blocking. If you want to check if publications are delivered, without blocking, register an instance of a callback class that implements MqttCallback with the MQTT client. The MQTT client calls the MqttCallback.deliveryComplete method as soon as the publication has been delivered. Depending on the quality of service, the delivery might be almost immediate for QoS=0, or it might take some time for QoS=2.
Use the MqttDeliveryToken.isComplete method to poll if delivery is complete. While the value of MqttDeliveryToken.isComplete is false, you can call MqttDeliveryToken.getMessage to get the message contents. If the result of calling MqttDeliveryToken.isComplete is true, the message has been discarded and calling MqttDeliveryToken.getMessage would throw a null pointer exception. There is no built-in synchronization between MqttDeliveryToken.getMessage and MqttDeliveryToken.isComplete.
If the client disconnects before receiving all the pending delivery tokens, a new instance of the client can query pending delivery tokens before connecting. Until the client connects, no new deliveries are completed, and it is safe to call MqttDeliveryToken.getMessage. Use the MqttDeliveryToken.getMessage method to find out which publications have not been delivered. Pending delivery tokens are discarded if you connect with MqttConnectOptions.cleanSession set to its default value, true.
Subscribing
A queue manager or IBM MessageSight is responsible for creating publications to send to an MQTT subscriber. The queue manager checks if the topic filter in a subscription created by an MQTT client matches the topic string in a publication. The match can either be an exact match, or the match can include wildcards. Before the publication is forwarded to the subscriber by the queue manager, the queue manager checks the topic attributes associated with the publication. It follows the search procedure described in Subscribing using a topic string that contains wildcard characters to identify if an administrative topic object grants the user authority to subscribe.
When the MQTT client receives a publication with "at least once" quality of service, it calls the MqttCallback.messageArrived method to process the publication. If the quality of service of the publication is "exactly once", QoS=2, the MQTT client calls the MqttClientPersistence interface to store the message when it is received. It then calls MqttCallback.messageArrived.