Class MqttClientRequestBuilder
- java.lang.Object
-
- com.plccom.mqtt.client.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 Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description MqttClientRequestBuildercontentType(String value)Sets the MQTT 5 Content Type property on the request PUBLISH.MqttClientRequestBuildercorrelationData(byte[] value)Sets explicit MQTT 5 Correlation Data for this request.MqttClientRequestBuildermessageExpirySeconds(long value)Sets the MQTT 5 Message Expiry Interval property on the request PUBLISH.MqttClientRequestBuildermessageExpirySeconds(Long value)Sets the MQTT 5 Message Expiry Interval property on the request PUBLISH.MqttClientRequestBuildernoCorrelationData()Sends the request without MQTT 5 Correlation Data.MqttClientRequestBuilderpayloadFormatBytes()Declares the request payload as unspecified binary data for MQTT 5 receivers.MqttClientRequestBuilderpayloadFormatUtf8()Declares the request payload as UTF-8 character data for MQTT 5 receivers.MqttClientRequestBuilderpayloadFormatUtf8(Boolean value)Sets the MQTT 5 Payload Format Indicator property on the request PUBLISH.MqttClientRequestBuilderqos0()Uses QoS 0 for the request PUBLISH.MqttClientRequestBuilderqos1()Uses QoS 1 for the request PUBLISH.MqttClientRequestBuilderqos2()Uses QoS 2 for the request PUBLISH.MqttClientRequestBuilderqualityOfService(PlccomMqttQualityOfService value)Sets the request PUBLISH QoS.MqttClientRequestBuilderrandomCorrelationData()Generates a new random Correlation Data value.MqttClientRequestBuilderresponseMaximumQualityOfService(PlccomMqttQualityOfService value)Sets the maximum QoS for the temporary response subscription.MqttClientRequestBuilderresponseQos0()Requests QoS 0 as maximum QoS for the temporary response subscription.MqttClientRequestBuilderresponseQos1()Requests QoS 1 as maximum QoS for the temporary response subscription.MqttClientRequestBuilderresponseQos2()Requests QoS 2 as maximum QoS for the temporary response subscription.MqttClientRequestBuilderresponseTopic(String value)Sets the MQTT 5 Response Topic where the peer should publish the answer.MqttRequestResponseResultsend()Sends the request and waits for a matching response.MqttClientRequestBuildertimeoutMillis(long value)Sets the maximum time to wait for a matching response.MqttClientRequestBuilderuserProperty(String name, String value)Adds one MQTT 5 User Property to the request PUBLISH.
-
-
-
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- ifvalueisnull
-
qos0
public MqttClientRequestBuilder qos0()
Uses QoS 0 for the request PUBLISH.- Returns:
- this builder
-
qos1
public MqttClientRequestBuilder qos1()
Uses QoS 1 for the request PUBLISH.- Returns:
- this builder
-
qos2
public MqttClientRequestBuilder qos2()
Uses QoS 2 for the request PUBLISH.- Returns:
- this builder
-
qualityOfService
public MqttClientRequestBuilder qualityOfService(PlccomMqttQualityOfService value)
Sets the request PUBLISH QoS.- Parameters:
value- requested QoS for the request PUBLISH- Returns:
- this builder
- Throws:
NullPointerException- ifvalueisnull
-
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
-
responseMaximumQualityOfService
public MqttClientRequestBuilder responseMaximumQualityOfService(PlccomMqttQualityOfService value)
Sets the maximum QoS for the temporary response subscription.- Parameters:
value- maximum response subscription QoS- Returns:
- this builder
- Throws:
NullPointerException- ifvalueisnull
-
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
nullsends no Correlation Data and makes the builder accept the first message received on the response topic.- Parameters:
value- correlation data bytes, ornullto 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- ifvalueis negative
-
payloadFormatUtf8
public MqttClientRequestBuilder payloadFormatUtf8(Boolean value)
Sets the MQTT 5 Payload Format Indicator property on the request PUBLISH.- Parameters:
value- payload format hint, ornullto 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, ornullto 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, ornullto omit it- Returns:
- this builder
- Throws:
IllegalArgumentException- ifvalueis 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- ifvalueis 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 namevalue- property value- Returns:
- this builder
- Throws:
NullPointerException- ifnameorvalueisnull
-
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
-
-