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.
Start with the HiveMQ Hello World Extension as a Template
To develop your first HiveMQ Extension with Gradle, you can use the HiveMQ Hello World Extension as a template. The HiveMQ Hello World Extension sets up everything you need for you:
Example for integration testing with the HiveMQ Testcontainer
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.
Use the Extension as a GitHub Template
Use the HiveMQ Hello World Extension as a GitHub Template to instantly create a GitHub repository with your extension. You can then checkout the repository on your local machine.
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
Develop Your HiveMQ Extension
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.
To get an idea of all the services and events you can leverage in your HiveMQ extension, see Services, Registries, and Interceptors.
Java Project Structure
The HiveMQ Hello World Extension is a Java project that includes the minimum elements that a HiveMQ extension requires:
A Java class that implements
com.hivemq.extension.sdk.api.ExtensionMainand provides a starting point the HiveMQ extension. For more information, see Extension Main Class.
build.gradle.ktsGradle file that correctly configures the HiveMQ Gradle plugin. For more information, see Kotlin DSL.
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) `-- java
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.|
Test Your HiveMQ Extension
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.
Debug Your HiveMQ Extension
You can debug your HiveMQ Extension during runtime with an IDE of your choice:
Debug with the HiveMQ Gradle Plugin
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.
Debug with the HiveMQ Testcontainer
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: