Develop HiveMQ Extensions with Gradle

HiveMQ provides a com.hivemq.extension Gradle plugin that eases the development of HiveMQ extensions. To develop your HiveMQ extension with Gradle, you can start with the HiveMQ Hello World Extension as a template.

Domain Specific Language (DSL)

The Gradle DSL gives you a way to form build scripts from building blocks that are defined in various plugins. For more information, see Gradle DSL and API.

Example with Groovy DSL

Content of the settings.gradle file:

pluginManagement {
    plugins {
        id 'com.hivemq.extension' version '2.0.0'
    }
}

rootProject.name = 'example-extension'

Content of the build.gradle file:

plugins {
    id 'com.hivemq.extension'
}

group 'org.example'
version '1.0.0'

hivemqExtension {
    name.set('Example Extension')
    author.set('Example Org')
    priority.set(0)
    startPriority.set(1000)
    mainClass.set('org.example.ExtensionMain')
    sdkVersion.set('latest.0')
}

Example with Kotlin DSL

Content of the settings.gradle.kts file:

pluginManagement {
    plugins {
        id("com.hivemq.extension") version "2.0.0"
    }
}

rootProject.name = "example-extension"

Content of the build.gradle.kts file:

plugins {
    id("com.hivemq.extension")
}

group = "org.example"
version = "1.0.0"

hivemqExtension {
    name.set("Example Extension")
    author.set("Example Org")
    priority.set(0)
    startPriority.set(1000)
    mainClass.set("org.example.ExtensionMain")
    sdkVersion.set('latest.0')
}

Gradle Tasks

Gradle models builds as Directed Acyclic Graphs (DAGs) of tasks. Each task is a unit of work. Based on the dependencies of the tasks, a Gradle build essentially configures a set of tasks and groups the tasks together into a DAG. Once Gradle creates the task graph, Gradle determines which tasks need to be run in which order and executes the tasks. For more information, see Task.

Build Tasks

Task

Description

hivemqExtensionJar

Assembles the jar of the HiveMQ extension

hivemqExtensionServiceDescriptor

Generates the service descriptor of the HiveMQ extension

hivemqExtensionXml

Generates the xml descriptor of the HiveMQ extension

hivemqExtensionZip

Assembles the zip distribution of the HiveMQ extension

Run/Debug Tasks

Task

Description

prepareHivemqHome

Prepares a HiveMQ home directory with the HiveMQ extension for debugging via runHivemqWithExtension

runHivemqWithExtension

Runs HiveMQ with the extension for debugging

Test Tasks

Task

Description

integrationTest

Runs integration tests, which can use the built extension under build/hivemq-extension-test

prepareExtensionTest

Prepares the HiveMQ extension for integration testing via integrationTest

Requirements

Gradle 6.x or higher is required
Do not create descriptor files by yourself (hivemq-extension.xml or com.hivemq.extension.sdk.api.ExtensionMain). They are automatically generated.
Do not add the hivemq-extension-sdk dependency yourself. It is added automatically with the right scopes.

Build Your HiveMQ Extension

Execute the hivemqExtensionZip task to build your extension:

./gradlew hivemqExtensionZip

Gradle saves your output to the build/hivemq-extension folder in a <project.name>-<project.version>.zip archive.

The zip archive contains your ready-to-deploy HiveMQ extension.

Deploy Your Extension

Once your extension is built and packaged, your fully-functional HiveMQ extension project is ready to be deployed to HiveMQ.

To deploy your HiveMQ extension to your HiveMQ instance, unzip the archive and move the extracted extension folder to the extensions folder of your HiveMQ instance:

Install Extension

HiveMQ automatically recognizes and starts your new extension.

HiveMQ Console

2018-12-11 12:18:00,248 INFO  - Started Hello World Extension:1.0.0
2018-12-11 12:18:00,248 INFO  - Extension "Hello World Extension" version 1.0.0 started successfully.

Custom Resources

You can add custom resources to the extension zip by putting files into the src/hivemq-extension directory.

Additionally, you can use hivemqExtension.resources to add custom resources from any location or Gradle task. hivemqExtension.resources is of type CopySpec, so you can use from, exclude, include, rename, and so on. For more information, see Working with Files.

Custom resource example:

tasks.hivemqExtensionResources {
    from("LICENSE")
    from("README.md") { rename { "README.txt" } }
}

Run and Debug

Use the prepareHivemqHome task to define the content of the HiveMQ home folder. It is mandatory to set the hivemqHomeDirectory property to the path of an HiveMQ directory (unzipped). The content of the HiveMQ directory is copied to build/hivemq-home. Your extension is built via the hivemqExtensionZip task and added automatically to build/hivemq-home/extensions. It is also possible to specify a custom zip via the hivemqExtensionZip property.

prepareHivemqHome is of type Copy/Sync, so you can add any additional files (configs, licenses, or other extensions). For more information, see Working with Files.

The resulting home folder can be seen in build/hivemq-home.

Prepare home folder example:

tasks.prepareHivemqHome {
    hivemqFolder.set("/path/to/a/hivemq/folder") // the only mandatory property
    from("config.xml") { into("conf") }
    from("src/test/resources/other-extension") { into("extensions") }
}

Execute the runHivemqWithExtension task to run HiveMQ with your extension from the configured home folder.

As it is a gradle JavaExec task, you can easily set debug options, system properties, JVM arguments, etc.

tasks.runHivemqWithExtension {
    debugOptions {
        enabled.set(true)
    }
}

Integration Testing

The Gradle plugin adds an integrationTest task that executes tests from the integrationTest source set.

Integration test source files are defined in src/integrationTest.
Integration test dependencies are defined via the integrationTestImplementation, integrationTestRuntimeOnly configurations.

The integrationTest task builds the extension first and unzips it to the build/hivemq-extension-test directory. The tests can then load the built extension into a HiveMQ Test Container