Build Your HiveMQ Extensions with Gradle
Now, in addition to Maven, you can use the Gradle build tool to create HiveMQ extensions. This new option lets you take advantage of everything Gradle has to offer. For example,
Incremental builds,
Better dependency management, and
Scripting your build configuration.
To make it even easier to set up a complete Gradle build pipeline for your HiveMQ extension, we’ve created a Gradle plugin that registers all the basic tasks you need from start to finish.
Example HiveMQ Extension Build with Gradle
Let’s take a look at how to create a HiveMQ extension with Gradle. In this example I use the Kotlin DSL for the Gradle scripts.
First, to apply the com.hivemq.extension Gradle plugin, add the following lines to the build files that are located at the root of your project.
settings.gradle.kts
pluginManagement {
plugins {
id("com.hivemq.extension") version "1.0.0"
}
}
rootProject.name = "hivemq-hello-world-extension" // Used as ID of the HiveMQ extensionbuild.gradle.kts
plugins {
id("com.hivemq.extension")
}Once you apply the HiveMQ extension plugin to your project, you can configure all the important HiveMQ extension properties directly in your build file.
build.gradle.kts
group = "com.hivemq.extensions"
version = "4.25.0" // Version of the HiveMQ extension, required
description = "HiveMQ 4 Hello World Extension - a simple reference for all extension developers"
hivemqExtension {
name = "Hello World Extension" // Name of the HiveMQ extension, required
author = "HiveMQ GmbH" // Author of the HiveMQ extension, required
priority = 50 // Priority of the HiveMQ extension, default: 0
startPriority = 1000 // Start priority of the HiveMQ extension, default: 1000
mainClass = "$group.HelloWorldMain" // Main class of the HiveMQ extension, required
sdkVersion = "4.25.0" // Version of the HiveMQ extension SDK, default: latest.integration
}You may notice strong similarities between the hivemq-extension.xml you used to create and bundle into your extension zip. The Gradle plugin takes care of creating the file for you and filling it with all the required properties. Additionally, the gradle plugin generates the service descriptor file META-INF/services/com.hivemq.extension.sdk.api.ExtensionMain. Just specify the mainClass entry point of the extension as shown above.
That is all you need to create a HiveMQ extension with Gradle.
In order to assemble your extension, simply execute the hivemqExtensionZip Gradle task which executes all the other tasks needed to create the finalized zip of your HiveMQ extension. When the task is done, the zip file appears in the build/hivemq-extension folder of your project folder.
We recommend using a Gradle wrapper so that every build uses the same Gradle version. To initialize the Gradle wrapper, execute the following command in your project folder. At least Gradle version 6 is required.
gradle wrapper --gradle-version=6.6.1You can build your HiveMQ extension with:
./gradlew hivemqExtensionZipAssemble Additional Files Into Your Extension Folder
Files inside the src/hivemq-extension folder are automatically included in your HiveMQ extension zip.
hivemq-hello-world-extension
├─ src
│ ├─ hivemq-extension // Everything here is added to the extension folder in the zip
│ ├─ main // Everything here is used to generate the jar archive
│ │ ├─ java // Your code
│ │ └─ resources // Resources inside the jar, do not put resources for the zip here
│ └─ test
│ ...
├─ build.gradle.kts
└─ settings.gradle.ktsIf you want to add files from other locations to the zip, you can use the hivemqExtensionResources Gradle task. Due to Gradle’s scripting nature, you can also include files that your own custom tasks create.
build.gradle.kts
tasks.hivemqExtensionResources {
from("example.txt") { rename { "example.info" }.into("subfolder") }
from(tasks.named("generateSamples")) { into("samples") }
}Debug Your Extension Directly from Your IDE
The HiveMQ Gradle plugin lets you run your extension with HiveMQ directly from your IDE. This enables you to quickly debug and test your extension. To use this feature, you need to download HiveMQ Enterprise or Community Edition first and unzip it somewhere suitable.
For example, add the following lines to your build file.
build.gradle.kts
tasks.prepareHivemqHome {
hivemqFolder.set("/your/path/to/hivemq-4.25.0") // The home folder of your HiveMQ EE or CE
// You can add any files: configs, licenses, other extensions, etc.
from("src/test/resources/config.xml") { into("conf") }
from("src/test/resources/other-extension") { into("extensions") }
}
tasks.runHivemqWithExtension {
debugOptions {
enabled.set(true) // This enables you to attach a debugger to your HiveMQ instance
}
}Conclusion
The HiveMQ extension Gradle plugin enables you to easily develop, debug, and build your HiveMQ extensions with Gradle. Simply configure some metadata and make use of Gradle’s flexible scripting capabilities for more complicated extension builds.
Have a great day,
Lukas from the HiveMQ Team
Check out our blog HiveMQ Extension Gradle Plugin 2.0.0 Released, where we discuss a new version of the HiveMQ Extension Gradle Plugin.
Lukas Brandl
Lukas Brandl is Senior Software Engineer at HiveMQ. He is with HiveMQ for more than a decade and plays a key role in product development and product engineering.
