org.eclipse.paho.client.mqttv3

Class MqttMessage

java.lang.Object

org.eclipse.paho.client.mqttv3.MqttMessage

Direct Known Subclasses:

MqttReceivedMessage

public class MqttMessage
extends java.lang.Object

An MQTT message holds the application payload and options specifying how the message is to be delivered The message includes a "payload" (the body of the message) represented as a byte[].

Constructor Summary

Constructors

Constructor and Description
MqttMessage() Constructs a message with an empty payload, and all other values set to defaults.
MqttMessage(byte[] payload) Constructs a message with the specified byte array as a payload, and all other values set to defaults.

Method Summary

Modifier and Type	Method and Description
void	clearPayload() Clears the payload, resetting it to be empty.
int	getId() Returns the MQTT id of the message.
byte[]	getPayload() Returns the payload as a byte array.
int	getQos() Returns the quality of service for this message.
boolean	isDuplicate() Returns whether or not this message might be a duplicate of one which has already been received.
boolean	isRetained() Returns whether or not this message should be/was retained by the server.
void	setId(int messageId) This is only to be used internally to provide the MQTT id of a message received from the server.
void	setPayload(byte[] payload) Sets the payload of this message to be the specified byte array.
void	setQos(int qos) Sets the quality of service for this message.
void	setRetained(boolean retained) Whether or not the publish message should be retained by the messaging engine.
java.lang.String	toString() Returns a string representation of this message's payload.
static void	validateQos(int qos) Utility method to validate the supplied QoS value.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MqttMessage

public MqttMessage()

Constructs a message with an empty payload, and all other values set to defaults. The defaults are:

• Message QoS set to 1
• Message will not be "retained" by the server

MqttMessage

public MqttMessage(byte[] payload)

Constructs a message with the specified byte array as a payload, and all other values set to defaults.

Method Detail

validateQos

public static void validateQos(int qos)

Utility method to validate the supplied QoS value.

Throws:

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

getPayload

public byte[] getPayload()

Returns the payload as a byte array.

Returns:

the payload as a byte array.

clearPayload

public void clearPayload()

Clears the payload, resetting it to be empty.

Throws:

java.lang.IllegalStateException - if this message cannot be edited

setPayload

public void setPayload(byte[] payload)

Sets the payload of this message to be the specified byte array.

Parameters:

payload - the payload for this message.

Throws:

java.lang.IllegalStateException - if this message cannot be edited

java.lang.NullPointerException - if no payload is provided

isRetained

public boolean isRetained()

Returns whether or not this message should be/was retained by the server. For messages received from the server, this method returns whether or not the message was from a current publisher, or was "retained" by the server as the last message published on the topic.

Returns:

true if the message should be, or was, retained by the server.

See Also:

setRetained(boolean)

setRetained

public void setRetained(boolean retained)

Whether or not the publish message should be retained by the messaging engine. Sending a message with retained set to true and with an empty byte array as the payload e.g. new byte[0] will clear the retained message from the server. The default value is false

Parameters:

retained - whether or not the messaging engine should retain the message.

Throws:

java.lang.IllegalStateException - if this message cannot be edited

getQos

public int getQos()

Returns the quality of service for this message.

Returns:

the quality of service to use, either 0, 1, or 2.

See Also:

setQos(int)

setQos

public void setQos(int qos)

Sets the quality of service for this message.

• Quality of Service 0 - indicates that a message should be delivered at most once (zero or one times). The message will not be persisted to disk, and will not be acknowledged across the network. This QoS is the fastest, but should only be used for messages which are not valuable - note that if the server cannot process the message (for example, there is an authorization problem), then an MqttCallback.deliveryComplete(IMqttDeliveryToken). Also known as "fire and forget".
• Quality of Service 1 - indicates that a message should be delivered at least once (one or more times). The message can only be delivered safely if it can be persisted, so the application must supply a means of persistence using MqttConnectOptions. If a persistence mechanism is not specified, the message will not be delivered in the event of a client failure. The message will be acknowledged across the network. This is the default QoS.
• Quality of Service 2 - indicates that a message should be delivered once. The message will be persisted to disk, and will be subject to a two-phase acknowledgement across the network. The message can only be delivered safely if it can be persisted, so the application must supply a means of persistence using MqttConnectOptions. If a persistence mechanism is not specified, the message will not be delivered in the event of a client failure.
If persistence is not configured, QoS 1 and 2 messages will still be delivered in the event of a network or server problem as the client will hold state in memory. If the MQTT client is shutdown or fails and persistence is not configured then delivery of QoS 1 and 2 messages can not be maintained as client-side state will be lost.

Parameters:

qos - the "quality of service" to use. Set to 0, 1, 2.

Throws:

java.lang.IllegalArgumentException - if value of QoS is not 0, 1 or 2.

java.lang.IllegalStateException - if this message cannot be edited

toString

public java.lang.String toString()

Returns a string representation of this message's payload. Makes an attempt to return the payload as a string. As the MQTT client has no control over the content of the payload it may fail.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this message.

isDuplicate

public boolean isDuplicate()

Returns whether or not this message might be a duplicate of one which has already been received. This will only be set on messages received from the server.

Returns:

true if the message might be a duplicate.

setId

public void setId(int messageId)

This is only to be used internally to provide the MQTT id of a message received from the server. Has no effect when publishing messages.

Parameters:

messageId -

getId

public int getId()

Returns the MQTT id of the message. This is only applicable to messages received from the server.

Returns:

the MQTT id of the message