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 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. Use async(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 - if executor is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 String payload)
        Creates a high-level publish operation for a UTF-8 string payload.
        Parameters:
        topic - MQTT topic name
        payload - payload text, or null to publish an empty payload
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 byte[] payload)
        Creates a high-level publish operation for a binary payload.
        Parameters:
        topic - MQTT topic name
        payload - payload bytes, or null to publish an empty payload
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 int payload)
        Creates a high-level publish operation for an integer payload.
        Parameters:
        topic - MQTT topic name
        payload - payload value encoded as UTF-8 decimal text
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 long payload)
        Creates a high-level publish operation for a long payload.
        Parameters:
        topic - MQTT topic name
        payload - payload value encoded as UTF-8 decimal text
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 double payload)
        Creates a high-level publish operation for a double payload.
        Parameters:
        topic - MQTT topic name
        payload - payload value encoded as UTF-8 decimal text
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • publish

        default MqttClientPublishBuilder publish​(String topic,
                                                 boolean payload)
        Creates a high-level publish operation for a boolean payload.
        Parameters:
        topic - MQTT topic name
        payload - payload value encoded as true or false
        Returns:
        publish operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload text, or null for an empty payload
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload bytes, or null for an empty payload
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload encoded as UTF-8 decimal text
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload encoded as UTF-8 decimal text
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload encoded as UTF-8 decimal text
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 Name
        payload - request payload encoded as true or false
        Returns:
        request/response operation builder
        Throws:
        NullPointerException - if topic is null
      • 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 - if topicFilter is null
      • 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 null when 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 - if level is null
      • 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 - if listener is null
        UnsupportedOperationException - 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 - if listener is null
        UnsupportedOperationException - 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 - if listener is null
        UnsupportedOperationException - 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 - if listener is null
        UnsupportedOperationException - if the implementation does not support diagnostic callbacks
      • isConnected

        boolean isConnected()
        Returns whether the client is connected.
        Returns:
        true after a successful connect and before close
      • getNegotiatedProtocolVersion

        PlccomMqttProtocolVersion getNegotiatedProtocolVersion()
        Returns the negotiated concrete protocol version.
        Returns:
        concrete version, or null before 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:
        close in interface AutoCloseable