Class MqttClientRequestBuilder


  • public final class MqttClientRequestBuilder
    extends Object
    High-level builder for one MQTT 5 request/response exchange.

    MQTT 5 request/response is built from normal PUBLISH and SUBSCRIBE packets: the requester subscribes to a response topic, publishes the request with the MQTT 5 Response Topic property and usually includes Correlation Data so the later response can be matched to the request. This builder wraps that sequence for simple blocking use cases and automatically removes the temporary response subscription after the exchange finishes.

    The builder waits by calling PlccomMqttClient.receive(long). That keeps the API dependency-free and works with custom client implementations, but it also means concurrent code that reads from the same client may race with this request. Applications with many concurrent request/response exchanges should prefer their own callback or routing layer on top of the lower-level publish/subscribe API.

    • Method Detail

      • responseTopic

        public MqttClientRequestBuilder responseTopic​(String value)
        Sets the MQTT 5 Response Topic where the peer should publish the answer.
        Parameters:
        value - response Topic Name
        Returns:
        this builder
        Throws:
        NullPointerException - if value is null
      • responseQos0

        public MqttClientRequestBuilder responseQos0()
        Requests QoS 0 as maximum QoS for the temporary response subscription.
        Returns:
        this builder
      • responseQos1

        public MqttClientRequestBuilder responseQos1()
        Requests QoS 1 as maximum QoS for the temporary response subscription.
        Returns:
        this builder
      • responseQos2

        public MqttClientRequestBuilder responseQos2()
        Requests QoS 2 as maximum QoS for the temporary response subscription.
        Returns:
        this builder
      • correlationData

        public MqttClientRequestBuilder correlationData​(byte[] value)
        Sets explicit MQTT 5 Correlation Data for this request.

        By default the builder creates a random 16-byte value and requires the response to carry the same value. Supplying null sends no Correlation Data and makes the builder accept the first message received on the response topic.

        Parameters:
        value - correlation data bytes, or null to omit the property
        Returns:
        this builder
      • randomCorrelationData

        public MqttClientRequestBuilder randomCorrelationData()
        Generates a new random Correlation Data value.
        Returns:
        this builder
      • noCorrelationData

        public MqttClientRequestBuilder noCorrelationData()
        Sends the request without MQTT 5 Correlation Data.

        Without Correlation Data the first received message on the response topic is treated as the response. This is convenient for tiny examples, but explicit Correlation Data is safer when multiple requests can be in flight or when retained/stale messages may exist on the response topic.

        Returns:
        this builder
      • timeoutMillis

        public MqttClientRequestBuilder timeoutMillis​(long value)
        Sets the maximum time to wait for a matching response.
        Parameters:
        value - timeout in milliseconds
        Returns:
        this builder
        Throws:
        IllegalArgumentException - if value is negative
      • payloadFormatUtf8

        public MqttClientRequestBuilder payloadFormatUtf8​(Boolean value)
        Sets the MQTT 5 Payload Format Indicator property on the request PUBLISH.
        Parameters:
        value - payload format hint, or null to omit the property
        Returns:
        this builder
      • payloadFormatUtf8

        public MqttClientRequestBuilder payloadFormatUtf8()
        Declares the request payload as UTF-8 character data for MQTT 5 receivers.
        Returns:
        this builder
      • payloadFormatBytes

        public MqttClientRequestBuilder payloadFormatBytes()
        Declares the request payload as unspecified binary data for MQTT 5 receivers.
        Returns:
        this builder
      • contentType

        public MqttClientRequestBuilder contentType​(String value)
        Sets the MQTT 5 Content Type property on the request PUBLISH.
        Parameters:
        value - content type, or null to omit the property
        Returns:
        this builder
      • messageExpirySeconds

        public MqttClientRequestBuilder messageExpirySeconds​(Long value)
        Sets the MQTT 5 Message Expiry Interval property on the request PUBLISH.
        Parameters:
        value - expiry interval in seconds, or null to omit it
        Returns:
        this builder
        Throws:
        IllegalArgumentException - if value is outside the MQTT unsigned 32-bit range
      • messageExpirySeconds

        public MqttClientRequestBuilder messageExpirySeconds​(long value)
        Sets the MQTT 5 Message Expiry Interval property on the request PUBLISH.
        Parameters:
        value - expiry interval in seconds
        Returns:
        this builder
        Throws:
        IllegalArgumentException - if value is outside the MQTT unsigned 32-bit range
      • userProperty

        public MqttClientRequestBuilder userProperty​(String name,
                                                     String value)
        Adds one MQTT 5 User Property to the request PUBLISH.
        Parameters:
        name - property name
        value - property value
        Returns:
        this builder
        Throws:
        NullPointerException - if name or value is null
      • send

        public MqttRequestResponseResult send()
        Sends the request and waits for a matching response.
        Returns:
        request/response result containing the matched response message
        Throws:
        IllegalStateException - if no response topic was configured