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:

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 .zip file on your local machine.

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:

  1. A Java class that implements com.hivemq.extension.sdk.api.ExtensionMain and provides a starting point the HiveMQ extension. For more information, see Extension Main Class.

  2. A build.gradle.kts Gradle 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

  1. build: The directory that contains all output that Gradle generates

  2. build.gradle.kts: The Gradle buildscript

  3. settings.gradle.kts: The Gradle settings

  4. gradle.properties: The properties for the Gradle buildscript and settings. For example, the version of third party dependencies.

  5. src: The directory that contains all source files

  6. integrationTest: The directory that contains all integration test files

  7. main: The directory that contains all extension source files

  8. 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.

Next Steps

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: