Class MqttMessage

java.lang.Object
org.mqtt4j.hato.MqttMessage
public final class MqttMessage extends Object

An immutable application message: a topic, a payload, a QoS, a retain flag, and the MQTT 5.0 message properties. The payload and the Correlation Data are copied on construction and on access. Equality compares every component, including the payload contents and the order of the User Properties. toString() reports the payload, the Correlation Data, and the User Properties only by size, because they carry application data, and leaves out properties that are not set. Each with method returns a copy with one setting changed.

All QoS values can be represented and published. The properties need MQTT 5.0: an MQTT 3.1.1 client refuses to publish a message that has any of them, and receives messages without them. A received message carries the properties that the broker forwarded.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<String>
    contentType()
    Returns the content type that describes the payload, or empty when absent.
    Optional<byte[]>
    correlationData()
    Returns a copy of the Correlation Data, or empty when absent.
    boolean
    equals(@Nullable Object other)
     
    int
    hashCode()
     
    Optional<Duration>
    messageExpiry()
    Returns the lifetime of the message, or empty when it does not expire.
    static MqttMessage
    of(Topic topic, byte[] payload, Qos qos, boolean retain)
    Creates a message without properties, with a copy of the application bytes.
    byte[]
    payload()
    Returns a copy of the application bytes.
    int
    payloadSize()
    Returns the payload byte count without copying its contents.
    boolean
    payloadUtf8()
    Returns whether the payload is declared as UTF-8 encoded character data.
    Qos
    qos()
    Returns the requested or received quality of service.
    Optional<Topic>
    responseTopic()
    Returns the topic for a reply, or empty when absent.
    boolean
    retain()
    Returns whether publication requests retention, or reception is a retained delivery: one that the broker sent from its retained messages as it made the subscription.
    Topic
    topic()
    Returns the published topic name.
    String
    toString()
     
    List<UserProperty>
    userProperties()
    Returns the User Properties in order, possibly repeating a name.
    MqttMessage
    withContentType(String contentType)
    Returns a copy with a content type (the MQTT 5.0 Content Type) that describes the payload, such as a MIME type.
    MqttMessage
    withCorrelationData(byte[] correlationData)
    Returns a copy with a copy of correlationData (the MQTT 5.0 Correlation Data), at most 65535 bytes and possibly empty, which a reply can return to identify its request.
    MqttMessage
    withMessageExpiry(Duration messageExpiry)
    Returns a copy with a lifetime (the MQTT 5.0 Message Expiry Interval) from zero to 4294967295 seconds; a fraction of a second is rounded up when sent.
    MqttMessage
    withPayload(byte[] payload)
    Returns a copy with a different payload, copying the supplied bytes.
    MqttMessage
    withPayloadUtf8(boolean payloadUtf8)
    Returns a copy that declares the payload as UTF-8 encoded character data (true, the MQTT 5.0 Payload Format Indicator) or as unspecified bytes (false).
    MqttMessage
    withQos(Qos qos)
    Returns a copy with a different requested or received quality of service.
    MqttMessage
    withResponseTopic(Topic responseTopic)
    Returns a copy that names the topic for a reply (the MQTT 5.0 Response Topic).
    MqttMessage
    withRetain(boolean retain)
    Returns a copy with a different retention request or retained-delivery flag.
    MqttMessage
    withTopic(Topic topic)
    Returns a copy with a different published topic.
    MqttMessage
    withUserProperties(List<UserProperty> userProperties)
    Returns a copy whose User Properties are a copy of userProperties, in the same order.

    Methods inherited from class Object

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

  • Method Details

    • of

      public static MqttMessage of(Topic topic, byte[] payload, Qos qos, boolean retain)
      Creates a message without properties, with a copy of the application bytes.
      Parameters:
      topic - the published topic name
      payload - the application bytes, possibly empty
      qos - the requested or received quality of service
      retain - whether publication requests retention, or reception is a retained delivery
      Returns:
      the message

    • withTopic

      public MqttMessage withTopic(Topic topic)
      Returns a copy with a different published topic.
      Parameters:
      topic - the published topic name
      Returns:
      a copy with a different published topic

    • withPayload

      public MqttMessage withPayload(byte[] payload)
      Returns a copy with a different payload, copying the supplied bytes.
      Parameters:
      payload - the application bytes, possibly empty
      Returns:
      a copy with a different payload, copying the supplied bytes

    • withQos

      public MqttMessage withQos(Qos qos)
      Returns a copy with a different requested or received quality of service.
      Parameters:
      qos - the requested or received quality of service
      Returns:
      a copy with a different requested or received quality of service

    • withRetain

      public MqttMessage withRetain(boolean retain)
      Returns a copy with a different retention request or retained-delivery flag.
      Parameters:
      retain - whether publication requests retention, or reception is a retained delivery
      Returns:
      a copy with a different retention request or retained-delivery flag

    • withPayloadUtf8

      public MqttMessage withPayloadUtf8(boolean payloadUtf8)
      Returns a copy that declares the payload as UTF-8 encoded character data (true, the MQTT 5.0 Payload Format Indicator) or as unspecified bytes (false). Neither publication nor reception checks the payload against the declaration.
      Parameters:
      payloadUtf8 - whether the payload is declared as UTF-8 encoded character data
      Returns:
      a copy that declares the payload as UTF-8 encoded character data (true, the MQTT 5.0 Payload Format Indicator) or as unspecified bytes (false)

    • withMessageExpiry

      public MqttMessage withMessageExpiry(Duration messageExpiry)
      Returns a copy with a lifetime (the MQTT 5.0 Message Expiry Interval) from zero to 4294967295 seconds; a fraction of a second is rounded up when sent. When the lifetime passes before the broker starts delivering the message to a subscriber, the broker discards it for that subscriber. The client sends the same lifetime however long the message waits to be sent, including a resend in a later connection.
      Parameters:
      messageExpiry - the lifetime of the message
      Returns:
      a copy with a lifetime (the MQTT 5.0 Message Expiry Interval) from zero to 4294967295 seconds; a fraction of a second is rounded up when sent
      Throws:
      IllegalArgumentException - 
      if `messageExpiry` is negative or exceeds 4294967295 seconds

    • withContentType

      public MqttMessage withContentType(String contentType)
      Returns a copy with a content type (the MQTT 5.0 Content Type) that describes the payload, such as a MIME type. It is an MQTT UTF-8 string of at most 65535 bytes and may be empty.
      Parameters:
      contentType - the content type that describes the payload
      Returns:
      a copy with a content type (the MQTT 5.0 Content Type) that describes the payload, such as a MIME type
      Throws:
      IllegalArgumentException - 
      if `contentType` contains U+0000 or an unpaired surrogate, or exceeds 65535 bytes in
UTF-8

    • withResponseTopic

      public MqttMessage withResponseTopic(Topic responseTopic)
      Returns a copy that names the topic for a reply (the MQTT 5.0 Response Topic).
      Parameters:
      responseTopic - the topic for a reply
      Returns:
      a copy that names the topic for a reply (the MQTT 5.0 Response Topic)

    • withCorrelationData

      public MqttMessage withCorrelationData(byte[] correlationData)
      Returns a copy with a copy of correlationData (the MQTT 5.0 Correlation Data), at most 65535 bytes and possibly empty, which a reply can return to identify its request.
      Parameters:
      correlationData - the Correlation Data
      Returns:
      a copy with a copy of correlationData (the MQTT 5.0 Correlation Data), at most 65535 bytes and possibly empty, which a reply can return to identify its request
      Throws:
      IllegalArgumentException - 
      if `correlationData` exceeds 65535 bytes

    • withUserProperties

      public MqttMessage withUserProperties(List<UserProperty> userProperties)
      Returns a copy whose User Properties are a copy of userProperties, in the same order. An empty list leaves the copy without User Properties.
      Parameters:
      userProperties - the User Properties in order
      Returns:
      a copy whose User Properties are a copy of userProperties, in the same order
      Throws:
      NullPointerException - 
      if `userProperties` or one of its elements is null

    • topic

      public Topic topic()
      Returns the published topic name.
      Returns:
      the published topic name

    • payload

      public byte[] payload()
      Returns a copy of the application bytes.
      Returns:
      a copy of the application bytes

    • qos

      public Qos qos()
      Returns the requested or received quality of service.
      Returns:
      the requested or received quality of service

    • retain

      public boolean retain()
      Returns whether publication requests retention, or reception is a retained delivery: one that the broker sent from its retained messages as it made the subscription. A subscription with Subscribe.retainAsPublished() instead receives the retain flag that the publisher set.
      Returns:
      whether publication requests retention, or reception is a retained delivery: one that the broker sent from its retained messages as it made the subscription

    • payloadSize

      public int payloadSize()
      Returns the payload byte count without copying its contents.
      Returns:
      the payload byte count without copying its contents

    • payloadUtf8

      public boolean payloadUtf8()
      Returns whether the payload is declared as UTF-8 encoded character data. False means unspecified bytes, which is also what MQTT 5.0 assumes without a Payload Format Indicator.
      Returns:
      whether the payload is declared as UTF-8 encoded character data

    • messageExpiry

      public Optional<Duration> messageExpiry()
      Returns the lifetime of the message, or empty when it does not expire. A received message reports the lifetime that remained when the broker forwarded it.
      Returns:
      the lifetime of the message, or empty when it does not expire

    • contentType

      public Optional<String> contentType()
      Returns the content type that describes the payload, or empty when absent.
      Returns:
      the content type that describes the payload, or empty when absent

    • responseTopic

      public Optional<Topic> responseTopic()
      Returns the topic for a reply, or empty when absent.
      Returns:
      the topic for a reply, or empty when absent

    • correlationData

      public Optional<byte[]> correlationData()
      Returns a copy of the Correlation Data, or empty when absent. Present Correlation Data can be an empty array.
      Returns:
      a copy of the Correlation Data, or empty when absent

    • userProperties

      public List<UserProperty> userProperties()
      Returns the User Properties in order, possibly repeating a name. The list cannot be modified.
      Returns:
      the User Properties in order, possibly repeating a name

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object