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('4.9.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('4.9.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 |
|
Assembles the jar of the HiveMQ extension |
|
Generates the service descriptor of the HiveMQ extension |
|
Generates the xml descriptor of the HiveMQ extension |
|
Assembles the zip distribution of the HiveMQ extension |
Requirements
-
Gradle 6.x or higher is required
-
Do not create descriptor files by yourself (
hivemq-extension.xml
orcom.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:
HiveMQ automatically recognizes and starts your new extension.
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