Hands-on MQTT for Java developers — a comfortable high-level Client and an embeddable Broker.
MQTT looks simple — connect, publish, subscribe — but real projects get concrete fast: which QoS should this message use, does a late subscriber see the last value, what happens when a device drops off the network, how do I attach a content type or a correlation id, and how do I secure the transport with TLS or a client certificate?
This repository is a practical learning path that answers those questions with small, readable, runnable programs. Each workshop is a self-contained scenario: it prints a framed explanation, runs a real MQTT flow against a broker, checks the result and tells you exactly what to expect. When you outgrow the console examples, two full reference applications (a Client tool and a Broker tool) let you click through the same features by hand.
Everything here uses the high-level PLCcom MQTT API only — the comfortable Client and Broker surface, not the wire protocol.
Nothing on this list is just a claim — every capability is demonstrated by a runnable workshop in this repository (the workshop maps below show exactly which one).
Protocol & Messaging
- MQTT 3.1.1 and 5.0 over
mqtt://,mqtts://,ws://andwss:// - QoS 0 / 1 / 2 and topic wildcards (
+,#) - Retained messages including retained deletion
- Last Will — fired on an ungraceful drop, suppressed by a clean disconnect
- All MQTT 5 message properties: content type, payload format, user properties, message expiry, response topic, correlation data and topic alias
- MQTT 5 subscription options: subscription identifiers, no local, retain as published, retain handling
- Request / response as one high-level call, and JSON mapping (publish a Java object, read it back as the same type)
Client
- Persistent sessions with offline queueing and session expiry
- Automatic reconnect with lifecycle callbacks (connected / disconnected / reconnect failed)
- Async API (
CompletableFuture) alongside the blocking API - Shared subscriptions to load-balance a topic across workers
- TLS / mTLS / WSS with trust and key stores, hostname verification and an optional custom remote-certificate validator
- MQTT 5 enhanced authentication (application-owned challenge/response)
- Structured diagnostics with level filtering — and every call returns a checkable OperationResult/Quality
Broker
- Runs standalone or embedded inside your Java application
- Multiple listeners side by side: TCP, WebSocket, TLS and secure WebSocket — with per-port server certificates
- In-process publish and listen — exchange data with connected clients without a network client
- Access control (application-owned validator for CONNECT / PUBLISH / SUBSCRIBE) and enhanced authentication
- PKI store for certificate management (own / trusted / issuers / rejected)
- Custom state stores — keep retained messages and sessions in your own durable storage
- Admin snapshots and statistics, plus structured diagnostics
| Area | What it teaches | Typical use |
|---|---|---|
| Client Workshops | Connect, QoS, retained messages, Last Will, all MQTT 5 properties and subscription options, request/response, JSON, sessions, reconnect, async, shared subscriptions, TLS/mTLS/WSS and diagnostics. | Learn the client side step by step, from a first connection to a secured, resilient application. |
| Broker Workshops | Standalone and embedded brokers, multiple listeners, TLS/WSS with per-port certificates, in-process publish/listen, retained state, access control, authentication & PKI, custom stores, admin & diagnostics. | Host your own MQTT broker inside a Java product, edge gateway or test environment. |
| Reference Applications | Two complete Swing applications — a Client tool and a Broker tool — with DE/EN UI and integrated help. | Manual testing, demos and troubleshooting against real devices, Mosquitto or each other. |
| PLCcom.Console | The shared Swing console window used by the workshops. | Keeps workshop output readable without duplicating console code. |
pom.xml reactor: builds the modules below in the right order
PLCcom.Console/ shared Swing console window
Workshops/
Client/ 13 client workshops (grouped 1x..4x)
gettingstarted/ mqtt5/ resilience/ security/
Broker/ 10 broker workshops (grouped 1x..4x)
basics/ embedded/ security/ service/
Reference_Applications/
Client/ full Swing client tool
Broker/ full Swing broker tool
assets/ overview graphic
README.md this file
The root pom.xml is a thin reactor: its only job is to build the modules in order — the shared PLCcom.Console first, then the workshops and reference applications. It sets no versions and no dependencies, so you can just as well build, import or run any single module on its own.
Each workshop class is numbered _1x, _2x, _3x, _4x. The tens digit is the topic group (shown by the package name), the ones digit is the order inside the group — so the folder tree already reads like the learning path.
Client — start here if you connect to a broker:
| Step | Workshop | Why |
|---|---|---|
| 1 | gettingstarted/_11_FirstConnection |
The smallest complete rhythm: connect, subscribe, publish, receive, close. |
| 2 | gettingstarted/_12_PublishSubscribeAndQos |
Choose QoS 0/1/2 deliberately and use topic wildcards. |
| 3 | gettingstarted/_13_RetainedMessagesAndLastWill |
Remember state and announce unexpected disconnects. |
| 4 | mqtt5/_21..._24 |
MQTT 5 properties, subscription options, request/response and JSON. |
| 5 | resilience/_31..._33 |
Sessions, reconnect, async API and shared subscriptions. |
| 6 | security/_41_SecureConnection, _42_DiagnosticsAndErrorHandling & _43_EnhancedAuthentication |
TLS/mTLS/WSS, structured diagnostics and MQTT 5 enhanced authentication. |
Broker — start here if you host a broker:
| Step | Workshop | Why |
|---|---|---|
| 1 | basics/_11_FirstBroker |
Start the smallest standalone broker and read its bound port. |
| 2 | basics/_12..._14 |
Multiple listeners, secure listeners, and all four transports with per-port certificates. |
| 3 | embedded/_21..._22 |
Own the broker lifecycle in Java; publish and listen in-process. |
| 4 | security/_31..._32 |
Access control, authentication and PKI. |
| 5 | service/_41..._42 |
Durable custom stores, admin snapshots and diagnostics. |
The two sides are independent, so you can mix and match — a PLCcom client against a PLCcom broker, a PLCcom client against Mosquitto, or a client tool against the broker tool. A convenient pairing to see the whole picture:
- Start Broker Workshop
basics/_11_FirstBroker(or a local Mosquitto onmqtt://localhost:1883). - Run Client Workshop
gettingstarted/_11_FirstConnectionand point it at that broker. - For TLS, pair Broker
basics/_13_SecureListenerswith Clientsecurity/_41_SecureConnection.
Every client workshop reads its broker address from a visible BROKER_ENDPOINT constant and can be overridden without editing the file:
-Dplccom.mqtt.workshop.endpoint=mqtt://localhost:1883The examples use the PLCcom MQTT Java packages:
<!-- Client-side applications -->
<dependency>
<groupId>com.indi-an.plccom</groupId>
<artifactId>plccom-mqtt-client</artifactId>
<version>2.1.2</version>
</dependency>
<!-- Broker-side applications -->
<dependency>
<groupId>com.indi-an.plccom</groupId>
<artifactId>plccom-mqtt-broker</artifactId>
<version>2.1.2</version>
</dependency>Both artifacts are on Maven Central and pull in plccom-mqtt-core (and gson) transitively, so you only declare the side you use.
Each module is self-contained. Open any module's own pom.xml and the SDK version is written right there, at the dependency — there is no hidden parent that controls it. To target another PLCcom MQTT release, change the <version> in the module you build (the workshop or reference-application module you are using).
The root pom.xml is only a reactor — it lists the modules and builds them in the right order (the shared PLCcom.Console first). It never overrides the SDK version, which stays visible in each module's own pom.xml. In your IDE you import the module folders, not the root: with an Eclipse workspace at the repository root, m2e skips the root aggregator (the harmless "existing workspace folder" note) and imports each module as its own project — exactly as in the sibling PLCcom OPC UA example repository.
- Java 11 or newer
- Maven 3.8 or newer
- A valid PLCcom MQTT license user name and serial number (see the note in each workshop)
- A running MQTT broker for the client workshops (a broker workshop, the broker tool, or Mosquitto)
- A desktop environment for the Swing console and the reference applications
git clone https://github.com/Indi-An/PLCcom-mqtt-example-java.git
cd PLCcom-mqtt-example-javaEvery workshop shows exactly where the credentials go — a visible block near the top of each class, shipped blank:
private static final String LICENSE_USER = "";
private static final String LICENSE_SERIAL = "";You can start without a license. Those two empty strings are what turns on evaluation mode: the library then runs for 15 minutes during a debug session with the full functional scope — enough to bring up a connection and exchange messages. So you can try the workshops out before you register. (Leaving out the license(...) call altogether is a different thing and does not work — evaluation mode has to be asked for.)
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.
For uninterrupted work you need a PLCcom MQTT license (a user name and a serial number). Two ways to get one:
- Free trial — generate a 14-day trial license on the PLCcom MQTT download page.
- Purchase — buy a full license on the PLCcom MQTT buy page.
Fill both values in from your license (trial or purchased). A client-only license is enough for the client workshops; broker workshops need a broker (or broker+client) license. Both values can also come from configuration or an environment variable — license data does not belong in source code you publish.
One command in the repository root builds everything — the reactor builds the shared PLCcom.Console first, then the workshops and reference applications:
mvn clean installPrefer a single module? Point Maven at that module's own pom.xml, e.g. mvn -f Workshops/Client/pom.xml compile (the shared console must be installed once first: mvn -f PLCcom.Console/pom.xml install).
Open the workshop class in your IDE and run its main() method, or use Maven. Build once first (step 3), then start a broker and a client:
# Terminal 1 - broker
mvn -f Workshops/Broker/pom.xml exec:java -Dexec.mainClass=com.plccom.mqtt.examples.broker.basics._11_FirstBroker
# Terminal 2 - client (point it at the broker or a local Mosquitto)
mvn -f Workshops/Client/pom.xml exec:java -Dexec.mainClass=com.plccom.mqtt.examples.client.gettingstarted._11_FirstConnectionRun a reference application the same way:
mvn -f Reference_Applications/Client/pom.xml exec:java
mvn -f Reference_Applications/Broker/pom.xml exec:java| # | Workshop | Short description |
|---|---|---|
| 11 | First Connection | Connect, protocol selection, Topic Name vs Topic Filter, one QoS 1 round trip. |
| 12 | Publish, Subscribe & QoS | QoS 0/1/2 explained and topic wildcards on one subscription. |
| 13 | Retained Messages & Last Will | Set, read and delete retained state; fire and suppress a Last Will. |
| 21 | MQTT 5 Message Properties | Content Type, Payload Format, User Properties, Message Expiry, Topic Alias. |
| 22 | MQTT 5 Subscription Options | Subscription Identifier, No Local, Retain As Published, Retain Handling. |
| 23 | Request / Response | Response Topic and Correlation Data with a visible responder client. |
| 24 | JSON Mapping | Publish a Java object as JSON and read it back as the same type. |
| 31 | Sessions, Reconnect & Lifecycle | Persistent session, offline queue, automatic reconnect, lifecycle callbacks. |
| 32 | Async API | The same MQTT flow using non-blocking CompletableFuture calls. |
| 33 | Shared Subscriptions | Load-balance a job stream across two workers. |
| 41 | Secure Connection | TLS, WSS and mutual TLS with a client-side trust/key store. |
| 42 | Diagnostics & Error Handling | Diagnostic listener, level filtering, Quality checks and error handling. |
| 43 | Enhanced Authentication | Client-side MQTT 5 enhanced authentication: method + token and AUTH challenges (pairs with Broker 32). |
| # | Workshop | Short description |
|---|---|---|
| 11 | First Broker | The smallest standalone broker; start it, read the port, stop it cleanly. |
| 12 | Listeners & Bind Addresses | Several TCP ports plus a WebSocket listener on one broker. |
| 13 | Secure Listeners | Plain TCP + TLS (mqtts) + secure WebSocket (wss) with an auto-created certificate. |
| 14 | All Listener Types | All four transports on one broker, with a per-port certificate. |
| 21 | Embedded Broker in a Java App | Own the lifecycle; publish and listen in-process, with options, batch and JSON. |
| 22 | Retained Messages & Sessions | Retained replay and deletion; session/queue behavior explained. |
| 31 | Access Control | An access validator for CONNECT/PUBLISH/SUBSCRIBE with deny-by-default. |
| 32 | Authentication & PKI | Username/password, MQTT 5 enhanced authentication and where PKI/mTLS fit. |
| 41 | Custom Stores | Move retained/session state into your own durable storage. |
| 42 | Admin & Diagnostics | Read-only admin snapshots, safe counter reset and structured diagnostics. |
The security workshops use TLS to protect the transport. The broker owns a server certificate; the client uses a trust store to verify it, and optionally a key store to authenticate itself (mutual TLS). Broker certificates can be created on demand in a local PKI folder or assigned per port, so one broker can present different identities on different ports.
The generated PKI/TLS folders are ignored by Git on purpose: they are local runtime material, not source code. Some workshops relax hostname or certificate checks to keep the flow readable — that is convenient for learning, not a production security policy. For the full picture see the official Security Guide.
The two Swing tools are complete, clickable versions of the same features:
- Client Tool — connect to any broker, publish/subscribe, try QoS 2, retained messages, MQTT 5 request/response, subscription identifiers, TLS and diagnostics.
- Broker Tool — start a configurable broker with TCP/WS/TLS/WSS listeners, publish and listen in-process, review statistics and diagnostics, and try access validation.
Both ship with a German/English interface and integrated help.
The complete PLCcom MQTT documentation lives at docs.plccom.net.
Guides (PDF, English)
- First Steps — install, license and your first MQTT program
- Appendix A — Security Guide — TLS, mTLS, WSS and PKI
- Appendix B — Client Guide — the full client API
- Appendix C — Broker Guide — the full broker API
API reference (Javadoc)
Examples License — all example sources in this repository are released under the MIT License. You may use, modify and distribute them according to the license terms.
PLCcom Library License — the PLCcom MQTT library itself is proprietary software and is not part of the MIT license. To use the SDK in your own applications you need a valid PLCcom MQTT license and must accept the applicable EULA. More information: www.indi-an.com.
These examples are written for learning, integration tests and manual validation. Do not use them unchanged in production, safety-critical or industrial environments. Review topics, QoS, retained state, timeouts, TLS settings, certificate trust and authorization logic before connecting to real equipment. Use at your own risk.
All product names, company names and trademarks referenced in this repository are trademarks or registered trademarks of their respective owners. Their use is solely for identification and interoperability documentation.