Interface PlccomMqttClient
-
- All Superinterfaces:
AutoCloseable
public interface PlccomMqttClient extends AutoCloseable
Synchronous PLCcom MQTT client.This interface represents the supported blocking client facade for MQTT applications. Use it when application code wants explicit control over when CONNECT, PUBLISH, SUBSCRIBE, RECEIVE and DISCONNECT operations are executed. Convenience builders are available for the common publish, subscribe and MQTT 5 request/response workflows, while prepared value objects remain available for applications that build MQTT packets in a separate layer.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default PlccomMqttAsyncClientasync()Creates a CompletableFuture based comfort facade for this client.default PlccomMqttAsyncClientasync(Executor executor)Creates a CompletableFuture based comfort facade for this client using a caller-provided executor.voidclose()Closes the client.PlccomMqttConnectResultconnect()Opens the socket and performs MQTT CONNECT.voiddisconnect()Sends MQTT DISCONNECT and closes the connection.PlccomMqttProtocolVersiongetNegotiatedProtocolVersion()Returns the negotiated concrete protocol version.default PlccomMqttClientOptionsgetOptions()Returns the immutable options this client was created with.booleanisConnected()Returns whether the client is connected.default PlccomMqttClientonConnected(MqttConnectedListener listener)Registers a high-level callback for successful MQTT connections.default PlccomMqttClientonDiagnostic(PlccomMqttDiagnosticListener listener)Registers a diagnostic listener.default PlccomMqttClientonDisconnected(MqttDisconnectedListener listener)Registers a high-level callback for MQTT disconnect events.default PlccomMqttClientonReconnectFailed(MqttReconnectFailedListener listener)Registers a high-level callback for failed bounded automatic reconnect.voidpublish(PlccomMqttPublishMessage message)Publishes a message.default MqttClientPublishBuilderpublish(String topic, boolean payload)Creates a high-level publish operation for a boolean payload.default MqttClientPublishBuilderpublish(String topic, byte[] payload)Creates a high-level publish operation for a binary payload.default MqttClientPublishBuilderpublish(String topic, double payload)Creates a high-level publish operation for a double payload.default MqttClientPublishBuilderpublish(String topic, int payload)Creates a high-level publish operation for an integer payload.default MqttClientPublishBuilderpublish(String topic, long payload)Creates a high-level publish operation for a long payload.default MqttClientPublishBuilderpublish(String topic, String payload)Creates a high-level publish operation for a UTF-8 string payload.PlccomMqttPublishMessagereceive(long timeoutMillis)Receives the next inbound publish.default MqttMessagereceiveMessage(long timeoutMillis)Receives the next inbound publish as a comfort message.default MqttClientRequestBuilderrequest(String topic, boolean payload)Creates a high-level MQTT 5 request/response operation for a boolean payload.default MqttClientRequestBuilderrequest(String topic, byte[] payload)Creates a high-level MQTT 5 request/response operation for a binary payload.default MqttClientRequestBuilderrequest(String topic, double payload)Creates a high-level MQTT 5 request/response operation for a double payload.default MqttClientRequestBuilderrequest(String topic, int payload)Creates a high-level MQTT 5 request/response operation for an integer payload.default MqttClientRequestBuilderrequest(String topic, long payload)Creates a high-level MQTT 5 request/response operation for a long payload.default MqttClientRequestBuilderrequest(String topic, String payload)Creates a high-level MQTT 5 request/response operation for a UTF-8 string payload.voidsetDiagnosticLevel(PlccomMqttDiagnosticLevel level)Changes the SDK diagnostic level of this client at runtime.voidsubscribe(PlccomMqttSubscription subscription)Subscribes to a topic filter.default MqttClientSubscribeBuildersubscribe(String topicFilter)Creates a high-level subscribe operation for one topic filter.voidunsubscribe(String topicFilter)Removes one topic-filter subscription.
-
-
-
Method Detail
-
async
default PlccomMqttAsyncClient async()
Creates a CompletableFuture based comfort facade for this client.On Java 21 and newer the returned facade schedules blocking client operations on virtual threads, so each pending operation blocks a cheap virtual thread instead of a pool worker. On older runtimes it schedules on
ForkJoinPool.commonPool()as before. Useasync(Executor)when the application wants explicit control over threads, queueing or shutdown. The facade is additive: it uses this client instance and does not change existing blocking behavior.- Returns:
- asynchronous facade for this client
-
async
default PlccomMqttAsyncClient async(Executor executor)
Creates a CompletableFuture based comfort facade for this client using a caller-provided executor.The executor is used for protocol operations that may block, such as CONNECT, QoS acknowledgement waits, SUBSCRIBE and RECEIVE. Applications that perform many concurrent MQTT operations should provide an executor sized for that workload and shut it down according to their own lifecycle rules.
- Parameters:
executor- executor used to run asynchronous client operations- Returns:
- asynchronous facade for this client
- Throws:
NullPointerException- ifexecutorisnull
-
connect
PlccomMqttConnectResult connect() throws PlccomMqttException
Opens the socket and performs MQTT CONNECT.- Returns:
- connect result including the concrete negotiated protocol version
- Throws:
PlccomMqttException- if the connection cannot be established
-
publish
void publish(PlccomMqttPublishMessage message) throws PlccomMqttException
Publishes a message.- Parameters:
message- message to publish- Throws:
PlccomMqttException- if the publish fails
-
publish
default MqttClientPublishBuilder publish(String topic, String payload)
Creates a high-level publish operation for a UTF-8 string payload.- Parameters:
topic- MQTT topic namepayload- payload text, ornullto publish an empty payload- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
publish
default MqttClientPublishBuilder publish(String topic, byte[] payload)
Creates a high-level publish operation for a binary payload.- Parameters:
topic- MQTT topic namepayload- payload bytes, ornullto publish an empty payload- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
publish
default MqttClientPublishBuilder publish(String topic, int payload)
Creates a high-level publish operation for an integer payload.- Parameters:
topic- MQTT topic namepayload- payload value encoded as UTF-8 decimal text- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
publish
default MqttClientPublishBuilder publish(String topic, long payload)
Creates a high-level publish operation for a long payload.- Parameters:
topic- MQTT topic namepayload- payload value encoded as UTF-8 decimal text- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
publish
default MqttClientPublishBuilder publish(String topic, double payload)
Creates a high-level publish operation for a double payload.- Parameters:
topic- MQTT topic namepayload- payload value encoded as UTF-8 decimal text- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
publish
default MqttClientPublishBuilder publish(String topic, boolean payload)
Creates a high-level publish operation for a boolean payload.- Parameters:
topic- MQTT topic namepayload- payload value encoded astrueorfalse- Returns:
- publish operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, String payload)
Creates a high-level MQTT 5 request/response operation for a UTF-8 string payload.The returned builder publishes the request with MQTT 5 Response Topic and Correlation Data properties, waits for a matching response and then removes its temporary response subscription. Request/response is an MQTT 5 pattern; MQTT 3.1.1 connections do not carry these properties.
- Parameters:
topic- MQTT request Topic Namepayload- request payload text, ornullfor an empty payload- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, byte[] payload)
Creates a high-level MQTT 5 request/response operation for a binary payload.- Parameters:
topic- MQTT request Topic Namepayload- request payload bytes, ornullfor an empty payload- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, int payload)
Creates a high-level MQTT 5 request/response operation for an integer payload.- Parameters:
topic- MQTT request Topic Namepayload- request payload encoded as UTF-8 decimal text- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, long payload)
Creates a high-level MQTT 5 request/response operation for a long payload.- Parameters:
topic- MQTT request Topic Namepayload- request payload encoded as UTF-8 decimal text- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, double payload)
Creates a high-level MQTT 5 request/response operation for a double payload.- Parameters:
topic- MQTT request Topic Namepayload- request payload encoded as UTF-8 decimal text- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
request
default MqttClientRequestBuilder request(String topic, boolean payload)
Creates a high-level MQTT 5 request/response operation for a boolean payload.- Parameters:
topic- MQTT request Topic Namepayload- request payload encoded astrueorfalse- Returns:
- request/response operation builder
- Throws:
NullPointerException- iftopicisnull
-
subscribe
void subscribe(PlccomMqttSubscription subscription) throws PlccomMqttException
Subscribes to a topic filter.- Parameters:
subscription- subscription request- Throws:
PlccomMqttException- if the subscribe fails
-
unsubscribe
void unsubscribe(String topicFilter) throws PlccomMqttException
Removes one topic-filter subscription.- Parameters:
topicFilter- MQTT topic filter to unsubscribe- Throws:
PlccomMqttException- if the unsubscribe failsNullPointerException- iftopicFilterisnull
-
subscribe
default MqttClientSubscribeBuilder subscribe(String topicFilter)
Creates a high-level subscribe operation for one topic filter.- Parameters:
topicFilter- MQTT topic filter- Returns:
- subscribe operation builder
- Throws:
NullPointerException- iftopicFilterisnull
-
receive
PlccomMqttPublishMessage receive(long timeoutMillis) throws PlccomMqttException
Receives the next inbound publish.- Parameters:
timeoutMillis- maximum time to wait- Returns:
- next publish, or
nullwhen the timeout expires - Throws:
PlccomMqttException- if the client is closed or interrupted
-
receiveMessage
default MqttMessage receiveMessage(long timeoutMillis) throws PlccomMqttException
Receives the next inbound publish as a comfort message.Same wait behaviour as
receive(long), but returns the type that callbacks and the asynchronous facade already hand out, so the blocking path offers the same payload helpers (payloadAsString(),payloadAsInt(), ...) without a manual conversion.- Parameters:
timeoutMillis- maximum time to wait- Returns:
- next message, or
nullwhen the timeout expires - Throws:
PlccomMqttException- if the client is closed or interrupted
-
getOptions
default PlccomMqttClientOptions getOptions()
Returns the immutable options this client was created with.Declared as a default method on purpose: an abstract method would break every existing implementation of this interface. The PLCcom clients override it; a foreign implementation that does not keeps compiling and only fails when this method is actually called.
- Returns:
- client options, never
null - Throws:
UnsupportedOperationException- if the implementation does not expose its options
-
setDiagnosticLevel
void setDiagnosticLevel(PlccomMqttDiagnosticLevel level)
Changes the SDK diagnostic level of this client at runtime. The new level applies immediately to subsequent diagnostic events, so verbosity can be raised or lowered on a live connection without reconnecting; the setting also survives automatic reconnects.- Parameters:
level- new minimum diagnostic level- Throws:
NullPointerException- iflevelisnull
-
onConnected
default PlccomMqttClient onConnected(MqttConnectedListener listener)
Registers a high-level callback for successful MQTT connections.PLCcom client implementations catch runtime exceptions thrown by the listener so application callback failures do not close the MQTT connection. Custom client implementations that do not support lifecycle callbacks may rely on this default method, which rejects the registration deterministically.
- Parameters:
listener- callback invoked after CONNACK has been accepted- Returns:
- this client for fluent setup
- Throws:
NullPointerException- iflistenerisnullUnsupportedOperationException- if the implementation does not support lifecycle callbacks
-
onDisconnected
default PlccomMqttClient onDisconnected(MqttDisconnectedListener listener)
Registers a high-level callback for MQTT disconnect events.The callback is invoked for graceful application disconnects and for lost connections detected while reading from the broker or maintaining MQTT Keep Alive. Runtime exceptions thrown by the listener are caught by PLCcom client implementations.
- Parameters:
listener- callback invoked when the connection closes- Returns:
- this client for fluent setup
- Throws:
NullPointerException- iflistenerisnullUnsupportedOperationException- if the implementation does not support lifecycle callbacks
-
onReconnectFailed
default PlccomMqttClient onReconnectFailed(MqttReconnectFailedListener listener)
Registers a high-level callback for failed bounded automatic reconnect.This callback is only meaningful for clients created with automatic reconnect enabled. Runtime exceptions thrown by the listener are caught and the original reconnect failure is still reported to the blocking operation that triggered reconnect.
- Parameters:
listener- callback invoked when reconnect gives up- Returns:
- this client for fluent setup
- Throws:
NullPointerException- iflistenerisnullUnsupportedOperationException- if the implementation does not support lifecycle callbacks
-
onDiagnostic
default PlccomMqttClient onDiagnostic(PlccomMqttDiagnosticListener listener)
Registers a diagnostic listener.Diagnostics are optional SDK-to-application events for background errors and protected callback failures. Direct failures of client methods are still reported by their normal checked exceptions. Implementations catch runtime exceptions thrown by the diagnostic listener so logging or UI notification code cannot damage MQTT processing.
- Parameters:
listener- diagnostic listener- Returns:
- this client for fluent setup
- Throws:
NullPointerException- iflistenerisnullUnsupportedOperationException- if the implementation does not support diagnostic callbacks
-
disconnect
void disconnect() throws PlccomMqttExceptionSends MQTT DISCONNECT and closes the connection.- Throws:
PlccomMqttException- if disconnect transmission fails
-
isConnected
boolean isConnected()
Returns whether the client is connected.- Returns:
trueafter a successful connect and before close
-
getNegotiatedProtocolVersion
PlccomMqttProtocolVersion getNegotiatedProtocolVersion()
Returns the negotiated concrete protocol version.- Returns:
- concrete version, or
nullbefore connection
-
close
void close()
Closes the client. This method does not throw checked exceptions so it can be used safely from cleanup paths.- Specified by:
closein interfaceAutoCloseable
-
-