PLCcom

First steps PLCcom MQTT Broker for Java

The PLCcom MQTT Broker module is the Java API for applications that host an MQTT broker. It accepts MQTT 3.1.1 and MQTT 5.0 clients, routes messages, handles retained state and sessions, and exposes application hooks for access validation, TLS, Enhanced AUTH, custom state storage and read-oriented Admin snapshots.

Start here: use PlccomMqttBrokerFactory.builder() when an application should start an embedded or standalone broker. The broker can accept external network MQTT clients and can also publish/listen from the owning Java process without creating an extra network client.

PLCcom MQTT Broker overview with listeners, broker core, Java embedding and extension points.

How to read this API

The high-level broker API is organized around operating a broker from a Java application. Configure the listeners that should accept network clients, decide which security and storage extension points belong to your system, then start the broker and inspect runtime state through Admin snapshots and diagnostics. Embedded publishing and local listeners are first-class broker features: they are meant for applications that already own process data and want to expose or receive MQTT messages without creating an additional network client.

Network side
Configure one or more TCP, TLS, WebSocket or Secure WebSocket listeners. Each listener accepts MQTT 3.1.1 and MQTT 5.0 clients according to its configured transport and security rules.

Broker runtime
The broker handles CONNECT, subscriptions, publishes, retained messages, sessions, QoS handshakes, access decisions and diagnostic events.

Java embedding
The owning application can publish into the broker, receive local listener callbacks, inspect Admin snapshots and provide custom validators, authenticators or stores.

Main entry points

Entry point	Use it when	Typical next step
`PlccomMqttBrokerFactory.builder()`	You create a new standalone or embedded broker from readable high-level settings.	Add listeners, configure security, diagnostics and optional store, then call `start()`.
`PlccomMqttBroker`	You operate the running broker from Java code.	Publish application data, register local listeners, inspect Admin state or close the broker.
`PlccomMqttBrokerListenerOptions`	You need more than the simple default listener setup.	Configure protocol, bind address, port, TLS, WebSocket path and listener limits.
`MqttBrokerPublishBuilder`	The Java application publishes data into the broker.	Set payload, QoS, retained flag, JSON or MQTT 5 metadata and finish with `send()`.
`MqttBrokerListenBuilder`	The Java application should react to messages received by the broker.	Register a topic filter and keep the callback fast and thread-safe.
`MqttBrokerAdmin`	You need runtime visibility without changing MQTT state.	Read snapshots, counters, sessions, retained entries and bound listener information.

Maven dependency


<dependency>
    <groupId>com.indi-an.plccom</groupId>
    <artifactId>plccom-mqtt-broker</artifactId>
    <version>2.x.x</version>
</dependency>

Replace 2.x.x with the concrete PLCcom MQTT v2 release version you use. If the same application also needs to behave as an MQTT client, add plccom-mqtt-client explicitly as a second dependency. Core is resolved transitively.

Minimal standalone broker

This example starts a broker on the default MQTT TCP port. Port 1883 is the conventional unencrypted MQTT port. For production, configure bind addresses, TLS, access validation and persistence according to your deployment rules.

The two empty strings are the license fields, shown blank on purpose: they turn on evaluation mode, so this example runs for 15 minutes during a debug session with the full functional scope. Fill both in from your license for uninterrupted work.


import com.plccom.mqtt.broker.PlccomMqttBroker;
import com.plccom.mqtt.broker.PlccomMqttBrokerFactory;

public class MinimalMqttBroker {
    public static void main(String[] args) throws Exception {
        try (PlccomMqttBroker broker = PlccomMqttBrokerFactory.builder("", "")
                .tcpPort(1883)
                .start()) {

            System.out.println("Broker is running on port " + broker.getBoundPort());
            Thread.sleep(60000L);
        }
    }
}

Evaluation mode

Pass two empty strings as the license fields and the library runs for 15 minutes during a debug session with full functionality – enough to open a connection and read values. This lets you try the library before you register. For uninterrupted work, generate a free trial license (14 days): https://www.indi-an.com/en/plccom/mqtt/mqtt-download/

When the evaluation period ends, operation stops: an open connection is disconnected and a running broker halts. The same applies when a time-limited license expires. The library never terminates your application.

License data does not belong in source code. Use configuration files, environment variables or a secret manager to load it at runtime.

Listener model

Listener type	When to use it	Typical endpoint
TCP	Plain MQTT inside trusted networks or during simple local tests.	`mqtt://host:1883`
TLS	Encrypted MQTT with server certificate and optional client certificate.	`mqtts://host:8883`
WebSocket	MQTT through WebSocket-aware infrastructure.	`ws://host:8080/mqtt`
Secure WebSocket	MQTT over TLS-protected WebSocket.	`wss://host:8443/mqtt`

Choosing the right broker feature

Feature	Best for	What to watch
Plain listener	Local tests, trusted lab networks and simple interoperability checks.	Do not use unencrypted public endpoints for production credentials or sensitive payloads.
TLS or WSS listener	Production traffic, certificate-based server identity and encrypted transport.	Keep the PKI store clean and decide deliberately which remote certificates are trusted.
Access validator	Username/password checks, topic authorization and certificate login mapping.	Slow external checks reduce connection and publish throughput.
Embedded publish	Publishing values that already exist inside the owning Java application.	This is application-side trusted code; validate business rules before calling the broker API.
Custom store	Durable retained messages and persistent sessions controlled by your application.	The store owns durability, thread safety, backup, encryption and performance.

Embedded application publishing and listening

An embedded broker can publish data from the owning Java process. This is useful when values already exist in memory and should be exposed to MQTT subscribers without creating a separate network publisher. The same broker can also call a Java listener when matching MQTT messages arrive.


broker.publish("machine/line1/state", "running")
        .qos1()
        .retain()
        .contentType("text/plain")
        .send();

The local publish is trusted in-process application code. It validates the MQTT Topic Name and routes through retained-message handling, network delivery and local listeners, but it is not checked by the network access validator.

Extension points

Extension point	What happens when you provide it	What happens when you do not provide it
Access validator	Your implementation decides whether network clients may CONNECT, PUBLISH, SUBSCRIBE or UNSUBSCRIBE.	The broker uses the default open policy and allows anonymous access.
Enhanced authenticator	Your implementation handles MQTT 5 Enhanced AUTH challenge/response data.	Enhanced AUTH is disabled. Clients that require an unsupported method are rejected according to MQTT 5 behavior.
Custom store	Your implementation owns retained-message and persistent-session storage. It must handle durability, thread safety, backup, encryption and latency.	The broker keeps retained messages and sessions in memory.
TLS and PKI	The broker exposes secure listeners with server identity, trust rules, protocol restrictions and optional client certificates.	Plain TCP or WebSocket listeners are used, depending on configured listeners.
Diagnostics	Your listener receives warnings and errors from runtime paths.	The broker keeps running where recovery is safe and reports fewer details to the application.

Performance: access validators, Enhanced AUTH callbacks and custom stores are called from broker protocol paths. Slow database calls, remote service calls or blocking file I/O can reduce connection throughput and message latency.

Admin snapshots

The Broker Admin API is intentionally read-oriented. It can show bound ports, running state, sessions, retained messages, queued messages and diagnostic counters. The current reset operation resets safe diagnostic counters only; it does not disconnect clients or delete MQTT state.


System.out.println("Retained messages: "
        + broker.admin().snapshot().getRetainedMessages().size());

broker.admin().resetCounters();

Examples and workshops

Runnable broker examples are maintained outside the API Javadocs in the public example repository: https://github.com/Indi-An/PLCcom-mqtt-example-java. Use them when you want complete, executable learning scenarios for listener setup, TLS/WSS, embedded publishing, embedded listeners, Admin snapshots, access validation, custom stores and diagnostics.

Back to PLCcom MQTT SDK overview.

Packages
Package	Description
com.plccom.mqtt.broker	Public PLCcom MQTT broker lifecycle API.

PLCcom MQTT Broker Java class library documentation