Extension Quick Start Guide with Gradle
This quick start guide covers the basics that you need to get started with extension development for HiveMQ with the flexible and extensible open-source build automation tool Gradle.
To create your first HiveMQ extension with Gradle, simply follow the step-by-step instructions that are provided in the HiveMQ Hello World Extension README file of the GitHub repository.
If you prefer not to create a GitHub repository, you can download the HiveMQ Hello World Extension zip archive as a staring point for your extension development.
To download the archive, select Code| Download ZIP on the HiveMQ Hello World Extension GitHub repository and extract the
.zip file on your local machine.
Once you create your Hello World Extension Java project, you can use the project as a basis to implement custom logic for your individual use case.
The HiveMQ Hello World Extension is a Java project that includes the minimum elements that a HiveMQ extension requires:
A typical project contains the following files and directories:
|-- build (1)
|-- build.gradle.kts (2)
|-- settings.gradle.kts (3)
|-- gradle.properties (4)
`-- src (5)
|-- integrationTest (6)
| |-- java
| `-- resources
|-- main (7)
| `-- java
`-- test (8)
build: The directory that contains all output that Gradle generates
build.gradle.kts: The Gradle buildscript
settings.gradle.kts: The Gradle settings
gradle.properties: The properties for the Gradle buildscript and settings. For example, the version of third party dependencies.
src: The directory that contains all source files
integrationTest: The directory that contains all integration test files
main: The directory that contains all extension source files
test: The directory that directory contains all unit-test files
|HiveMQ 4 and the HiveMQ Extension SDK support Extension Hot Reload. This functionality allows you to add and remove extensions to HiveMQ during runtime.
When you develop an extension, regular testing and debugging are fundamental parts of the process. Testing helps you identify any bugs or errors in your extension before you deploy to production.
The HiveMQ Testcontainer gives you the tools you need to automatically deploy and run your extension on the fly inside a Docker container, while running a JUnit Test.
For step-by instructions on how to use the HiveMQ Testcontainer, see Test HiveMQ Extensions.
You can debug your HiveMQ Extension during runtime with an IDE of your choice:
To facilitate plugin development and provide a more convenient way to debug your extensions, HiveMQ created the HiveMQ Gradle plugin.
Our Gradle plugin gives you two key advantages:
Easily run your extensions on HiveMQ for testing purposes
Efficiently debug your extension
For step-by-step instructions on how to debug a custom HiveMQ extension, see Debug Your HiveMQ Extension with the HiveMQ Gradle Plugin.
The HiveMQ Test Container to can also simplify your extension debugging process.
For more information, see Debug with the HiveMQ Testcontainer.
To get all the details on the HiveMQ Extension SDK API, see our JavaDoc.
To familiarize yourself further with the concepts used in HiveMQ extension development, see General Concepts.
For information on how to run and debug your new extension, see Develop HiveMQ Extensions with Gradle.
To learn more about the possibilities HiveMQ extensions offer and view code examples for several frequently implemented HiveMQ extension use cases, we highly recommend these Popular HiveMQ Extension Use Cases: