HiveMQ Extension Gradle Plugin 2.0.0 released

The HiveMQ team is proud to present a new version of the HiveMQ Extension Gradle Plugin. This plugin 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 new version of the HiveMQ Extension Gradle Plugin that registers all the basic tasks you need from start to finish. The new version adds the following advantages:

• Improved API
• Automatic setup for integration testing

Example HiveMQ Extension build with Gradle

Let’s take a look at how to create a HiveMQ Extension with Gradle. In this example we 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

1
2
3
4
5
6
7

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

rootProject.name = "hivemq-hello-world-extension" // Used as ID of the HiveMQ Extension

build.gradle.kts

1
2
3

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

 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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.set("Hello World Extension")      // Name of the HiveMQ Extension, required
    author.set("HiveMQ GmbH")              // Author of the HiveMQ Extension, required
    priority.set(50)                       // Priority of the HiveMQ Extension, default: 0
    startPriority.set(1000)                // Start priority of the HiveMQ Extension, default: 1000
    mainClass.set("$group.HelloWorldMain") // Main class of the HiveMQ Extension, required
    sdkVersion.set("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 creates the XML file for you and fills in all the required properties. The Gradle plugin also generates the META-INF/services/com.hivemq.extension.sdk.api.ExtensionMain service descriptor file. Just specify the mainClass entry point of the Extension as shown above.

That is all you need to create a HiveMQ Extension with Gradle.

To assemble your Extension, simply execute the hivemqExtensionZip Gradle task that 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. (Gradle version 6 or higher is required)

gradle wrapper --gradle-version=7.1.1

You can build your HiveMQ Extension with:

./gradlew hivemqExtensionZip

Assemble 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.kts

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, etc. (for a detailed explanation see the Gradle documentation). (for a detailed explanation see the Gradle documentation)

build.gradle.kts

18
19
20
21

hivemqExtension.resources {
    from("LICENSE")
    from("README.md") { rename { "README.txt" } }
}

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

23
24
25
26
27
28
29
30
31
32
33
34

tasks.prepareHivemqHome {
    hivemqHomeDirectory.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
    }
}

Integration testing with the HiveMQ Testcontainer

The HiveMQ Extension Gradle Plugin 2.0.0 adds an integrationTest task that executes tests from the integrationTest source set.

hivemq-hello-world-extension
 ├─ src
 │   ├─ main             
 │   │   ├─ java         // Your code
 │   │   └─ resources    
 │   ├─ integrationTest           
 │   │   ├─ java         // Your integration testing code
 │   │   └─ resources    
 │   └─ test
 │   ...
 ├─ build.gradle.kts
 └─ settings.gradle.kts

Add the HiveMQ Testcontainer as dependency

Integration test dependencies are defined via the integrationTestImplementation, integrationTestRuntimeOnly, etc. configurations. So you can add all the dependencies you need for integration testing:

build.gradle.kts

23
24
25
26

dependencies {
    integrationTestImplementation("com.hivemq:hivemq-mqtt-client:1.2.2")
    integrationTestImplementation("com.hivemq:hivemq-testcontainer-junit5:1.3.3")
}

Implement your integration test

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

class ExampleIT {

    @RegisterExtension
    public final @NotNull HiveMQTestContainerExtension hivemqTestcontainer =
            new HiveMQTestContainerExtension()
                    .withExtension(new File("build/hivemq-extension-test/<id-of-your-extension>"));

    @Test
    @Timeout(value = 5, unit = TimeUnit.MINUTES)
    void test() {
        // implement your integration test here
    }
}

Conclusion

The HiveMQ Extension Gradle plugin version 2.0.0 further simplifies developing, debugging, and building HiveMQ Extensions with Gradle. With version 2.0.0 the ability for integration testing without boilerplate is added.

Have a great day,

Yannick from the HiveMQ Team

About Yannick Weber

Yannick is a Senior Software Engineer and one of the core members of HiveMQ’s product development team. He is focusing on quality development of HiveMQ’s many tools and extensions. In addition, he is the maintainer of the HiveMQ module in the testcontainers-java project.

Contact Yannick